@nodaro/prompts 1.19.0 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "Nodaro's prompt-engineering layer — person/picker catalogs with prompt hints, identity-lock clauses, entity prompt builders, brand presets, and prompt/reference assembly shared by the Nodaro platform and SDK.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
@@ -20,7 +20,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@nodaro/shared": "^3.9.0"
+    "@nodaro/shared": "^3.10.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

package/src/__tests__/adult-only-ratchet.test.ts

@@ -4,6 +4,7 @@ import { STYLINGS } from "../styling.js"
 import { MOODS } from "../mood.js"
 import { POSES } from "../pose.js"
 import { PHOTO_GENRES } from "../photo-genre.js"
+import { CHARACTER_MOTIONS } from "../character-motion.js"
 import { getAdultOnlyEntries } from "../age-floor.js"
 
 /**
@@ -45,6 +46,20 @@ const EXEMPT: Readonly<Record<string, string>> = {
   "caught-off-guard": "lips parted from a startled reaction, not a seductive expression",
   "hands-on-hips": "neutral confident stance — hips referenced as a body part, no exposure or sexual content",
   "hand-position-hands-on-hips": "neutral confident stance, hand-position variant of hands-on-hips",
+  "sway-to-music": "character-motion: sway to the music — dance mechanics, hips as a body part, no exposure",
+  "sway-arms-raised": "character-motion: arms-up sway — dance mechanics, hips as a body part, no exposure",
+  "do-the-worm": "character-motion: the worm — dance mechanics, hips as a body part, no exposure",
+  "strike-vogue-poses": "character-motion: vogue — dance mechanics, hips as a body part, no exposure",
+  "spin-salsa-turn": "character-motion: salsa turn — dance mechanics, hips as a body part, no exposure",
+  "sway-bachata-hips": "character-motion: bachata sway — dance mechanics, hips as a body part, no exposure",
+  "flourish-bollywood-hands": "character-motion: bollywood flourish — dance mechanics, hips as a body part, no exposure",
+  "do-the-twist": "character-motion: the twist — dance mechanics, hips as a body part, no exposure",
+  "throw-disco-point": "character-motion: disco point — dance mechanics, hips as a body part, no exposure",
+  "do-the-floss": "character-motion: the floss — dance mechanics, hips as a body part, no exposure",
+  "tears-well-up": "character-motion: tear-filled glistening eyes — emotion, not skin",
+  "pout-sulkily": "character-motion: a sulky pout — emotional expression, not a seductive one",
+  "plant-hands-on-hips": "character-motion: neutral confident stance — hips as a body part, no exposure",
+  "freeze-on-the-drop": "character-motion: freeze on the drop — dance mechanics, hips as a body part, no exposure",
 }
 
 /** The hand-curated set. The test fails if any of these loses the flag. */
@@ -71,9 +86,11 @@ const CURATED = [
   "seductive", "sultry", "smoldering", "flirty",
   "biting-lip", "arched-back", "sitting-edge-of-bed", "lounging", "lying-down",
   "brand-helmut-newton", "glamour-portrait",
+  // character-motion
+  "sultry-look-over-shoulder", "sashay-forward", "sway-hips-walk", "drop-coat-off-shoulders", "sultry-look-back", "shimmy-the-hips", "roll-the-body", "bite-lip-teasingly", "lick-lips-suggestively", "smolder-heavy-lidded", "smolder-at-camera", "hug-partner-from-behind", "lean-in-almost-kiss", "kiss-partner", "rise-on-tiptoes-to-kiss-partner", "pull-partner-close",
 ] as const
 
-const ALL = [...PEOPLE, ...STYLINGS, ...MOODS, ...POSES, ...PHOTO_GENRES]
+const ALL = [...PEOPLE, ...STYLINGS, ...MOODS, ...POSES, ...PHOTO_GENRES, ...CHARACTER_MOTIONS]
 
 describe("adultOnly ratchet", () => {
   it("every id in CURATED exists and carries the flag", () => {

package/src/__tests__/character-motion-docs-example.test.ts

@@ -0,0 +1,26 @@
+/**
+ * Public Docs Maintenance Rule: worked examples in docs MUST match the code.
+ * The Character Motion page quotes the composer's exact output for one sequence
+ * in both hint modes; this reads the page and fails if either quote drifts.
+ */
+import { describe, it, expect } from "vitest"
+import { readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { composeCharacterMotionHintFromConnections as compose } from "../character-motion.js"
+
+const DOC = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), "../../../../docs/nodes/parameters/character-motion.md"),
+  "utf8",
+)
+const IDS = ["walk-in-from-left", "wave-hello", "hug-partner"]
+const TIMING = { position: "start", pace: "slow" } as const
+
+describe("docs/nodes/parameters/character-motion.md worked example", () => {
+  it("quotes the full-mode output verbatim", () => {
+    expect(DOC).toContain(compose(IDS, ["Mira"], ["Theo"], TIMING))
+  })
+  it("quotes the compact-mode output verbatim", () => {
+    expect(DOC).toContain(compose(IDS, ["Mira"], ["Theo"], TIMING, "compact"))
+  })
+})

package/src/__tests__/character-motion-timing-catalogs.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Character Motion's two timing parameters (position / pace) are enumerable
+ * catalogs so id-only consumers (Studio, the SDK, MCP) can offer them. Twin of
+ * `character-fx-timing-catalogs.test.ts`; the wording is this node's own and
+ * nothing here may couple it to the transition or character-fx rows.
+ */
+import { describe, it, expect } from "vitest"
+import {
+  CHARACTER_MOTION_POSITIONS,
+  CHARACTER_MOTION_PACES,
+  composeCharacterMotionHintFromConnections,
+} from "../character-motion.js"
+import { CHARACTER_FX_POSITIONS } from "../character-fx.js"
+import { TRANSITION_POSITIONS } from "../transitions.js"
+
+const MOVE = "walk-in-from-left"
+const DIMENSIONS = [
+  ["position", CHARACTER_MOTION_POSITIONS],
+  ["pace", CHARACTER_MOTION_PACES],
+] as const
+
+describe("character-motion timing catalogs", () => {
+  it("spells exactly the ids stored workflows will use", () => {
+    expect(CHARACTER_MOTION_POSITIONS.map((o) => o.id)).toEqual(["auto", "start", "middle", "end", "full"])
+    expect(CHARACTER_MOTION_PACES.map((o) => o.id)).toEqual(["auto", "slow-motion", "slow", "natural", "fast", "explosive"])
+  })
+
+  it("pins the injected clauses byte for byte", () => {
+    expect(CHARACTER_MOTION_POSITIONS.map((o) => o.promptHint)).toEqual([
+      "",
+      "the movement begins at the opening of the clip",
+      "the movement begins midway through the clip",
+      "the movement happens in the closing moments of the clip",
+      "the movement plays out across the entire clip",
+    ])
+    expect(CHARACTER_MOTION_PACES.map((o) => o.promptHint)).toEqual([
+      "",
+      "the action is rendered in slow motion, every phase of the movement stretched and drawn out",
+      "performed slowly and deliberately, each phase of the movement given its full time",
+      "performed at a natural everyday tempo, neither rushed nor drawn out",
+      "performed quickly, with brisk urgent tempo and sharp transitions between phases",
+      "performed with an explosive burst of energy, snapping from stillness into full-speed motion",
+    ])
+  })
+
+  it("keeps its own position wording — not the character-fx or transition rows", () => {
+    const mine = CHARACTER_MOTION_POSITIONS.map((o) => o.promptHint)
+    expect(mine).not.toEqual(CHARACTER_FX_POSITIONS.map((o) => o.promptHint))
+    expect(mine).not.toEqual(TRANSITION_POSITIONS.map((o) => o.promptHint))
+  })
+
+  it("every scale leads with a no-op auto; every other step has a hint and a term", () => {
+    for (const [field, options] of DIMENSIONS) {
+      expect(options[0]!.id, field).toBe("auto")
+      expect(options[0]!.promptHint, field).toBe("")
+      expect(options[0]!.term, field).toBe("")
+      for (const o of options.slice(1)) {
+        expect(o.promptHint, `${field}/${o.id}`).not.toBe("")
+        expect(o.term, `${field}/${o.id}`).toBeTruthy()
+      }
+    }
+  })
+
+  it("composes every step verbatim with no dangling separator, in both modes", () => {
+    for (const [field, options] of DIMENSIONS) {
+      for (const o of options.slice(1)) {
+        for (const mode of ["full", "compact"] as const) {
+          const out = composeCharacterMotionHintFromConnections(MOVE, [], [], { [field]: o.id } as never, mode)
+          expect(out, `${field}/${o.id} ${mode}`).toContain(o.promptHint)
+          expect(out, `${field}/${o.id} ${mode}`).not.toMatch(/,\s*$/)
+          expect(out, `${field}/${o.id} ${mode}`).not.toContain("undefined")
+        }
+      }
+    }
+  })
+})

package/src/__tests__/character-motion.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, it } from "vitest"
+import {
+  CHARACTER_MOTIONS,
+  CHARACTER_MOTION_IDS,
+  CHARACTER_MOTION_CATEGORY_ORDER,
+  CHARACTER_MOTION_CATEGORY_LABELS,
+  CHARACTER_MOTION_MAX_PICKS,
+  composeCharacterMotionHintFromConnections as compose,
+  getCharacterMotion,
+  getCharacterMotionLabel,
+  getCharacterMotionPromptHint as hintOf,
+  getCharacterMotionTerm as termOf,
+} from "../character-motion.js"
+
+// Real ids from the catalog. Solo moves carry "the subject" only; DUO carries
+// "the partner" too.
+const SOLO_A = "walk-in-from-left"
+const SOLO_B = "turn-to-camera"
+const SOLO_C = "break-into-smile"
+const SOLO_D = "wave-hello"
+const DUO = "hug-partner"
+const injecting = CHARACTER_MOTIONS.filter((m) => m.promptHint !== "")
+
+describe("character-motion catalog — shape", () => {
+  it("leads with the no-op auto and none heads, which inject nothing", () => {
+    expect(CHARACTER_MOTIONS.slice(0, 2).map((m) => m.id)).toEqual(["auto", "none"])
+    for (const id of ["auto", "none"]) {
+      expect(hintOf(id)).toBe("")
+      expect(termOf(id)).toBe("")
+      expect(getCharacterMotion(id)?.adultOnly).toBeUndefined()
+    }
+  })
+
+  it("ships 1003 injecting entries across 20 categories", () => {
+    expect(injecting).toHaveLength(1003)
+    expect(CHARACTER_MOTION_CATEGORY_ORDER).toHaveLength(20)
+  })
+
+  it("ids are unique kebab-case", () => {
+    expect(new Set(CHARACTER_MOTION_IDS).size).toBe(CHARACTER_MOTION_IDS.length)
+    for (const id of CHARACTER_MOTION_IDS) expect(id).toMatch(/^[a-z0-9]+(-[a-z0-9]+)*$/)
+  })
+
+  it("labels are unique case-insensitively, so no two tiles read the same", () => {
+    const labels = CHARACTER_MOTIONS.map((m) => m.label.toLowerCase())
+    expect(new Set(labels).size).toBe(labels.length)
+  })
+
+  it("every category is ordered, labelled and non-empty; every entry sits in one", () => {
+    expect(new Set(CHARACTER_MOTION_CATEGORY_ORDER)).toEqual(new Set(Object.keys(CHARACTER_MOTION_CATEGORY_LABELS)))
+    for (const cat of CHARACTER_MOTION_CATEGORY_ORDER) {
+      expect(injecting.some((m) => m.category === cat), `${cat} is empty`).toBe(true)
+    }
+    for (const m of CHARACTER_MOTIONS) expect(CHARACTER_MOTION_CATEGORY_ORDER).toContain(m.category)
+  })
+
+  it("the substitution tokens match the flags exactly", () => {
+    for (const m of injecting) {
+      expect(m.promptHint, `${m.id} hint must name the subject`).toMatch(/\bthe subject\b/)
+      expect(/\bthe partner\b/.test(m.promptHint), `${m.id}: hint partner token vs twoPerson`).toBe(m.twoPerson === true)
+      expect(m.term, `${m.id} needs an authored term`).toBeTruthy()
+      expect(m.term!, `${m.id}: a term never names the subject (compact mode prefixes it)`).not.toMatch(/\bthe subject\b/)
+      expect(/\bthe partner\b/.test(m.term!), `${m.id}: term partner token vs twoPerson`).toBe(m.twoPerson === true)
+      expect(m.promptHint.endsWith("."), `${m.id} trailing period`).toBe(false)
+    }
+  })
+})
+
+describe("character-motion getters", () => {
+  it("resolve known ids and return nothing for nullish or unknown ids", () => {
+    expect(getCharacterMotion(SOLO_D)?.id).toBe(SOLO_D)
+    expect(getCharacterMotion(undefined)).toBeUndefined()
+    expect(getCharacterMotion(null)).toBeUndefined()
+    expect(getCharacterMotion("no-such-move")).toBeUndefined()
+    expect(hintOf("no-such-move")).toBe("")
+    expect(termOf("no-such-move")).toBe("")
+  })
+
+  it("label falls back to the title-cased id, or empty for nullish", () => {
+    expect(getCharacterMotionLabel("no-such-move")).toBe("No Such Move")
+    expect(getCharacterMotionLabel(null)).toBe("")
+  })
+})
+
+describe("composeCharacterMotionHintFromConnections — full mode", () => {
+  it("a single unwired pick is the bare hint", () => {
+    expect(compose(SOLO_A, [], [])).toBe(hintOf(SOLO_A))
+  })
+
+  it("auto, none, unknown, null and [] inject nothing", () => {
+    for (const v of ["auto", "none", "no-such-move", null, undefined, [] as string[]]) {
+      expect(compose(v, ["Aria"], ["Ben"])).toBe("")
+    }
+  })
+
+  it("substitutes the wired target for every 'the subject'", () => {
+    expect(compose(SOLO_A, ["Aria"], [])).toBe(hintOf(SOLO_A).replace(/\bthe subject\b/g, "Aria"))
+  })
+
+  it("joins the picks as an ordered sequence with ', then '", () => {
+    expect(compose([SOLO_B, SOLO_A], [], [])).toBe(`${hintOf(SOLO_B)}, then ${hintOf(SOLO_A)}`)
+  })
+
+  it(`de-duplicates, keeps first-pick order, then caps at ${CHARACTER_MOTION_MAX_PICKS}`, () => {
+    expect(compose([SOLO_A, SOLO_A, SOLO_B, SOLO_C, SOLO_D], [], [])).toBe(
+      [SOLO_A, SOLO_B, SOLO_C].map((id) => hintOf(id)).join(", then "),
+    )
+  })
+
+  it("an unwired partner reads 'another person' — the literal token never ships", () => {
+    const out = compose(DUO, [], [])
+    expect(out).not.toMatch(/\bthe partner\b/)
+    expect(out).toBe(hintOf(DUO).replace(/\bthe partner\b/g, "another person"))
+  })
+
+  it("substitutes both wired names", () => {
+    expect(compose(DUO, ["Aria"], ["Ben"])).toBe(
+      hintOf(DUO).replace(/\bthe subject\b/g, "Aria").replace(/\bthe partner\b/g, "Ben"),
+    )
+  })
+
+  it("appends the position clause, then the pace clause", () => {
+    expect(compose(SOLO_A, [], [], { position: "start", pace: "slow-motion" })).toBe(
+      `${hintOf(SOLO_A)}, the movement begins at the opening of the clip, the action is rendered in slow motion, every phase of the movement stretched and drawn out`,
+    )
+  })
+
+  it("auto timing adds nothing", () => {
+    expect(compose(SOLO_A, [], [], { position: "auto", pace: "auto" })).toBe(hintOf(SOLO_A))
+  })
+})
+
+describe("composeCharacterMotionHintFromConnections — compact mode", () => {
+  it("joins terms with ', then ' and has no prefix when unwired", () => {
+    expect(compose([SOLO_B, SOLO_C], [], [], undefined, "compact")).toBe(`${termOf(SOLO_B)}, then ${termOf(SOLO_C)}`)
+  })
+
+  it("prefixes the wired target", () => {
+    expect(compose(SOLO_A, ["Aria"], [], undefined, "compact")).toBe(`Aria: ${termOf(SOLO_A)}`)
+  })
+
+  it("substitutes the partner inside a two-person term", () => {
+    expect(compose([SOLO_A, DUO], ["Aria"], ["Ben"], undefined, "compact")).toBe(
+      `Aria: ${termOf(SOLO_A)}, then ${termOf(DUO).replace(/\bthe partner\b/g, "Ben")}`,
+    )
+    expect(compose(DUO, [], [], undefined, "compact")).toBe(termOf(DUO).replace(/\bthe partner\b/g, "another person"))
+  })
+
+  it("timing clauses are the same promptHint strings in compact mode", () => {
+    expect(compose(SOLO_A, [], [], { pace: "fast" }, "compact")).toBe(
+      `${termOf(SOLO_A)}, performed quickly, with brisk urgent tempo and sharp transitions between phases`,
+    )
+  })
+})
+
+// The composer is the floor for adult-only moves on the video prompt: its
+// caller reports a minor subject and every `adultOnly` pick is dropped.
+describe("composeCharacterMotionHintFromConnections — minor-age floor", () => {
+  const ADULT = "kiss-partner"
+  const ADULT_B = "lean-in-almost-kiss"
+  const MODES = ["full", "compact"] as const
+  const MINOR = { subjectMinor: true } as const
+
+  it("the fixtures carry the flags these tests rely on", () => {
+    expect(getCharacterMotion(ADULT)?.adultOnly).toBe(true)
+    expect(getCharacterMotion(ADULT_B)?.adultOnly).toBe(true)
+    for (const id of [SOLO_A, SOLO_B, SOLO_D]) expect(getCharacterMotion(id)?.adultOnly).toBeUndefined()
+  })
+
+  it("drops an adult-only pick for a minor subject and keeps the neutral one, in both modes", () => {
+    const full = compose([SOLO_D, ADULT], [], [], undefined, "full", MINOR)
+    expect(full).toBe(hintOf(SOLO_D))
+    expect(full).not.toMatch(/kiss/i)
+    const compact = compose([SOLO_D, ADULT], [], [], undefined, "compact", MINOR)
+    expect(compact).toBe(termOf(SOLO_D))
+    expect(compact).not.toMatch(/kiss/i)
+  })
+
+  it("only adult-only picks for a minor inject nothing — no timing clauses either", () => {
+    for (const mode of MODES) {
+      expect(compose([ADULT, ADULT_B], ["Aria"], ["Ben"], { position: "start", pace: "fast" }, mode, MINOR)).toBe("")
+      expect(compose(ADULT, [], [], undefined, mode, MINOR)).toBe("")
+    }
+  })
+
+  it("subjectMinor false and an omitted floor are byte-identical and keep the adult-only pick", () => {
+    for (const mode of MODES) {
+      const picks = [SOLO_D, ADULT]
+      const omitted = compose(picks, ["Aria"], ["Ben"], undefined, mode)
+      expect(compose(picks, ["Aria"], ["Ben"], undefined, mode, { subjectMinor: false })).toBe(omitted)
+      expect(compose(picks, ["Aria"], ["Ben"], undefined, mode, {})).toBe(omitted)
+      const kiss = mode === "full"
+        ? hintOf(ADULT).replace(/\bthe subject\b/g, "Aria").replace(/\bthe partner\b/g, "Ben")
+        : termOf(ADULT).replace(/\bthe partner\b/g, "Ben")
+      expect(omitted).toContain(kiss)
+    }
+  })
+
+  it(`caps the user's picks at ${CHARACTER_MOTION_MAX_PICKS} before dropping, so a later pick never backfills`, () => {
+    expect(compose([SOLO_A, ADULT, SOLO_B, SOLO_D], [], [], undefined, "full", MINOR)).toBe(
+      `${hintOf(SOLO_A)}, then ${hintOf(SOLO_B)}`,
+    )
+    expect(compose([SOLO_A, ADULT, SOLO_B, SOLO_D], [], [], undefined, "compact", MINOR)).toBe(
+      `${termOf(SOLO_A)}, then ${termOf(SOLO_B)}`,
+    )
+  })
+})

package/src/__tests__/fixtures/parameter-hint-golden.json

@@ -631,6 +631,142 @@
       },
       "expected": "Mira 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"
     },
+    {
+      "key": "character-motion/id:auto",
+      "note": "single-dim catalog id",
+      "node": {
+        "id": "n1",
+        "type": "character-motion",
+        "data": {
+          "characterMotion": "auto"
+        }
+      },
+      "ctx": null,
+      "expected": ""
+    },
+    {
+      "key": "character-motion/id:let-the-jaw-drop",
+      "note": "single-dim catalog id",
+      "node": {
+        "id": "n1",
+        "type": "character-motion",
+        "data": {
+          "characterMotion": "let-the-jaw-drop"
+        }
+      },
+      "ctx": null,
+      "expected": "the subject lets the jaw fall open under its own weight until the mouth hangs wide and slack, the lips loose and the tongue still, holding it open while the rest of the face stays blank"
+    },
+    {
+      "key": "character-motion/id:rise-after-knockdown",
+      "note": "single-dim catalog id",
+      "node": {
+        "id": "n1",
+        "type": "character-motion",
+        "data": {
+          "characterMotion": "rise-after-knockdown"
+        }
+      },
+      "ctx": null,
+      "expected": "the subject pushes up from the ground onto one knee, plants a hand and rises to standing, shakes the head clear and raises both fists back into guard"
+    },
+    {
+      "key": "character-motion/multi-pick",
+      "note": "array of 2 ids on \"characterMotion\"",
+      "node": {
+        "id": "n1",
+        "type": "character-motion",
+        "data": {
+          "characterMotion": [
+            "walk-in-from-left",
+            "walk-in-from-right"
+          ]
+        }
+      },
+      "ctx": null,
+      "expected": "the subject walks into frame from the left edge at an even stride, weight rolling heel to toe, crosses toward center and stops facing forward, then the subject walks into frame from the right edge at an even stride, weight rolling heel to toe, crosses toward center and stops facing forward"
+    },
+    {
+      "key": "character-motion/pre-post",
+      "note": "preText + postText wrap the base fragment",
+      "node": {
+        "id": "n1",
+        "type": "character-motion",
+        "data": {
+          "characterMotion": "walk-in-from-left",
+          "preText": "shot on location",
+          "postText": "no text overlays"
+        }
+      },
+      "ctx": null,
+      "expected": "shot on location, the subject walks into frame from the left edge at an even stride, weight rolling heel to toe, crosses toward center and stops facing forward, no text overlays"
+    },
+    {
+      "key": "character-motion/sequence-timing",
+      "note": "character-motion: three ordered picks + position + pace, no ctx",
+      "node": {
+        "id": "n1",
+        "type": "character-motion",
+        "data": {
+          "characterMotion": [
+            "walk-in-from-left",
+            "turn-to-camera",
+            "wave-hello"
+          ],
+          "position": "middle",
+          "pace": "slow"
+        }
+      },
+      "ctx": null,
+      "expected": "the subject walks into frame from the left edge at an even stride, weight rolling heel to toe, crosses toward center and stops facing forward, then the subject turns from back-to-camera around to face front, stepping the feet through the rotation, shoulders squaring to the camera and weight settling evenly on both feet, then the subject lifts one hand to shoulder height, palm forward, and waves it side to side in a friendly greeting before letting the arm drop back to the side, the movement begins midway through the clip, performed slowly and deliberately, each phase of the movement given its full time"
+    },
+    {
+      "key": "character-motion/with-ctx",
+      "note": "character-motion substituting upstream names for 'the subject' and 'the partner'",
+      "node": {
+        "id": "n1",
+        "type": "character-motion",
+        "data": {
+          "characterMotion": [
+            "walk-in-from-left",
+            "hug-partner"
+          ]
+        }
+      },
+      "ctx": {
+        "nodes": [
+          {
+            "id": "c1",
+            "type": "character-ref",
+            "data": {
+              "characterName": "Mira"
+            }
+          },
+          {
+            "id": "c2",
+            "type": "character-ref",
+            "data": {
+              "characterName": "Theo"
+            }
+          }
+        ],
+        "edges": [
+          {
+            "source": "c1",
+            "target": "n1",
+            "sourceHandle": "output",
+            "targetHandle": "target"
+          },
+          {
+            "source": "c2",
+            "target": "n1",
+            "sourceHandle": "output",
+            "targetHandle": "partner"
+          }
+        ]
+      },
+      "expected": "Mira walks into frame from the left edge at an even stride, weight rolling heel to toe, crosses toward center and stops facing forward, then Mira steps toward Theo, opens both arms and wraps them around Theo's back in a firm hug, holds the hug, and loosens the arms to step back"
+    },
     {
       "key": "color-look/id:lifestyle-warm-magazine",
       "note": "single-dim catalog id",

package/src/__tests__/parameter-hint-mode.test.ts

@@ -194,6 +194,33 @@ describe("hint mode: compact preserves everything but the base fragment", () =>
     expect(compact).toContain("with extreme exaggerated energy, wild flourishes, and dramatic distortion")
   })
 
+  it("character-motion timing clauses are emitted identically in compact mode", () => {
+    const move = firstInjectingId("character-motion")
+    const data = { characterMotion: move, position: "full", pace: "explosive" }
+    const compact = getParameterPromptHint({ id: "n1", type: "character-motion", data: { ...data, hintMode: "compact" } })
+    expect(compact).toContain("the movement plays out across the entire clip")
+    expect(compact).toContain("performed with an explosive burst of energy, snapping from stillness into full-speed motion")
+  })
+
+  it("character-motion names target and partner in both modes", () => {
+    const ctx: HintGraphContext = {
+      nodes: [
+        { id: "c1", type: "character-ref", data: { characterName: "Mira" } },
+        { id: "c2", type: "character-ref", data: { characterName: "Theo" } },
+      ],
+      edges: [
+        { source: "c1", target: "n1", targetHandle: "target" },
+        { source: "c2", target: "n1", targetHandle: "partner" },
+      ],
+    }
+    const node: HintNodeLike = { id: "n1", type: "character-motion", data: { characterMotion: "hug-partner" } }
+    for (const out of [getParameterPromptHint(node, ctx), getParameterPromptHint(withMode(node, "compact"), ctx)]) {
+      expect(out).toContain("Mira")
+      expect(out).toContain("Theo")
+      expect(out).not.toMatch(/\bthe (subject|partner)\b/)
+    }
+  })
+
   it("the wired character is NAMED in both modes", () => {
     // Regression: compact mode used to run the full mode's substitution — a
     // regex replace of "the subject" — over a `term` that never contains those
@@ -282,6 +309,7 @@ describe("hint mode: compact preserves everything but the base fragment", () =>
     for (const [type, field] of [
       ["transition", "transition"],
       ["character-fx", "characterFx"],
+      ["character-motion", "characterMotion"],
       ["camera-motion", "cameraMotion"],
     ] as const) {
       expect(getParameterPromptHint({ id: "n1", type, data: { [field]: "auto", hintMode: "compact" } })).toBe("")