@nodaro/prompts 1.0.1

package/src/__tests__/parameter-registry-sync.test.ts

@@ -0,0 +1,243 @@
+/**
+ * Parameter-registry sync tests.
+ *
+ * Per CLAUDE.md "Parameter Picker Node Registration", every parameter node
+ * type must appear in 5 registries. The shared package owns 3 of them:
+ *
+ *   1. PARAMETER_NODE_TYPES set            (parameter-node-value.ts)
+ *   2. getParameterValue switch cases       (parameter-node-value.ts)
+ *   3. getParameterPromptHint switch cases  (parameter-prompt-hint.ts)
+ *
+ * (The frontend owns PARAMETER_PICKER_NODE_TYPES and parameter-picker-registry,
+ * tested separately on that side.)
+ *
+ * Drift between any of these has caused two production outages — action-fx
+ * (#1649 era) and loop-subject (#2132). Both times: the type was added to
+ * the set but the corresponding switch case was missed, so the orchestrator
+ * created a stale `pending` jobs row and threw `Unknown node type` while the
+ * picker UI silently rendered nothing.
+ *
+ * These tests drive a sample-data probe FROM the set, so adding a new
+ * parameter type without updating the helpers fails CI here.
+ */
+
+import { describe, it, expect } from "vitest"
+import { PARAMETER_NODE_TYPES, getParameterValue } from "@nodaro/shared"
+import { getParameterPromptHint } from "../parameter-prompt-hint.js"
+
+// Catalog-driven types need real ids — the prompt-hint builders look them up.
+import { FRAMINGS } from "../framing.js"
+import { LIGHTINGS } from "../lighting.js"
+import { LENSES } from "../lens.js"
+import { CAMERA_FORMATS } from "../camera-format.js"
+import { CAMERA_MOTIONS } from "../camera-motions.js"
+import { COLOR_LOOKS } from "../color-look.js"
+import { ATMOSPHERES } from "../atmosphere.js"
+import { ACTION_FX } from "../action-fx.js"
+import { STYLES } from "../style.js"
+import { SETTINGS } from "../setting.js"
+import { LOOP_SUBJECTS } from "../loop-subject.js"
+import { MATERIALS } from "../materials.js"
+import { ANIMALS } from "@nodaro/shared"
+import { VEHICLES } from "@nodaro/shared"
+import { WEAPONS } from "@nodaro/shared"
+import { FURNITURE } from "@nodaro/shared"
+import { PHOTO_GENRES } from "../photo-genre.js"
+import { BACKDROPS } from "../backdrop.js"
+import { HELD_PROPS } from "../held-prop.js"
+import { PHOTOGRAPHERS } from "../photographer.js"
+import { AESTHETICS } from "../aesthetic.js"
+import { ERAS } from "../era.js"
+import { MOODS } from "../mood.js"
+import { POSES } from "../pose.js"
+import { STYLINGS } from "../styling.js"
+import { TEMPORALS } from "../temporal.js"
+import { EXPOSURE_SETTINGS } from "../exposure-settings.js"
+import { RENDER_QUALITIES } from "../render-quality.js"
+import { COMPOSITION_EFFECTS } from "../composition-effects.js"
+import { POST_PROCESS_EFFECTS } from "../post-process-effects.js"
+import { PEOPLE } from "../person.js"
+import { MUSIC_GENRES } from "../music-genre.js"
+import { MUSIC_EMOTIONS } from "../music-mood.js"
+import { INSTRUMENTS } from "../instrumentation.js"
+import { VOICE_TIMBRES } from "../voice-character.js"
+import { VOICE_ARCHETYPES } from "../voice-delivery.js"
+import { TRANSITIONS } from "../transitions.js"
+import { CHARACTER_FX } from "../character-fx.js"
+
+// ---------------------------------------------------------------------------
+// Lookup helper — pick an id from a catalog or return a placeholder. Empty
+// catalogs fall through to a clearly invalid sentinel so the test fails
+// loudly rather than silently passing on missing fixtures.
+// ---------------------------------------------------------------------------
+function firstId(catalog: ReadonlyArray<{ readonly id: string }>): string {
+  return catalog[0]?.id ?? "<MISSING_CATALOG_ENTRY>"
+}
+
+// Pick the first FRAMINGS entry whose category === target, since FRAMINGS
+// is a flat list spanning shot-size/angle/coverage/composition/vantage.
+function firstByCategory<T extends { readonly id: string; readonly category: string }>(
+  catalog: ReadonlyArray<T>,
+  category: string,
+): string {
+  for (const e of catalog) {
+    if (e.category === category) return e.id
+  }
+  return "<MISSING_CATEGORY>"
+}
+
+// Same idea for LIGHTINGS (which is also flat with `category`).
+const FIRST_FRAMING_SHOT = firstByCategory(
+  FRAMINGS as ReadonlyArray<{ id: string; category: string }>,
+  "shot-size",
+)
+const FIRST_LIGHTING_TIME = firstByCategory(
+  LIGHTINGS as ReadonlyArray<{ id: string; category: string }>,
+  "time-of-day",
+)
+
+// ---------------------------------------------------------------------------
+// Sample data per parameter type. Drives both getParameterValue and
+// getParameterPromptHint tests.
+// ---------------------------------------------------------------------------
+const SAMPLE_DATA_BY_TYPE: Record<string, Record<string, unknown>> = {
+  "text-prompt": { text: "a dog running" },
+  "tone": { tone: "dramatic" },
+  "style-guide": { text: "photographic, naturalistic" },
+  "motion": { motion: "moderate" },
+  // CAMERA_MOTIONS[0] is "auto" with intentionally empty promptHint — use a
+  // real motion id so the sync test exercises the hint dispatch.
+  "camera-motion": { cameraMotion: "static" },
+  "framing": { shotSize: FIRST_FRAMING_SHOT },
+  "lens": { lens: firstId(LENSES) },
+  "camera-format": { cameraFormat: firstId(CAMERA_FORMATS) },
+  "lighting": { timeOfDay: FIRST_LIGHTING_TIME },
+  "color-look": { colorLook: firstId(COLOR_LOOKS) },
+  "atmosphere": { atmosphere: firstId(ATMOSPHERES) },
+  "style": { style: firstId(STYLES) },
+  "setting": { setting: firstId(SETTINGS) },
+  "person": { type: firstId(PEOPLE) },
+  "mood": { mood: firstId(MOODS) },
+  "photographer": { photographer: firstId(PHOTOGRAPHERS) },
+  "aesthetic": { aesthetic: firstId(AESTHETICS) },
+  "era": { era: firstId(ERAS) },
+  "pose": { pose: firstId(POSES) },
+  "styling": { outfit: firstId(STYLINGS) },
+  "temporal": { temporalSpeed: firstId(TEMPORALS) },
+  "material": { material: firstId(MATERIALS) },
+  "animal": { animal: firstId(ANIMALS) },
+  "vehicle": { vehicle: firstId(VEHICLES) },
+  "weapon": { weapon: firstId(WEAPONS) },
+  "furniture": { furniture: firstId(FURNITURE) },
+  "photo-genre": { photoGenre: firstId(PHOTO_GENRES) },
+  "backdrop": { backdrop: firstId(BACKDROPS) },
+  "held-prop": { heldProp: firstId(HELD_PROPS) },
+  "exposure-settings": { aperture: firstId(EXPOSURE_SETTINGS) },
+  "render-quality": { renderQuality: firstId(RENDER_QUALITIES) },
+  "composition-effects": { compositionEffect: firstId(COMPOSITION_EFFECTS) },
+  "post-process-effects": { postProcess: firstId(POST_PROCESS_EFFECTS) },
+  "action-fx": { actionFx: firstId(ACTION_FX) },
+  // TRANSITIONS[0] is "auto" with an intentionally empty promptHint — use a
+  // real transition id so the sync test exercises the hint dispatch.
+  "transition":   { transition:   "cross-dissolve" },
+  // CHARACTER_FX[0] is "auto" with an intentionally empty promptHint — use a
+  // real effect id so the sync test exercises the hint dispatch.
+  "character-fx": { characterFx:  "werewolf" },
+  "loop-subject": { loopSubject: firstId(LOOP_SUBJECTS) },
+  "scene-count": { count: 5 },
+  "duration": { seconds: 8 },
+  "aspect-ratio": { ratio: "16:9" },
+  "music-genre": { genre: firstId(MUSIC_GENRES) },
+  "music-mood": { emotion: firstId(MUSIC_EMOTIONS) },
+  "instrumentation": { instruments: [firstId(INSTRUMENTS)] },
+  "voice-character": { timbre: firstId(VOICE_TIMBRES) },
+  "voice-delivery": { archetype: firstId(VOICE_ARCHETYPES) },
+}
+
+// Types that intentionally do NOT inject a prompt hint via
+// getParameterPromptHint. They carry pure runtime parameters (counts,
+// durations, aspect ratios, motion intensity) consumed by the executor
+// directly, not appended to a downstream prompt.
+const HINT_EXEMPT: ReadonlySet<string> = new Set([
+  "motion",
+  "style-guide",
+  "scene-count",
+  "duration",
+  "aspect-ratio",
+])
+
+// =============================================================================
+// Test 1 — every type in the set has a sample (forces the developer who adds
+// a new type to also extend this file).
+// =============================================================================
+
+describe("PARAMETER_NODE_TYPES — sample coverage", () => {
+  for (const type of PARAMETER_NODE_TYPES) {
+    it(`has a sample data fixture for "${type}"`, () => {
+      expect(
+        SAMPLE_DATA_BY_TYPE[type],
+        `Missing SAMPLE_DATA_BY_TYPE entry for "${type}". When you add a new parameter type to PARAMETER_NODE_TYPES, you must also add a sample here so the cross-registry sync tests can probe it.`,
+      ).toBeDefined()
+    })
+  }
+})
+
+// =============================================================================
+// Test 2 — every type in PARAMETER_NODE_TYPES resolves via getParameterValue.
+// Catches: type added to set but switch-case missing in getParameterValue.
+// (The action-fx + loop-subject outages were exactly this.)
+// =============================================================================
+
+describe("PARAMETER_NODE_TYPES ↔ getParameterValue cases", () => {
+  for (const type of PARAMETER_NODE_TYPES) {
+    it(`getParameterValue resolves a value for "${type}"`, () => {
+      const sample = SAMPLE_DATA_BY_TYPE[type] ?? {}
+      const value = getParameterValue(sample, type)
+      expect(
+        value,
+        `getParameterValue returned undefined for "${type}". Either add a "case ${JSON.stringify(type)}" to getParameterValue, or update SAMPLE_DATA_BY_TYPE[${JSON.stringify(type)}] with a field this case reads.`,
+      ).toBeDefined()
+    })
+  }
+})
+
+// =============================================================================
+// Test 3 — every non-exempt type returns a non-empty prompt hint.
+// Catches: type added but missing from getParameterPromptHint switch — picker
+// mounts and value resolves but the prompt fragment is never injected.
+// =============================================================================
+
+describe("PARAMETER_NODE_TYPES ↔ getParameterPromptHint cases", () => {
+  for (const type of PARAMETER_NODE_TYPES) {
+    if (HINT_EXEMPT.has(type)) continue
+    it(`getParameterPromptHint returns non-empty for "${type}"`, () => {
+      const sample = SAMPLE_DATA_BY_TYPE[type] ?? {}
+      const node = { id: "n1", type, data: sample }
+      const hint = getParameterPromptHint(node)
+      expect(
+        hint,
+        `getParameterPromptHint returned an empty string for "${type}". Either add a "case ${JSON.stringify(type)}" to getParameterPromptHint, add the type to HINT_EXEMPT (only if it's a pure runtime parameter), or fix SAMPLE_DATA_BY_TYPE[${JSON.stringify(type)}] so the catalog lookup succeeds.`,
+      ).toBeTruthy()
+      expect(typeof hint).toBe("string")
+      expect(hint.length).toBeGreaterThan(0)
+    })
+  }
+})
+
+// =============================================================================
+// Test 4 — types in the exempt set are present in PARAMETER_NODE_TYPES (so
+// HINT_EXEMPT can't drift to reference dead types).
+// =============================================================================
+
+describe("HINT_EXEMPT integrity", () => {
+  for (const type of HINT_EXEMPT) {
+    it(`exempt type "${type}" is still in PARAMETER_NODE_TYPES`, () => {
+      expect(PARAMETER_NODE_TYPES.has(type)).toBe(true)
+    })
+    it(`exempt type "${type}" really returns empty from getParameterPromptHint`, () => {
+      const sample = SAMPLE_DATA_BY_TYPE[type] ?? {}
+      const node = { id: "n1", type, data: sample }
+      expect(getParameterPromptHint(node)).toBe("")
+    })
+  }
+})

package/src/__tests__/person-age.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from "vitest"
+import { buildAgeHint, buildPersonHints, getPerson } from "../person.js"
+
+describe("buildAgeHint", () => {
+  it("returns the catalog promptHint for non-custom presets", () => {
+    expect(buildAgeHint("age-toddler", undefined)).toBe(getPerson("age-toddler")?.promptHint)
+    expect(buildAgeHint("age-30s", undefined)).toBe("in their 30s")
+  })
+
+  it("returns empty when ageId is undefined or unknown", () => {
+    expect(buildAgeHint(undefined, undefined)).toBe("")
+    expect(buildAgeHint(null, undefined)).toBe("")
+    expect(buildAgeHint("age-fictional", undefined)).toBe("")
+  })
+
+  it("ignores customAge unless ageId is the sentinel", () => {
+    // Without the sentinel the helper falls through to the catalog hint —
+    // a stale customAge from a previous selection must not leak.
+    expect(buildAgeHint("age-30s", 7)).toBe("in their 30s")
+  })
+
+  it("returns empty for custom sentinel without a number", () => {
+    expect(buildAgeHint("age-custom", undefined)).toBe("")
+    expect(buildAgeHint("age-custom", null)).toBe("")
+    expect(buildAgeHint("age-custom", Number.NaN)).toBe("")
+  })
+
+  it("generates age-band-tuned phrasing for the lower ranges", () => {
+    expect(buildAgeHint("age-custom", 0)).toBe("a newborn under 1 year old")
+    expect(buildAgeHint("age-custom", 1)).toBe("around 1 year old")
+    expect(buildAgeHint("age-custom", 3)).toBe("a toddler around 3 years old")
+    expect(buildAgeHint("age-custom", 5)).toBe("a young child around 5 years old")
+    expect(buildAgeHint("age-custom", 8)).toBe("a child around 8 years old")
+    expect(buildAgeHint("age-custom", 11)).toBe("a pre-teen around 11 years old")
+    expect(buildAgeHint("age-custom", 14)).toBe("14 years old, in their teens")
+  })
+
+  it("uses plain phrasing for adult ages so Age dim composes with Type", () => {
+    expect(buildAgeHint("age-custom", 22)).toBe("22 years old")
+    expect(buildAgeHint("age-custom", 28)).toBe("28 years old")
+    expect(buildAgeHint("age-custom", 47)).toBe("47 years old")
+  })
+
+  it("clamps and rounds outlandish numbers", () => {
+    expect(buildAgeHint("age-custom", -3)).toBe("a newborn under 1 year old")
+    expect(buildAgeHint("age-custom", 999)).toBe("120 years old")
+    expect(buildAgeHint("age-custom", 7.6)).toBe("a child around 8 years old")
+  })
+})
+
+describe("buildPersonHints with age-custom", () => {
+  it("emits the custom-age phrase in canonical position", () => {
+    const hints = buildPersonHints({
+      type: "woman",
+      age: "age-custom",
+      customAge: 8,
+    })
+    expect(hints).toContain("a woman")
+    expect(hints).toContain("a child around 8 years old")
+    // Age must follow type per PERSON_DIMENSION_ORDER.
+    expect(hints.indexOf("a child around 8 years old"))
+      .toBeGreaterThan(hints.indexOf("a woman"))
+  })
+
+  it("drops the age clause silently when age-custom has no number", () => {
+    const hints = buildPersonHints({
+      type: "woman",
+      age: "age-custom",
+    })
+    expect(hints).toEqual(["a woman"])
+  })
+
+  it("ignores customAge when a non-custom preset is selected", () => {
+    const hints = buildPersonHints({
+      age: "age-30s",
+      customAge: 7,
+    })
+    expect(hints).toEqual(["in their 30s"])
+  })
+})

package/src/__tests__/person-analyzer-invariants.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest"
+import {
+  PEOPLE,
+  PERSON_DIMENSION_ORDER,
+  PERSON_FIELD_BY_DIMENSION,
+  MAX_SELECTED_BY_DIMENSION,
+  getPersonDimensionLimit,
+} from "../person.js"
+import { buildPickerAnalyzerSpec } from "../picker-analyzer-registry.js"
+
+// PersonData array-capable fields (string | ReadonlyArray<string>).
+const ARRAY_FIELDS = new Set([
+  "ethnicity", "regionalAesthetic", "lipState", "hairColor",
+  "skinTexture", "eyeColor", "eyeState", "distinctiveFeature",
+])
+
+describe("person analyzer invariants", () => {
+  it("every dimension has a field mapping and a defined limit", () => {
+    for (const dim of PERSON_DIMENSION_ORDER) {
+      expect(PERSON_FIELD_BY_DIMENSION[dim]).toBeTruthy()
+      expect(getPersonDimensionLimit(dim)).toBeGreaterThanOrEqual(1)
+    }
+    expect(PERSON_DIMENSION_ORDER).toHaveLength(33)
+  })
+
+  it("cardinality bijection: limit>1 ⇔ field is array-capable", () => {
+    for (const dim of PERSON_DIMENSION_ORDER) {
+      const field = PERSON_FIELD_BY_DIMENSION[dim]
+      const multi = getPersonDimensionLimit(dim) > 1
+      expect(multi).toBe(ARRAY_FIELDS.has(field))
+    }
+  })
+
+  it("analyzer enum equals the catalog ids per dimension (ids, never labels)", () => {
+    const spec = buildPickerAnalyzerSpec("person")
+    for (const d of spec.dimensions) {
+      const catalog = PEOPLE.filter((p) => p.dimension === d.dimension && p.id !== "age-custom").map((p) => p.id)
+      expect([...d.entryIds].sort()).toEqual([...catalog].sort())
+    }
+  })
+
+  it("MAX_SELECTED keys are all valid dimensions", () => {
+    for (const k of Object.keys(MAX_SELECTED_BY_DIMENSION)) {
+      expect(PERSON_DIMENSION_ORDER).toContain(k)
+    }
+  })
+})

package/src/__tests__/person-body-axes.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest"
+import { buildPersonHints } from "../person.js"
+
+/**
+ * Body proportion axes — Frame / Body Mass / Bust / Waist / Hips / Silhouette —
+ * replaced the old coarse Build + Body Proportions pickers. These tests pin the
+ * prompt-token composition (the part that actually drives generation), the
+ * "neutral emits nothing" contract, and the independent-axes guarantee the split
+ * exists to provide ("slim frame + full bust" was inexpressible before).
+ */
+describe("buildPersonHints — body proportion axes", () => {
+  it("composes the target example (slim woman, full bust)", () => {
+    const hints = buildPersonHints({
+      frame: "frame-slim",
+      bodyMass: "mass-lean",
+      bust: "bust-full",
+      waist: "waist-defined",
+      silhouette: "silhouette-hourglass",
+    })
+    expect(hints.join(", ")).toBe(
+      "slim, lean build, full bust, defined waist, hourglass silhouette",
+    )
+  })
+
+  it("emits every axis in canonical order (frame, mass, bust, waist, hips, silhouette)", () => {
+    const joined = buildPersonHints({
+      frame: "frame-broad",
+      bodyMass: "mass-heavy",
+      bust: "bust-small",
+      waist: "waist-straight",
+      hips: "hips-wide",
+      silhouette: "silhouette-pear",
+    }).join(", ")
+    expect(joined).toBe(
+      "broad-framed, heavy-set build, small bust, straight waistline, wide hips, pear-shaped silhouette",
+    )
+  })
+
+  it("neutral values (Average / Balanced) contribute nothing", () => {
+    expect(
+      buildPersonHints({
+        frame: "frame-average",
+        bodyMass: "mass-average",
+        bust: "bust-average",
+        waist: "waist-average",
+        hips: "hips-balanced",
+      }),
+    ).toEqual([])
+  })
+
+  it("axes are independent — a slim frame pairs with a full bust (the bug the split fixes)", () => {
+    expect(buildPersonHints({ frame: "frame-slim", bust: "bust-full" })).toEqual([
+      "slim",
+      "full bust",
+    ])
+  })
+
+  it("Bust:Very Full emits the distinct very-full token", () => {
+    expect(buildPersonHints({ bust: "bust-very-full" })).toEqual(["very full bust"])
+  })
+
+  it("ignores stored values for the retired Build / Body Proportions keys (no migration)", () => {
+    // Old saved workflow data may still carry these now-removed fields; no
+    // dimension reads them, so they emit nothing and never crash the picker.
+    expect(buildPersonHints({ build: "voluptuous", bodyProportions: "proportions-hourglass" })).toEqual([])
+  })
+})

package/src/__tests__/person-facial-geometry.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect } from "vitest"
+import { PEOPLE, PERSON_DIMENSION_ORDER, PERSON_FIELD_BY_DIMENSION, buildPersonHints, migratePersonValue, getPersonPromptHint } from "../index.js"
+
+/**
+ * Facial-geometry layer: new Face dimensions + the eye/lips split, plus the
+ * backward-compatibility guarantees for already-saved Person data.
+ */
+describe("facial-geometry catalog", () => {
+  const idsFor = (dim: string) => PEOPLE.filter((p) => p.dimension === dim).map((p) => p.id)
+
+  it("registers every new dimension in the canonical order", () => {
+    for (const dim of [
+      "cheekbones",
+      "facial-fullness",
+      "eyelid-type",
+      "canthal-tilt",
+      "eye-spacing",
+      "eye-set-brow",
+      "nose-tip",
+      "lip-fullness",
+      "lip-shape",
+    ]) {
+      expect(PERSON_DIMENSION_ORDER, dim).toContain(dim)
+      expect(PERSON_FIELD_BY_DIMENSION[dim as keyof typeof PERSON_FIELD_BY_DIMENSION], dim).toBeTruthy()
+      expect(idsFor(dim).length, dim).toBeGreaterThan(0)
+    }
+  })
+
+  it("dropped `lips` and `philtrum` as dimensions", () => {
+    expect(PERSON_DIMENSION_ORDER).not.toContain("lips")
+    expect(PERSON_DIMENSION_ORDER).not.toContain("philtrum")
+  })
+
+  it("eyelid-type exposes Standard / Hooded / Droopy / Deep-set (droopy is its own value)", () => {
+    expect(idsFor("eyelid-type")).toEqual(["eyelid-standard", "eye-hooded", "eye-droopy", "eye-deep-set"])
+  })
+
+  it("eye-shape keeps only anatomical shapes (lid/tilt/spacing moved out)", () => {
+    expect(idsFor("eye-shape")).toEqual([
+      "eye-almond",
+      "eye-round",
+      "eye-monolid",
+      "eye-double-eyelid",
+      "eye-wide",
+      "eye-narrow",
+    ])
+  })
+
+  it("every neutral default carries an EMPTY promptHint (enabling injects nothing)", () => {
+    for (const id of [
+      "cheekbones-average",
+      "facial-fullness-average",
+      "eyelid-standard",
+      "canthal-neutral",
+      "eye-spacing-average",
+      "eyeset-average",
+      "nose-tip-natural",
+      "lips-natural",
+    ]) {
+      expect(getPersonPromptHint(id), id).toBe("")
+    }
+  })
+
+  it("non-neutral options inject a real fragment", () => {
+    expect(getPersonPromptHint("cheekbones-sculpted")).toContain("cheekbones")
+    expect(getPersonPromptHint("eye-upturned")).toContain("canthal tilt")
+    expect(getPersonPromptHint("nose-tip-upturned")).toContain("nose tip")
+    expect(getPersonPromptHint("lips-full-lower")).toContain("lower lip")
+  })
+})
+
+describe("buildPersonHints — facial geometry composition", () => {
+  it("composes the geometry fields in canonical order", () => {
+    const hints = buildPersonHints({
+      cheekbones: "cheekbones-sculpted",
+      facialFullness: "facial-fullness-lean",
+      eyeShape: "eye-almond",
+      eyelidType: "eye-hooded",
+      canthalTilt: "eye-upturned",
+      lipFullness: "lips-full",
+      lipShape: "lips-cupids-bow",
+    })
+    const joined = hints.join(", ")
+    expect(joined).toContain("sharply sculpted high cheekbones")
+    expect(joined).toContain("almond-shaped eyes")
+    expect(joined).toContain("hooded eyes")
+    expect(joined).toContain("positive canthal tilt")
+    expect(joined).toContain("full plump lips")
+    expect(joined).toContain("cupid's bow")
+    // cheekbones precede eyes precede lips (Face dimension order)
+    expect(joined.indexOf("cheekbones")).toBeLessThan(joined.indexOf("almond"))
+    expect(joined.indexOf("almond")).toBeLessThan(joined.indexOf("cupid's bow"))
+  })
+
+  it("neutral picks contribute nothing", () => {
+    expect(buildPersonHints({ cheekbones: "cheekbones-average", noseTip: "nose-tip-natural" })).toEqual([])
+  })
+})
+
+describe("backward compatibility — legacy saved Person data still resolves", () => {
+  it("legacy eyeShape values (relocated dims) still emit their original hint", () => {
+    // Old data stored hooded/upturned/wide-set under `eyeShape`; the ids stayed
+    // in the catalog, so buildPersonHints (id-based) emits the same phrase.
+    expect(buildPersonHints({ eyeShape: "eye-hooded" })).toEqual([
+      "hooded eyes with the upper lid partially covering the crease",
+    ])
+    expect(buildPersonHints({ eyeShape: "eye-wide-set" }).join("")).toContain("wide-set eyes")
+  })
+
+  it("legacy `lips` value emits via the fallback when no new lip field is set", () => {
+    expect(buildPersonHints({ lips: "lips-cupids-bow" })).toEqual([
+      "a pronounced cupid's bow on the upper lip",
+    ])
+  })
+
+  it("does NOT double-emit when both legacy `lips` and a new lip field are set", () => {
+    const hints = buildPersonHints({ lips: "lips-thin", lipFullness: "lips-full" })
+    expect(hints).toEqual(["full plump lips"])
+  })
+})
+
+describe("migratePersonValue", () => {
+  it("relocates legacy eyeShape onto the split fields and clears the source", () => {
+    expect(migratePersonValue({ eyeShape: "eye-hooded" })).toEqual({ eyeShape: undefined, eyelidType: "eye-hooded" })
+    expect(migratePersonValue({ eyeShape: "eye-upturned" })).toEqual({ eyeShape: undefined, canthalTilt: "eye-upturned" })
+    expect(migratePersonValue({ eyeShape: "eye-close-set" })).toEqual({ eyeShape: undefined, eyeSpacing: "eye-close-set" })
+  })
+
+  it("relocates legacy lips onto fullness/shape", () => {
+    expect(migratePersonValue({ lips: "lips-full" })).toEqual({ lips: undefined, lipFullness: "lips-full" })
+    expect(migratePersonValue({ lips: "lips-small" })).toEqual({ lips: undefined, lipShape: "lips-small" })
+  })
+
+  it("leaves kept eye-shape values and unrelated keys untouched (same reference)", () => {
+    const kept = { eyeShape: "eye-almond", label: "Person", type: "woman" }
+    expect(migratePersonValue(kept)).toBe(kept)
+  })
+
+  it("never overwrites an already-set target field", () => {
+    const v = { eyeShape: "eye-hooded", eyelidType: "eye-deep-set" }
+    // target already set → leave both as-is (no clobber)
+    expect(migratePersonValue(v)).toBe(v)
+  })
+
+  it("is idempotent", () => {
+    const once = migratePersonValue({ eyeShape: "eye-hooded", lips: "lips-cupids-bow" })
+    const twice = migratePersonValue(once)
+    expect(twice).toEqual(once)
+  })
+
+  it("preserves the same prompt output before and after migration", () => {
+    const legacy = { eyeShape: "eye-upturned", lips: "lips-full" }
+    const migrated = migratePersonValue(legacy)
+    expect(buildPersonHints(migrated)).toEqual(buildPersonHints(legacy))
+  })
+})