@nodaro/prompts 1.19.0 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.19.0",
+  "version": "1.21.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.11.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"
 
 /**
@@ -21,6 +22,14 @@ const RISKY =
 
 /** Entries the regex trips on that are NOT body-exposure content. */
 const EXEMPT: Readonly<Record<string, string>> = {
+  "sashay-forward": "Neutral movement or affection; no sensual framing or exposure in the authored fragment.",
+  "sway-hips-walk": "Neutral movement or affection; no sensual framing or exposure in the authored fragment.",
+  "drop-coat-off-shoulders": "Neutral movement or affection; no sensual framing or exposure in the authored fragment.",
+  "shimmy-the-hips": "Neutral movement or affection; no sensual framing or exposure in the authored fragment.",
+  "roll-the-body": "Neutral movement or affection; no sensual framing or exposure in the authored fragment.",
+  "hug-partner-from-behind": "Neutral movement or affection; no sensual framing or exposure in the authored fragment.",
+  "pull-partner-close": "Neutral movement or affection; no sensual framing or exposure in the authored fragment.",
+
   "nun": "rosary at the waist — garment placement",
   "construction-worker": "tool belt at the waist",
   "karate-fighter": "barefoot in a fighting stance — martial arts",
@@ -45,6 +54,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 +94,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", "sultry-look-back", "bite-lip-teasingly", "lick-lips-suggestively", "smolder-heavy-lidded", "smolder-at-camera", "lean-in-almost-kiss", "kiss-partner", "rise-on-tiptoes-to-kiss-partner",
 ] 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-audit.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest"
+import { CHARACTER_MOTIONS, composeCharacterMotionHintFromConnections as compose, getCharacterMotion } from "../character-motion.js"
+import { getCharacterMotionDiagnostics as diagnose } from "../character-motion-diagnostics.js"
+import { getParameterPromptHint, getCharacterMotionBindings } from "../parameter-prompt-hint.js"
+import { getPickerCatalog } from "../picker-catalogs.js"
+
+describe("motion composition regression coverage", () => {
+  it("treats replacement syntax and template words inside names literally", () => {
+    const output = compose("hug-partner", ["$& the partner"], ["$` Theo"])
+    expect(output).toContain("$& the partner steps toward $` Theo")
+    expect(output).not.toContain("another person")
+  })
+  it("composes separate singular clauses for multiple named targets", () => {
+    expect(compose("wave-hello", ["Mira", "Theo"], [])).toBe(`${compose("wave-hello", ["Mira"], [])}; separately, ${compose("wave-hello", ["Theo"], [])}`)
+  })
+  it("keeps multiple-target semantics identical in compact mode", () => {
+    expect(compose("wave-hello", ["Mira", "Theo"], [], undefined, "compact")).toBe("Mira: waves hello; separately, Theo: waves hello")
+  })
+  it("binds an animal recipient in both modes through the shared graph path", () => {
+    const node = { id: "motion", type: "character-motion", data: { characterMotion: "signal-dog-to-sit" } }
+    const graph = { nodes: [node, { id: "dog", type: "creature", data: { creatureName: "Rex" } }], edges: [{ source: "dog", target: "motion", targetHandle: "partner" }] }
+    for (const hintMode of ["full", "compact"]) {
+      const text = getParameterPromptHint({ ...node, data: { ...node.data, hintMode } }, graph)
+      expect(text).toContain("Rex")
+      expect(text).not.toContain("the counterpart")
+    }
+    expect(getCharacterMotionBindings(node, graph).partnerNames).toEqual(["Rex"])
+  })
+  it("resolves saved deprecated ids and advertises a valid replacement", () => {
+    expect(compose("mount-the-horse", [], [])).not.toBe("")
+    for (const entry of CHARACTER_MOTIONS.filter(e => e.replacementId)) {
+      expect(getCharacterMotion(entry.replacementId)?.deprecated).not.toBe(true)
+      expect(getCharacterMotion(entry.replacementId)?.promptHint).toBeTruthy()
+    }
+  })
+  it("binds counterpart tokens in both modes with an explicit fallback", () => {
+    for (const entry of CHARACTER_MOTIONS.filter(e => e.counterpart)) {
+      expect(entry.promptHint, entry.id).toContain("the counterpart")
+      expect(entry.term, entry.id).toContain("the counterpart")
+      for (const mode of ["full", "compact"] as const) {
+        expect(compose(entry.id, [], [], undefined, mode), entry.id).not.toContain("the counterpart")
+        expect(compose(entry.id, [], ["Named recipient"], undefined, mode), entry.id).toContain("Named recipient")
+      }
+    }
+  })
+})
+describe("authored sequence diagnostics", () => {
+  it("flags exits, missing transitions, occupied hands and contradictory pace", () => {
+    expect(diagnose(["walk-out-left", "wave-hello"]).map(x => x.code)).toContain("visibility")
+    expect(diagnose(["crawl-head-raised", "wave-hello"]).map(x => x.code)).toContain("pose")
+    expect(diagnose(["hug-partner-from-behind", "wave-hello"]).map(x => x.code)).toContain("hands")
+    expect(diagnose("give-slow-blink", { pace: "explosive" }).map(x => x.code)).toContain("pace")
+    expect(diagnose("sun-salutation").map(x => x.code)).toContain("compound")
+  })
+  it("reports unknown and completely filtered selections without certifying unknown metadata", () => {
+    expect(diagnose("missing")[0]?.severity).toBe("error")
+    expect(diagnose("kiss-partner", undefined, { subjectMinor: true })[0]?.severity).toBe("error")
+    expect(diagnose(["hold-current-pose", "wave-hello"]).some(x => x.code === "pose")).toBe(false)
+  })
+  it("identifies the same graph reference in both roles without confusing equal display names", () => {
+    const node = { id: "motion", type: "character-motion", data: { characterMotion: "hug-partner" } }
+    const nodes = [node, { id: "a", type: "character", data: { characterName: "Mira" } }, { id: "b", type: "character", data: { characterName: "Mira" } }]
+    const edges = [{ source: "a", target: "motion", targetHandle: "target" }, { source: "a", target: "motion", targetHandle: "partner" }]
+    const bindings = getCharacterMotionBindings(node, { nodes, edges })
+    expect(diagnose("hug-partner", undefined, bindings).some(e => e.code === "roles" && e.severity === "error")).toBe(true)
+    expect(getCharacterMotionBindings(node, { nodes, edges: [edges[0]!, { ...edges[1]!, source: "b" }] }).selfPairing).toBe(false)
+  })
+  it("passes authored metadata through catalog discovery", () => {
+    const option = getPickerCatalog("character-motion")?.options?.find(e => e.id === "sun-salutation")
+    expect(option?.motion?.kind).toBe("compound")
+    expect(option?.motion?.requires).toContain("floor space")
+  })
+  it("keeps neutral dance and affection available while retaining sensual flags", () => {
+    for (const id of ["sashay-forward", "roll-the-body", "hug-partner-from-behind", "drop-coat-off-shoulders"]) expect(getCharacterMotion(id)?.adultOnly).toBeUndefined()
+    for (const id of ["sultry-look-over-shoulder", "kiss-partner", "bite-lip-teasingly"]) expect(getCharacterMotion(id)?.adultOnly).toBe(true)
+  })
+})

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-exit-visibility.test.ts

@@ -0,0 +1,183 @@
+/**
+ * `endVisibility: "out-of-frame"` coverage.
+ *
+ * The annotation is ADVISORY input to `getCharacterMotionDiagnostics`: present,
+ * it raises a "visibility" warning when a later move follows; absent, it raises
+ * nothing. Absence is therefore missing information, never a claim that the
+ * performer stays in shot — these tests assert what each entry DECLARES and
+ * what the diagnostic reports, and nothing about what a model renders.
+ */
+import { describe, expect, it } from "vitest"
+import { CHARACTER_MOTIONS, getCharacterMotion } from "../character-motion.js"
+import { getCharacterMotionDiagnostics as diagnose } from "../character-motion-diagnostics.js"
+
+/** Every entry whose authored text ends with the subject out of view. */
+const DECLARED_EXITS = [
+  // annotated from the start
+  "walk-out-left",
+  "walk-out-right",
+  "run-out-of-frame",
+  "back-out-of-frame",
+  "exit-past-camera",
+  "duck-out-of-frame",
+  "exit-through-doorway",
+  // added after an audit found their own text already said so
+  "dragged-out-of-frame",
+  "dash-across-frame",
+  "walk-off-waving",
+  "walk-past-camera",
+  "lean-into-frame",
+] as const
+
+/**
+ * Phrases that describe the performer leaving the frame. Used as a fail-closed
+ * guard, not as a classifier: a NEW entry whose text matches has to either
+ * declare the annotation or be added to EXIT_PHRASE_EXEMPT on purpose.
+ *
+ * WHAT IT DEFENDS. Every way the catalog and plausible new entries spell an
+ * exit with a frame word: "off screen" / "off-screen" / "off camera";
+ * "out of frame / shot / view / sight", with or without an article, which is
+ * what defeats a bare /out of (frame|shot)/ pattern ("runs out of THE shot");
+ * "leaves / exits the frame"; "disappears from view"; crossing an edge
+ * ("below the bottom edge of the frame" — how `duck-out-of-frame` says it);
+ * a trailing ", and is gone"; and the flat statements "no longer visible" and
+ * "lost from sight". The positive table below pins each of those spellings, so
+ * narrowing the pattern breaks a test rather than silently un-covering a class.
+ *
+ * WHAT IT DOES NOT DEFEND, and cannot without false positives here: an exit
+ * stated only by its CONSEQUENCE, with no frame word at all — "steps behind the
+ * pillar and is not seen again", "melts into the crowd", "recedes into the
+ * darkness". The obvious pattern for those, /disappears into|is gone/, fires on
+ * `apply-skincare` ("until it disappears into the skin") and `reel-in-leash`
+ * ("until the slack is gone"), both of which stay in full view. An entry that
+ * ends out of view and never says so in frame terms still needs a human to
+ * annotate it; this scan will not catch it. The negative table pins those two
+ * so a future widening cannot quietly re-break them.
+ */
+const EXIT_PHRASE = new RegExp([
+  String.raw`\boff[ -]?(?:screen|frame|camera)\b`,
+  String.raw`\bout[ -]of[ -](?:the[ -])?(?:frame|shot|screen|view|sight|camera)\b`,
+  String.raw`\b(?:leave|leaves|leaving|exit|exits|exiting)\s+(?:the\s+)?(?:frame|shot|screen|view)\b`,
+  String.raw`\b(?:disappear|vanish)(?:e?s|ing|ed)?\s+(?:from|off|out[ -]of)\s+(?:the\s+)?(?:frame|shot|screen|view|sight)\b`,
+  String.raw`\b(?:below|past|beyond|through)\s+(?:the\s+)?(?:[\w-]+\s+){0,2}(?:edge|bottom|top|side)\s+of\s+(?:the\s+)?frame\b`,
+  String.raw`\b(?:and|then)\s+is\s+gone\b`,
+  String.raw`\b(?:no longer (?:visible|in (?:the )?(?:frame|shot|view))|(?:lost|hidden) from (?:view|sight))\b`,
+  String.raw`\bgone out\b`,
+  String.raw`\bexiting behind\b`,
+  String.raw`\bout the far side\b`,
+].join("|"), "i")
+
+/**
+ * "Off screen" as the thing LOOKED AT, not the place the performer went:
+ * "an off-screen sound", "toward something off-frame", "gaze from off-frame".
+ * Stripped before the scan rather than exempted by id, so the four entries that
+ * use it — and any future one — pass without an exemption, while an entry that
+ * says BOTH ("hears an off-screen shout and walks off screen") still trips the
+ * guard on its second phrase. Deliberately narrow: only the attributive and
+ * "from" forms, never a verb-distance heuristic, which would suppress
+ * "looks back, then walks off screen".
+ */
+const LOOKED_AT = new RegExp([
+  String.raw`\b(?:something|someone|somewhere|anything)\s+off[ -]?(?:screen|frame|camera)\b`,
+  String.raw`\boff[ -]?(?:screen|frame|camera)\s+(?:sound|noise|voice|light|source|object|person|movement|motion|thing)\b`,
+  String.raw`\bfrom\s+off[ -]?(?:screen|frame|camera)\b`,
+].join("|"), "gi")
+
+/** True when the text says the PERFORMER ends out of view. */
+const scansAsExit = (text: string): boolean => EXIT_PHRASE.test(text.replace(LOOKED_AT, " "))
+
+/**
+ * Entries the phrase scan still matches although the SUBJECT ends in view. Each
+ * is a genuine exception, not an oversight:
+ *  - peek-into-frame     — the head holds in view; "the rest of the body" is
+ *                          what stays out of frame.
+ *  - look-off-screen-*   — "something out of frame" is the thing looked AT.
+ *                          (The "off-screen" spelling of the same idea needs no
+ *                          exemption — LOOKED_AT strips it — but these two say
+ *                          "out of frame", which an exit says too.)
+ */
+const EXIT_PHRASE_EXEMPT = new Set(["peek-into-frame", "look-off-screen-left", "look-off-screen-right"])
+
+describe("character motion — entries that declare an out-of-frame ending", () => {
+  it("annotates every move whose text ends with the subject out of view", () => {
+    for (const id of DECLARED_EXITS) {
+      expect(getCharacterMotion(id)?.endVisibility, id).toBe("out-of-frame")
+    }
+  })
+
+  // Deliberately NOT asserting that these twelve are the WHOLE set: a thirteenth
+  // entry annotating itself correctly is the outcome we want, not a test failure.
+  // The fail-closed guard below is what catches an entry that SHOULD annotate.
+
+  it("fails closed on a new entry whose text uses an exit phrase", () => {
+    const unannotated = CHARACTER_MOTIONS.filter(
+      (m) =>
+        (scansAsExit(m.promptHint) || scansAsExit(m.term ?? "")) &&
+        m.endVisibility !== "out-of-frame" &&
+        !EXIT_PHRASE_EXEMPT.has(m.id),
+    ).map((m) => m.id)
+    expect(unannotated, "annotate endVisibility, or add to EXIT_PHRASE_EXEMPT with a reason").toEqual([])
+  })
+
+  it("scans all twelve declared exits by phrase, not just by the pin above", () => {
+    // The explicit list is a pin; this asserts the GUARD would have caught each
+    // of them on its own, so the scan is demonstrably wide enough for the
+    // phrasings the catalog actually uses.
+    for (const id of DECLARED_EXITS) {
+      const entry = getCharacterMotion(id)!
+      expect(scansAsExit(`${entry.promptHint} ${entry.term ?? ""}`), id).toBe(true)
+    }
+  })
+})
+
+describe("character motion — what the exit-phrase scan does and does not catch", () => {
+  // A heuristic that looks broad and is not is worse than a narrow one: these
+  // two tables ARE the scan's contract. Shrink the pattern and the first fails;
+  // widen it carelessly and the second does.
+  it.each([
+    "the subject walks off screen to the left",
+    "the subject walks off-screen without looking back",
+    "the subject leaves the frame at a jog",
+    "the subject exits the shot",
+    "the subject strides away until out of sight",
+    "the subject runs out of the shot",
+    "the subject backs out of frame",
+    "the subject walks off camera",
+    "the subject disappears from view behind the pillar",
+    "the subject ducks below the bottom edge of the frame",
+    "the subject edges sideways along the wall and slips off screen at the left, never looking back, and is gone",
+    "the subject steps out the far side of the doorway",
+    "the subject walks away and is no longer visible",
+    "the subject slips into the alley, lost from sight",
+  ])("catches an exit phrased as %j", (text) => {
+    expect(scansAsExit(text)).toBe(true)
+  })
+
+  it.each([
+    // The performer stays in view; something ELSE is off screen or gone.
+    "the subject snaps the head toward an off-screen sound in one sharp turn",
+    "slides the eyes hard to one side toward something off-frame without turning the head",
+    "the subject lifts their gaze from off-frame and locks eyes straight into the lens",
+    "the subject reacts to something off-screen then swings the gaze back to the lens",
+    "walks a few paces forward to stop in clear view",
+    "rubs it in with upward circles of the fingers until it disappears into the skin",
+    "drawing it back to the hip until the slack is gone",
+    "the subject leans the head and one shoulder into view from the right edge of the frame",
+  ])("does not fire on %j", (text) => {
+    expect(scansAsExit(text)).toBe(false)
+  })
+})
+
+describe("character motion — the advisory visibility diagnostic", () => {
+  it("warns when a declared exit is sequenced before another move", () => {
+    for (const id of ["dragged-out-of-frame", "walk-off-waving", "walk-past-camera"]) {
+      const warning = diagnose([id, "wave-hello"]).find((d) => d.code === "visibility")
+      expect(warning?.severity, id).toBe("warning")
+      expect(warning?.ids, id).toEqual([id, "wave-hello"])
+    }
+  })
+
+  it("stays silent when the declared exit is last — nothing follows it", () => {
+    expect(diagnose(["wave-hello", "walk-off-waving"]).some((d) => d.code === "visibility")).toBe(false)
+  })
+})

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

@@ -0,0 +1,225 @@
+/**
+ * The unwired partner / counterpart referent.
+ *
+ * A two-person hint can name "the partner" up to five times, and 74 of the 100
+ * two-person hints name it more than once. Substituting the same INDEFINITE
+ * fallback at every occurrence ("another person … another person's back … as
+ * another person arches") reads as several different people. The composer now
+ * introduces the referent at its first occurrence in the composed string and
+ * refers back to it afterwards ("that same person"); the wired path, where the
+ * name is already unambiguous, is a plain global replace exactly as before.
+ */
+import { describe, expect, it } from "vitest"
+import {
+  CHARACTER_MOTIONS,
+  composeCharacterMotionHintFromConnections as compose,
+  getCharacterMotionPromptHint as hintOf,
+  getCharacterMotionTerm as termOf,
+} from "../character-motion.js"
+
+const RECIPIENT = /\bthe (partner|counterpart)\b/g
+const mentions = (text: string) => (text.match(RECIPIENT) ?? []).length
+/** Every entry whose text addresses a second participant, in either mode. */
+const recipientEntries = CHARACTER_MOTIONS.filter(
+  (m) => mentions(m.promptHint) > 0 || mentions(m.term ?? "") > 0,
+)
+
+describe("character motion — the wired path is a plain global replace", () => {
+  it("has entries to check", () => {
+    expect(recipientEntries.length).toBeGreaterThan(100)
+  })
+
+  it("substitutes a wired name at EVERY occurrence, in both modes", () => {
+    for (const entry of recipientEntries) {
+      const named = (text: string) =>
+        text.replace(/\bthe subject\b/g, "Aria").replace(RECIPIENT, "Ben")
+      expect(compose(entry.id, ["Aria"], ["Ben"]), `${entry.id} full`).toBe(named(hintOf(entry.id)))
+      expect(compose(entry.id, ["Aria"], ["Ben"], undefined, "compact"), `${entry.id} compact`).toBe(
+        `Aria: ${named(termOf(entry.id))}`,
+      )
+    }
+  })
+
+  it("substitutes a wired name at every occurrence of EVERY target clause too", () => {
+    // Multiple targets are what the per-target referent scope touches; the wired
+    // path must stay a plain global replace there as well, byte for byte.
+    for (const entry of recipientEntries) {
+      const named = (text: string, subject: string) =>
+        text.replace(/\bthe subject\b/g, subject).replace(RECIPIENT, "Ben")
+      expect(compose(entry.id, ["Mira", "Ada"], ["Ben"]), `${entry.id} full`).toBe(
+        `${named(hintOf(entry.id), "Mira")}; separately, ${named(hintOf(entry.id), "Ada")}`,
+      )
+      expect(compose(entry.id, ["Mira", "Ada"], ["Ben"], undefined, "compact"), `${entry.id} compact`).toBe(
+        `Mira: ${named(termOf(entry.id), "Mira")}; separately, Ada: ${named(termOf(entry.id), "Ada")}`,
+      )
+    }
+  })
+
+  it("never rewrites a repeated wired name — it is already unambiguous", () => {
+    const repeated = recipientEntries.filter((m) => mentions(m.promptHint) > 1)
+    expect(repeated.length).toBeGreaterThan(70)
+    for (const entry of repeated) {
+      const out = compose(entry.id, ["Aria"], ["Ben"])
+      expect(out.match(/\bBen\b/g)?.length, entry.id).toBe(mentions(entry.promptHint))
+      expect(out, entry.id).not.toContain("that same")
+    }
+  })
+})
+
+describe("character motion — an unwired recipient is one referent", () => {
+  it("no authored text already contains the composed referent phrases", () => {
+    // Guards the counting assertions below against a hint that happens to
+    // spell "another person" or "that same …" on its own.
+    for (const entry of CHARACTER_MOTIONS) {
+      expect(`${entry.promptHint} ${entry.term ?? ""}`, entry.id).not.toMatch(/another person|that same/)
+    }
+  })
+
+  it("introduces 'another person' exactly once per entry and refers back after", () => {
+    const twoPerson = CHARACTER_MOTIONS.filter((m) => mentions(m.promptHint) > 0 && m.twoPerson)
+    expect(twoPerson.length).toBeGreaterThan(90)
+    for (const entry of twoPerson) {
+      const out = compose(entry.id, ["Aria"], [])
+      expect(out, entry.id).not.toMatch(/\bthe partner\b/)
+      expect(out.match(/another person/g)?.length, entry.id).toBe(1)
+      expect(out.match(/that same person/g)?.length ?? 0, entry.id).toBe(mentions(entry.promptHint) - 1)
+    }
+  })
+
+  it("renders possessives on both mentions", () => {
+    expect(compose("dip-the-partner", ["Mira"], [], undefined, "full")).toBe(
+      "Mira steps forward and dips another person backward, one arm supporting that same person's back " +
+        "as that same person arches the spine and extends one leg, holding the dip then lifting them upright",
+    )
+  })
+
+  it("shares ONE referent across the picks of a sequence", () => {
+    const out = compose(["dip-the-partner", "spin-partner"], ["Mira"], [])
+    expect(out.match(/another person/g)).toHaveLength(1)
+    expect(out.indexOf("another person")).toBeLessThan(out.indexOf("that same person"))
+    // The second pick refers back to the person the first pick introduced.
+    expect(out).toContain("then Mira raises that same person's hand overhead")
+  })
+
+  it("shares that referent in compact mode too — same rule, same scope", () => {
+    expect(compose(["dip-the-partner", "spin-partner"], ["Mira"], [], undefined, "compact")).toBe(
+      "Mira: dips another person backward, then spins that same person under the arm",
+    )
+  })
+
+  /**
+   * Each target performs a SEPARATE COPY of the sequence — the promise the
+   * `multiple-targets` diagnostic makes to the user — so the referent is scoped
+   * to one target's clauses, NOT to the whole composed string. Sharing it across
+   * the "; separately, " join made the second performer act on the first
+   * performer's partner: one person bridal-carried by two people at once.
+   */
+  it("gives each target its OWN partner — a separate copy of the sequence", () => {
+    const out = compose("carry-partner-bridal", ["Mira", "Ada"], [])
+    expect(out.match(/another person/g), "one introduction per target").toHaveLength(2)
+    expect(out).toBe(
+      "Mira scoops another person up in a bridal carry, one arm under that same person's knees " +
+        "and the other behind that same person's back, that same person's arm around Mira's neck, " +
+        "and walks forward carrying that same person" +
+        "; separately, " +
+        "Ada scoops another person up in a bridal carry, one arm under that same person's knees " +
+        "and the other behind that same person's back, that same person's arm around Ada's neck, " +
+        "and walks forward carrying that same person",
+    )
+  })
+
+  it("keeps BOTH scopes at once: per target, shared across that target's picks", () => {
+    const out = compose(["dip-the-partner", "spin-partner"], ["Mira", "Ada"], [])
+    // Two targets ⇒ two introductions; each target's second pick refers back to
+    // its own, across the other target's clause interleaved between them.
+    expect(out.match(/another person/g)).toHaveLength(2)
+    expect(out).toContain("Mira steps forward and dips another person backward")
+    expect(out).toContain("; separately, Ada steps forward and dips another person backward")
+    expect(out).toContain("then Mira raises that same person's hand overhead")
+    expect(out).toContain("; separately, Ada raises that same person's hand overhead")
+  })
+
+  it("scopes per target in compact mode on the same rule", () => {
+    expect(compose(["dip-the-partner", "spin-partner"], ["Mira", "Ada"], [], undefined, "compact")).toBe(
+      "Mira: dips another person backward; separately, Ada: dips another person backward, " +
+        "then Mira: spins that same person under the arm; separately, Ada: spins that same person under the arm",
+    )
+  })
+})
+
+describe("character motion — counterpart nouns are tracked per referent", () => {
+  it("introduces an indefinite animal noun once, then refers back", () => {
+    expect(compose("stroke-horse-neck", ["Mira"], [])).toBe(
+      "Mira lays a flat palm high on a horse's neck and sweeps it down the length of the crest " +
+        "in long full strokes, the other hand resting at that same horse's shoulder",
+    )
+  })
+
+  it("carries one referent across picks that declare the SAME noun", () => {
+    expect(compose(["pet-a-dog", "offer-a-treat"], ["Mira"], [])).toContain(
+      "extends an open palm holding a treat toward that same dog",
+    )
+  })
+
+  it("gives picks with DIFFERENT nouns their own introductions", () => {
+    const out = compose(["pet-a-dog", "stroke-horse-neck"], ["Mira"], [])
+    expect(out).toContain("onto a dog's head")
+    expect(out).toContain("high on a horse's neck")
+    expect(out).not.toContain("that same dog")
+  })
+
+  /**
+   * The definite-noun exemption is only REACHABLE on a second mention, and no
+   * single entry mentions its definite counterpart twice — so a per-entry loop
+   * of single picks asserts nothing: it passes with or without the branch.
+   * These cases compose two picks that declare the SAME definite noun, which is
+   * what puts a second mention in front of `laterReferenceTo`. Verified by
+   * mutation: widen its regex to /^(?:another|an|a|the) (.+)$/ and this block
+   * fails with "that same held object".
+   */
+  describe("a DEFINITE recipient noun repeats verbatim — it already names one referent", () => {
+    /** Definite nouns declared by two or more entries — the only way to reach a second mention. */
+    const definitePairs = [
+      ...CHARACTER_MOTIONS.filter((m) => m.counterpart?.startsWith("the ")).reduce((byNoun, m) => {
+        byNoun.set(m.counterpart!, [...(byNoun.get(m.counterpart!) ?? []), m.id])
+        return byNoun
+      }, new Map<string, string[]>()),
+    ].filter(([, ids]) => ids.length > 1)
+
+    it("has a repeatable definite noun to test — otherwise the cases below are vacuous", () => {
+      expect(definitePairs.length).toBeGreaterThan(0)
+    })
+
+    it.each(definitePairs)("repeats %j on every mention across the picks that share it", (noun, ids) => {
+      const picks = ids.slice(0, 3)
+      const out = compose(picks, ["Mira"], [])
+      const mentioned = picks.reduce((n, id) => n + mentions(hintOf(id)), 0)
+      // Non-vacuity, asserted rather than assumed: this composition really does
+      // put the noun in front of the composer more than once.
+      expect(mentioned, `${noun} is mentioned once — the exemption is not exercised`).toBeGreaterThan(1)
+      expect(out.match(new RegExp(noun, "g")), noun).toHaveLength(mentioned)
+      expect(out, noun).not.toContain("that same")
+    })
+
+    it("spells the two-pick held-object case out in full", () => {
+      expect(compose(["set-object-down", "hold-object-still"], ["Mira"], [])).toBe(
+        "Mira lowers the held object onto the nearby supporting surface, releases it and draws both hands away, " +
+          "then Mira keeps the held object steady in both hands without changing its orientation",
+      )
+    })
+
+    it("rewrites an INDEFINITE noun in the very same two-pick shape", () => {
+      // The contrast that proves the exemption is a real branch and not a
+      // property of two-pick composition: same shape, indefinite noun, rewritten.
+      expect(compose(["pet-a-dog", "offer-a-treat"], ["Mira"], [])).toContain("that same dog")
+    })
+
+    it("still repeats a definite noun verbatim in a single pick", () => {
+      for (const entry of CHARACTER_MOTIONS.filter((m) => m.counterpart?.startsWith("the "))) {
+        const out = compose(entry.id, ["Mira"], [])
+        expect(out, entry.id).toContain(entry.counterpart!)
+        expect(out, entry.id).not.toContain("that same")
+      }
+    })
+  })
+})