@nodaro/prompts 1.20.0 → 1.21.0

package/src/__tests__/frame-delivery.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from "vitest"
+import { planFrameDelivery } from "../frame-delivery.js"
+
+const START = "https://cdn.example/start.png"
+const END = "https://cdn.example/end.png"
+
+describe("planFrameDelivery", () => {
+  it("keeps a frame as a frame on a model whose frame mode measured fine", () => {
+    const plan = planFrameDelivery({
+      provider: "seedance-2-5", supportsReferenceImages: true, startFrameUrl: START, prompt: "a walk",
+    })
+    expect(plan).toEqual({ delivery: "frame", referenceImageUrls: [], promptSuffix: "" })
+  })
+
+  it("moves the frame into the reference list on the Seedance 2.0 family", () => {
+    const plan = planFrameDelivery({
+      provider: "seedance-2-fast", supportsReferenceImages: true, startFrameUrl: START,
+    })
+    expect(plan.delivery).toBe("reference")
+    expect(plan.referenceImageUrls).toEqual([START])
+    expect(plan.promptSuffix).toBe("Use @image_1 as the opening (first) frame of the video.")
+  })
+
+  it("appends frames after the user's own images so their ordinals hold", () => {
+    const plan = planFrameDelivery({
+      provider: "seedance-2-fast",
+      supportsReferenceImages: true,
+      startFrameUrl: START,
+      endFrameUrl: END,
+      userReferenceUrls: ["https://cdn.example/a.png", "https://cdn.example/b.png"],
+    })
+    expect(plan.referenceImageUrls).toEqual(["https://cdn.example/a.png", "https://cdn.example/b.png", START, END])
+    expect(plan.promptSuffix).toContain("@image_3 as the opening (first) frame")
+    expect(plan.promptSuffix).toContain("@image_4 as the closing (last) frame")
+  })
+
+  it("adds no second opening sentence when the prompt already binds one", () => {
+    const plan = planFrameDelivery({
+      provider: "seedance-2-fast",
+      supportsReferenceImages: true,
+      startFrameUrl: START,
+      prompt: "Use @image_1 as the first frame, it is the last keyframe of @video_1",
+    })
+    expect(plan.delivery).toBe("reference")
+    expect(plan.promptSuffix).toBe("")
+  })
+
+  it("honours an explicit choice in both directions", () => {
+    expect(planFrameDelivery({
+      provider: "seedance-2-fast", requested: "frame", supportsReferenceImages: true, startFrameUrl: START,
+    }).delivery).toBe("frame")
+    expect(planFrameDelivery({
+      provider: "veo3.1", requested: "reference", supportsReferenceImages: true, startFrameUrl: START,
+    }).delivery).toBe("reference")
+  })
+
+  it("refuses, with a reason, on a model that takes no reference images", () => {
+    const plan = planFrameDelivery({
+      provider: "wan-i2v", requested: "reference", supportsReferenceImages: false, startFrameUrl: START,
+    })
+    expect(plan).toMatchObject({ delivery: "frame", refusedReason: "no-reference-support" })
+  })
+
+  it("refuses rather than displace a user's reference image at the cap", () => {
+    const refs = Array.from({ length: 9 }, (_, i) => `https://cdn.example/ref-${i}.png`)
+    const plan = planFrameDelivery({
+      provider: "seedance-2-fast", supportsReferenceImages: true, startFrameUrl: START, userReferenceUrls: refs,
+    })
+    expect(plan).toMatchObject({ delivery: "frame", refusedReason: "image-cap" })
+    expect(plan.referenceImageUrls).toEqual(refs)
+  })
+
+  it("is a no-op when no frame is wired", () => {
+    const plan = planFrameDelivery({ provider: "seedance-2-fast", supportsReferenceImages: true })
+    expect(plan).toEqual({ delivery: "frame", referenceImageUrls: [], promptSuffix: "" })
+  })
+
+  it("plans the same shape whether it is asked with urls or with stand-ins", () => {
+    // The config panel knows a frame is wired before it knows its url, so it
+    // passes placeholders. Ordering and sentences must not depend on the string.
+    const real = planFrameDelivery({
+      provider: "seedance-2-mini", supportsReferenceImages: true, startFrameUrl: START, endFrameUrl: END,
+      userReferenceUrls: ["https://cdn.example/a.png"],
+    })
+    const preview = planFrameDelivery({
+      provider: "seedance-2-mini", supportsReferenceImages: true, startFrameUrl: "frame:start", endFrameUrl: "frame:end",
+      userReferenceUrls: ["ref:0"],
+    })
+    expect(preview.delivery).toBe(real.delivery)
+    expect(preview.promptSuffix).toBe(real.promptSuffix)
+    expect(preview.referenceImageUrls).toHaveLength(real.referenceImageUrls.length)
+  })
+})

package/src/__tests__/graph-composed-unwired-identity.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect } from "vitest"
+
+import { getParameterPromptHint } from "../parameter-prompt-hint.js"
+import { getPickerCatalog, type PickerOption } from "../picker-catalogs.js"
+import { composeTransitionHintFromConnections } from "../transitions.js"
+import { composeCharacterFxHintFromConnections } from "../character-fx.js"
+import type { HintEdgeLike, HintGraphContext, HintNodeLike } from "@nodaro/shared"
+
+/**
+ * THE BOUND ON "compose transition and character-fx from the graph on every
+ * path", as a proof rather than a claim.
+ *
+ * Transition and character-fx joined `EXECUTION_GRAPH_COMPOSED_PARAMETER_TYPES`
+ * (@nodaro/shared) and `LABEL_REF_GRAPH_COMPOSED_PARAMETER_TYPES` (backend
+ * `services/workflow-engine/label-ref-hint-context.ts`), so every executor now
+ * hands them the graph. That deliberately changes the prompt of a workflow that
+ * WIRES them — signed off, and the new text is the text the picker's own
+ * injection preview has always shown.
+ *
+ * What was signed off with it is the BOUND: a picker with nothing wired to its
+ * own composing handles (`startState` / `endState` for transition, `target` for
+ * character-fx) must emit BYTE-IDENTICAL text with and without the graph, so a
+ * workflow that wires nothing cannot move at all. This file walks every entry
+ * of both catalogs, in both hint modes, under two unwired graph shapes, and
+ * asserts that equality — then proves it is not vacuous with wired positive
+ * controls that MUST differ.
+ *
+ * Why two unwired shapes: "unwired" in a real workflow does not mean an
+ * isolated node. The picker is normally wired INTO a consumer (an outgoing
+ * `cinematography` edge) while nothing feeds its own handles — the walker in
+ * `resolveParameterHint` only ever looks at edges whose TARGET is the picker,
+ * and this pins that.
+ */
+
+const MODES = ["full", "compact"] as const
+
+/** The two pickers this change admitted, with the data field each reads. */
+const SUBJECTS = [
+  { type: "transition", valueField: "transition" },
+  { type: "character-fx", valueField: "characterFx" },
+] as const
+
+function optionsFor(type: string): readonly PickerOption[] {
+  const catalog = getPickerCatalog(type)
+  if (!catalog?.options?.length) throw new Error(`no registered picker catalog options for ${type}`)
+  return catalog.options
+}
+
+function pickerNode(type: string, valueField: string, id: string, mode: string): HintNodeLike {
+  return { id: "picker", type, data: { [valueField]: id, hintMode: mode } }
+}
+
+/** Nothing at all around the picker. */
+function isolated(node: HintNodeLike): HintGraphContext {
+  return { nodes: [node], edges: [] }
+}
+
+/** The realistic unwired shape: the picker FEEDS a consumer, but nothing feeds it. */
+function wiredIntoConsumer(node: HintNodeLike): HintGraphContext {
+  const consumer: HintNodeLike = { id: "consumer", type: "generate-video", data: { prompt: "a man walks forward" } }
+  const edges: HintEdgeLike[] = [
+    { source: node.id, target: consumer.id, sourceHandle: null, targetHandle: "cinematography" },
+  ]
+  return { nodes: [node, consumer], edges }
+}
+
+const UNWIRED_SHAPES = [
+  { name: "isolated (no edges at all)", build: isolated },
+  { name: "wired INTO a consumer, nothing wired into it", build: wiredIntoConsumer },
+] as const
+
+describe("unwired transition / character-fx pickers are byte-identical with and without the graph", () => {
+  for (const { type, valueField } of SUBJECTS) {
+    for (const { name, build } of UNWIRED_SHAPES) {
+      it(`${type}: every catalog entry × both hint modes, ${name}`, () => {
+        const options = optionsFor(type)
+        const differences: string[] = []
+        let compared = 0
+
+        for (const option of options) {
+          for (const mode of MODES) {
+            const node = pickerNode(type, valueField, option.id, mode)
+            const withoutGraph = getParameterPromptHint(node)
+            const withGraph = getParameterPromptHint(node, build(node))
+            compared += 1
+            if (withGraph !== withoutGraph) {
+              differences.push(`${type}/${option.id}/${mode}: ${JSON.stringify(withoutGraph)} -> ${JSON.stringify(withGraph)}`)
+            }
+          }
+        }
+
+        // Non-vacuity of the WALK itself: a catalog that somehow arrived empty
+        // would pass a zero-difference assertion trivially.
+        expect(compared).toBe(options.length * MODES.length)
+        expect(compared).toBeGreaterThan(20)
+        expect(differences).toEqual([])
+      })
+    }
+  }
+
+  it("the catalogs really do carry injecting entries (the comparison is over real text, not all empty strings)", () => {
+    // `auto` / `none` inject "" by design and are legitimately compared; this
+    // asserts they are not ALL of it, so the identity above is meaningful.
+    for (const { type, valueField } of SUBJECTS) {
+      const injecting = optionsFor(type).filter(
+        (o) => getParameterPromptHint(pickerNode(type, valueField, o.id, "full")).trim().length > 0,
+      )
+      expect(injecting.length, type).toBeGreaterThan(20)
+    }
+  })
+})
+
+describe("positive control — a WIRED picker must differ (or the bound above proves nothing)", () => {
+  /** A tone node: free text, so its fragment is identical in both hint modes,
+   *  which keeps the control honest without re-deriving inherited-mode text. */
+  const tone = (id: string, text: string): HintNodeLike => ({ id, type: "tone", data: { tone: text } })
+
+  it("transition: a startState + endState wire changes the text, in both modes", () => {
+    const id = optionsFor("transition").find(
+      (o) => getParameterPromptHint(pickerNode("transition", "transition", o.id, "full")).trim().length > 0,
+    )!.id
+    const start = tone("start", "warm golden morning light")
+    const end = tone("end", "cold blue dusk")
+
+    for (const mode of MODES) {
+      const node = pickerNode("transition", "transition", id, mode)
+      const ctx: HintGraphContext = {
+        nodes: [node, start, end],
+        edges: [
+          { source: "start", target: node.id, sourceHandle: null, targetHandle: "startState" },
+          { source: "end", target: node.id, sourceHandle: null, targetHandle: "endState" },
+        ],
+      }
+      const composed = getParameterPromptHint(node, ctx)
+      expect(composed).not.toBe(getParameterPromptHint(node))
+      // Derived from the catalog composer, never a hand-written sentence.
+      expect(composed).toBe(
+        composeTransitionHintFromConnections(
+          id,
+          [getParameterPromptHint(start)],
+          [getParameterPromptHint(end)],
+          undefined,
+          mode,
+        ),
+      )
+    }
+  })
+
+  it("character-fx: a target ref wire changes the text, in both modes", () => {
+    const id = optionsFor("character-fx").find(
+      (o) => getParameterPromptHint(pickerNode("character-fx", "characterFx", o.id, "full")).trim().length > 0,
+    )!.id
+    const mira: HintNodeLike = { id: "mira", type: "character", data: { characterName: "Mira" } }
+
+    for (const mode of MODES) {
+      const node = pickerNode("character-fx", "characterFx", id, mode)
+      const ctx: HintGraphContext = {
+        nodes: [node, mira],
+        edges: [{ source: "mira", target: node.id, sourceHandle: null, targetHandle: "target" }],
+      }
+      const composed = getParameterPromptHint(node, ctx)
+      expect(composed).not.toBe(getParameterPromptHint(node))
+      expect(composed).toBe(composeCharacterFxHintFromConnections(id, ["Mira"], undefined, mode))
+    }
+  })
+})

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

@@ -330,8 +330,14 @@ describe("getParameterPromptHint — character-motion minor-age floor", () => {
   const ADULT = { age: "age-30s" }
   const motion = { id: "n1", type: "character-motion", data: { characterMotion: ["wave-hello", "kiss-partner"] } }
   const wave = (target: string) => getCharacterMotionPromptHint("wave-hello").replace(/\bthe subject\b/g, target)
-  const kiss = (target: string, partner: string) =>
-    getCharacterMotionPromptHint("kiss-partner").replace(/\bthe subject\b/g, target).replace(/\bthe partner\b/g, partner)
+  // kiss-partner names the partner twice. A wired name repeats; the unwired
+  // fallback is introduced once and referred back to after that.
+  const kiss = (target: string, ...partner: readonly string[]) => {
+    let i = 0
+    return getCharacterMotionPromptHint("kiss-partner")
+      .replace(/\bthe subject\b/g, target)
+      .replace(/\bthe partner\b/g, () => partner[Math.min(i++, partner.length - 1)]!)
+  }
 
   it("a minor wired to target drops the adult-only move and keeps the neutral one", () => {
     const out = getParameterPromptHint(motion, {
@@ -347,7 +353,7 @@ describe("getParameterPromptHint — character-motion minor-age floor", () => {
       nodes: [{ id: "c1", type: "character", data: { characterName: "Mira", person: ADULT } }],
       edges: [{ source: "c1", target: "n1", targetHandle: "target" }],
     })
-    expect(out).toBe(`${wave("Mira")}, then ${kiss("Mira", "another person")}`)
+    expect(out).toBe(`${wave("Mira")}, then ${kiss("Mira", "another person", "that same person")}`)
     expect(out).toMatch(/kiss/)
   })
 

package/src/character-motion/animals-pets.ts

@@ -1,89 +1,116 @@
 import type { CharacterMotion } from "./types.js"
 
-/** Animals & Pets — 28 entries. Category id `animals-pets`. */
+/** animals-pets — authored motion fragments. Stable ids survive copy revisions. */
 export const ANIMALS_PETS_MOTIONS: ReadonlyArray<CharacterMotion> = [
-  { id: "pet-a-dog", label: "Pet a Dog", category: "animals-pets", description: "Flat hand strokes over the dog's skull and neck",
-    promptHint: "the subject lowers an open hand onto a dog's head, draws the flat palm back over the skull to the base of the neck, lifts the hand away and repeats the stroke",
-    term: "pets a dog on the head" },
-  { id: "scratch-behind-ears", label: "Scratch Behind Ears", category: "animals-pets", description: "Fingertips work in small circles behind an ear",
-    promptHint: "the subject reaches to the side of an animal's head and works curled fingertips in small circles behind one ear, the wrist rocking, the other hand resting under the muzzle",
-    term: "scratches behind the ears" },
-  { id: "ruffle-dog-fur", label: "Ruffle Dog Fur", category: "animals-pets", description: "Fingers scrub through the thick fur at the neck",
-    promptHint: "the subject sinks the fingers deep into the thick fur at a dog's neck and scrubs them briskly back and forth through the coat, elbows pumping, then opens the fingers and lifts the hands away",
-    term: "ruffles a dog's fur with both hands" },
-  { id: "scoop-up-pet", label: "Scoop Up Pet", category: "animals-pets", description: "Bends, slides both hands under, lifts to the chest",
-    promptHint: "the subject bends at the knees, slides one hand under a small pet's chest and the other under its hindquarters, and straightens upright, drawing the animal in against the subject's chest",
-    term: "scoops up a small pet" },
-  { id: "offer-hand-to-sniff", label: "Offer Hand to Sniff", category: "animals-pets", description: "Arm extends, knuckles down, hand held still",
-    promptHint: "the subject extends one arm forward at waist height with the fingers curled and the knuckles down, stops the hand short of the animal and holds it motionless, shoulders loose",
-    term: "holds out a hand to be sniffed" },
-  { id: "offer-a-treat", label: "Offer a Treat", category: "animals-pets", description: "Flat open palm held out at arm length",
-    promptHint: "the subject brings a treat out of a pocket, flattens the palm with the fingers pressed straight, extends the arm forward at waist height and holds the hand steady while a dog lips the treat off the open palm",
-    term: "offers a treat on an open palm" },
-  { id: "get-pulled-by-leash", label: "Get Pulled by Leash", category: "animals-pets", description: "Leash snaps taut and drags the arm forward",
-    promptHint: "the subject is yanked forward as the leash snaps taut and stumbles a step with one shoulder dragged ahead of the torso, then leans the weight back and digs the heels in",
-    term: "gets pulled along by the leash" },
-  { id: "reel-in-leash", label: "Reel In Leash", category: "animals-pets", description: "Hand over hand shortens the leash",
-    promptHint: "the subject gathers the leash hand over hand, each fist closing on the line and drawing it back to the hip until the slack is gone, the elbow tucked tight against the ribs",
-    term: "reels in the leash hand over hand" },
-  { id: "throw-ball-for-dog", label: "Throw Ball for Dog", category: "animals-pets", description: "Overhand wind-up, release, follow-through",
-    promptHint: "the subject cocks the throwing arm back past the shoulder, steps onto the front foot, whips the arm forward and releases a ball, the hand following through down across the opposite hip",
-    term: "throws a ball for a dog" },
-  { id: "kneel-to-greet", label: "Kneel to Greet", category: "animals-pets", description: "Drops to one knee and opens both arms",
-    promptHint: "the subject drops onto one knee, spreads both arms wide and leans the chest forward, closing both hands around a dog's shoulders and rocking back slightly under the weight",
-    term: "kneels down to greet a dog" },
-  { id: "signal-dog-to-sit", label: "Signal Dog to Sit", category: "animals-pets", description: "Flat palm raised, then pressed down and held",
-    promptHint: "the subject raises one flat palm to chest height, holds it still for a beat, and presses the hand down toward the ground in a firm level push, freezing it there",
-    term: "signals a dog to sit" },
-  { id: "call-dog-over", label: "Call Dog Over", category: "animals-pets", description: "Slaps thighs, whistles, crouches with arms open",
-    promptHint: "the subject slaps both palms against the thighs twice, cups one hand beside the mouth to whistle, and drops into a crouch with the arms spread open and waiting",
-    term: "calls a dog over" },
-  { id: "cuddle-pet-on-lap", label: "Cuddle Pet on Lap", category: "animals-pets", description: "Curls over a pet on the lap and strokes its back",
-    promptHint: "the subject curls the shoulders forward over a pet settled across the lap, runs one hand in long strokes down its back and lets the chin drop toward it",
-    term: "cuddles a pet on the lap" },
-  { id: "hold-cat-to-chest", label: "Hold Cat to Chest", category: "animals-pets", description: "Gathers a cat up against the sternum",
-    promptHint: "the subject gathers a cat up against the chest, one forearm braced under its hindquarters and the other hand flat along its back, and lowers the chin toward its head",
-    term: "holds a cat against the chest" },
-  { id: "lift-cat-up", label: "Lift Cat Up", category: "animals-pets", description: "Chest and hindquarters supported, lifted to eye level",
-    promptHint: "the subject slides one hand under a cat's chest just behind the front legs and the other under its hindquarters, lifts it up to eye level as the arms extend, holds it there a beat before drawing it back in against the chest",
-    term: "lifts a cat up to eye level" },
-  { id: "lift-puppy-to-face", label: "Lift Puppy to Face", category: "animals-pets", description: "Raises a puppy up nose to nose",
-    promptHint: "the subject raises a puppy in both hands from lap height up to eye level, lifts the chin and leans in until the two are nose to nose, then lowers the puppy back down against the subject's chest",
-    term: "holds a puppy up to the face" },
-  { id: "let-bird-perch", label: "Let Bird Perch", category: "animals-pets", description: "Index finger held out level and steady",
-    promptHint: "the subject holds one index finger out level in front of the chest and locks the elbow against the ribs to keep the hand from shaking, lifting the whole arm upward as a bird steps onto the finger",
-    term: "holds out a finger for a bird" },
-  { id: "feed-the-ducks", label: "Feed the Ducks", category: "animals-pets", description: "Breaks off pieces and tosses them underhand",
-    promptHint: "the subject reaches into a bag, pinches off small pieces and flicks them out underhand one after another with a loose wrist, stepping back a pace between tosses",
-    term: "feeds the ducks" },
-  { id: "stroke-horse-neck", label: "Stroke Horse Neck", category: "animals-pets", description: "Long flat-palm sweeps down the neck",
-    promptHint: "the subject 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 the horse's shoulder",
-    term: "strokes a horse's neck" },
-  { id: "brush-the-horse", label: "Brush the Horse", category: "animals-pets", description: "Long brush strokes along the lie of the coat",
-    promptHint: "the subject presses a brush to a horse's flank and pulls it in long strokes along the lie of the coat, the free hand steadying the horse ahead of each pass, the shoulder swinging with the motion",
-    term: "brushes a horse's coat" },
-  { id: "pat-horse-flank", label: "Pat Horse Flank", category: "animals-pets", description: "Two firm open-palm pats, then rests the hand",
-    promptHint: "the subject brings a flat hand in to pat a horse's flank twice with a firm open palm, then leaves the hand resting there and leans a little weight onto it",
-    term: "pats a horse on the flank" },
-  { id: "mount-the-horse", label: "Mount the Horse", category: "animals-pets", description: "Foot in the stirrup, swings the leg over",
-    promptHint: "the subject sets one foot into the stirrup, grips the saddle with both hands, springs off the ground and swings the trailing leg over, then settles down and finds the other stirrup",
-    term: "mounts a horse" },
-  { id: "back-away-slowly", label: "Back Away Slowly", category: "animals-pets", description: "Small heel-first steps back, palms raised",
-    promptHint: "the subject shifts the weight onto the back foot and takes small heel-first steps backward, palms raised open at chest height, the torso staying square and the gaze fixed forward",
-    term: "backs away slowly from an animal" },
-  { id: "let-it-approach", label: "Let It Approach", category: "animals-pets", description: "Goes completely still and waits it out",
-    promptHint: "the subject stops mid-step and goes completely still, arms hanging loose at the sides, the breathing shallow so the chest barely moves, only the eyes tracking the animal",
-    term: "freezes as an animal comes near" },
-  { id: "crouch-to-photograph", label: "Crouch to Photograph", category: "animals-pets", description: "Drops low and frames the animal with a phone",
-    promptHint: "the subject drops into a low crouch, braces the elbows on the knees and lifts a phone in both hands up in front of the face, holding dead still before tapping the screen with a thumb",
-    term: "crouches to photograph an animal" },
-  { id: "tug-the-toy", label: "Tug the Toy", category: "animals-pets", description: "Both fists on a rope toy, leaning back and pulling",
-    promptHint: "the subject grips a rope toy in both fists, leans the torso back against the pull and swings the toy side to side in short jerks before stepping in to let the tension go slack",
-    term: "tugs back and forth on a rope toy" },
-  { id: "wipe-muddy-paws", label: "Wipe Muddy Paws", category: "animals-pets", description: "Kneels and towels one paw at a time",
-    promptHint: "the subject kneels on one knee, lifts a dog's paw into a cupped hand, wraps a towel around it and rubs it clean, sets it back down and reaches for the next one",
-    term: "wipes a dog's muddy paws" },
-  { id: "brace-for-jump", label: "Brace for Jump", category: "animals-pets", description: "Plants the back foot to absorb a dog jumping up",
-    promptHint: "the subject plants the back foot and drops the pelvis to take a dog's weight against the chest, both hands rising to catch its shoulders, the torso rocking back then steadying",
-    term: "braces as a dog jumps up" },
+  { "id": "pet-a-dog", "label": "Pet a dog", "category": "animals-pets", "description": "Flat hand strokes over the dog's skull and neck",
+    "promptHint": "the subject lowers an open hand onto the counterpart's head, draws the flat palm back over the skull to the base of the neck, lifts the hand away and repeats the stroke", "term": "pets the counterpart on the head",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "scratch-behind-ears", "label": "Scratch behind ears", "category": "animals-pets", "description": "Fingertips work in small circles behind an ear",
+    "promptHint": "the subject reaches to the side of the counterpart's head and works curled fingertips in small circles behind one ear, the wrist rocking, the other hand resting under the muzzle", "term": "scratches behind the ears with the counterpart",
+    "counterpart": "an animal", "requires": ["animal"] },
+  { "id": "ruffle-dog-fur", "label": "Ruffle dog fur", "category": "animals-pets", "description": "Fingers scrub through the thick fur at the neck",
+    "promptHint": "the subject sinks the fingers deep into the thick fur at the counterpart's neck and scrubs them briskly back and forth through the coat, elbows pumping, then opens the fingers and lifts the hands away", "term": "ruffles the counterpart's fur with both hands",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "scoop-up-pet", "label": "Scoop up pet", "category": "animals-pets", "description": "Bends, slides both hands under, lifts to the chest",
+    "promptHint": "the subject bends at the knees, slides one hand under the counterpart's chest and the other under its hindquarters, and straightens upright, drawing the animal in against the subject's chest", "term": "scoops up the counterpart",
+    "counterpart": "a small pet", "requires": ["pet"] },
+  { "id": "offer-hand-to-sniff", "label": "Offer hand to sniff", "category": "animals-pets", "description": "Arm extends, knuckles down, hand held still",
+    "promptHint": "the subject extends one arm forward at waist height with the fingers curled and the knuckles down, stops the hand short of the counterpart and holds it motionless, shoulders loose", "term": "offers knuckles for the counterpart to sniff",
+    "counterpart": "the animal", "requires": ["animal"] },
+  { "id": "offer-a-treat", "label": "Offer treat to dog", "category": "animals-pets", "description": "Holds a treat out for the dog without requiring it to take it.",
+    "promptHint": "the subject extends an open palm holding a treat toward the counterpart and holds it steady, waiting for a response", "term": "offers the counterpart a treat on open palm",
+    "counterpart": "a dog", "requires": ["dog", "treat"], "aliases": ["Offer a Treat"] },
+  { "id": "get-pulled-by-leash", "label": "Get pulled by leash", "category": "animals-pets", "description": "Leash snaps taut and drags the arm forward",
+    "promptHint": "the subject is yanked forward as the leash snaps taut and stumbles a step with one shoulder dragged ahead of the torso, then leans the weight back and digs the heels in", "term": "gets pulled along by the leash" },
+  { "id": "reel-in-leash", "label": "Reel in leash", "category": "animals-pets", "description": "Hand over hand shortens the leash",
+    "promptHint": "the subject gathers the leash hand over hand, each fist closing on the line and drawing it back to the hip until the slack is gone, the elbow tucked tight against the ribs", "term": "reels in the leash hand over hand" },
+  { "id": "throw-ball-for-dog", "label": "Throw ball for dog", "category": "animals-pets", "description": "Throws a ball ahead of the dog without adding a fetch return.",
+    "promptHint": "the subject faces the same direction as the counterpart, draws the throwing arm back and throws a ball forward, following through with the arm", "term": "throws a ball ahead of the counterpart",
+    "counterpart": "a dog", "requires": ["dog", "ball"] },
+  { "id": "kneel-to-greet", "label": "Kneel to greet", "category": "animals-pets", "description": "Drops to one knee and opens both arms",
+    "promptHint": "the subject drops onto one knee, spreads both arms wide and leans the chest forward, closing both hands around the counterpart's shoulders and rocking back slightly under the weight", "term": "kneels down to greet the counterpart",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "signal-dog-to-sit", "label": "Signal dog to sit", "category": "animals-pets", "description": "Gives the dog a downward hand signal without requiring a response.",
+    "promptHint": "the subject faces the counterpart, raises a flat palm to chest height and lowers it in a deliberate downward signal, then waits", "term": "gives the counterpart a downward sit signal",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "call-dog-over", "label": "Call dog over", "category": "animals-pets", "description": "Crouches and beckons the dog, then waits.",
+    "promptHint": "the subject faces the counterpart, lowers into a crouch, pats one thigh and opens both hands in an inviting gesture, then waits", "term": "crouches and beckons the counterpart",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "cuddle-pet-on-lap", "label": "Cuddle pet on lap", "category": "animals-pets", "description": "Curls over a pet on the lap and strokes its back",
+    "promptHint": "the subject curls the shoulders forward over the counterpart settled across the lap, runs one hand in long strokes down its back and lets the chin drop toward it", "term": "cuddles the counterpart on the lap",
+    "counterpart": "a pet", "requires": ["pet"] },
+  { "id": "hold-cat-to-chest", "label": "Hold cat to chest", "category": "animals-pets", "description": "Gathers a cat up against the sternum",
+    "promptHint": "the subject gathers the counterpart up against the chest, one forearm braced under its hindquarters and the other hand flat along its back, and lowers the chin toward its head", "term": "holds the counterpart against the chest",
+    "counterpart": "a cat", "requires": ["cat"] },
+  { "id": "lift-cat-up", "label": "Lift cat up", "category": "animals-pets", "description": "Chest and hindquarters supported, lifted to eye level",
+    "promptHint": "the subject slides one hand under the counterpart's chest just behind the front legs and the other under its hindquarters, lifts it up to eye level as the arms extend, holds it there a beat before drawing it back in against the chest", "term": "lifts the counterpart up to eye level",
+    "counterpart": "a cat", "requires": ["cat"] },
+  { "id": "lift-puppy-to-face", "label": "Lift puppy to face", "category": "animals-pets", "description": "Raises a puppy up nose to nose",
+    "promptHint": "the subject raises the counterpart in both hands from lap height up to eye level, lifts the chin and leans in until the two are nose to nose, then lowers the counterpart back down against the subject's chest", "term": "holds the counterpart up to the face",
+    "counterpart": "a puppy", "requires": ["puppy"] },
+  { "id": "let-bird-perch", "label": "Let bird perch", "category": "animals-pets", "description": "Index finger held out level and steady",
+    "promptHint": "the subject holds one index finger out level in front of the chest and locks the elbow against the ribs to keep the hand from shaking, lifting the whole arm upward as the counterpart steps onto the finger", "term": "holds out a finger for the counterpart",
+    "counterpart": "a bird", "requires": ["bird"] },
+  { "id": "feed-the-ducks", "label": "Feed ducks", "category": "animals-pets", "description": "Tosses small pieces of food toward the ducks.",
+    "promptHint": "the subject takes small pieces of food from a bag and tosses them underhand toward the counterpart", "term": "tosses small pieces of food toward the counterpart",
+    "counterpart": "the ducks", "requires": ["ducks", "food", "bag"], "aliases": ["Feed the Ducks"] },
+  { "id": "stroke-horse-neck", "label": "Stroke horse neck", "category": "animals-pets", "description": "Long flat-palm sweeps down the neck",
+    "promptHint": "the subject lays a flat palm high on the counterpart's neck and sweeps it down the length of the crest in long full strokes, the other hand resting at the counterpart's shoulder", "term": "strokes the counterpart's neck",
+    "counterpart": "a horse", "requires": ["horse"] },
+  { "id": "brush-the-horse", "label": "Brush the horse", "category": "animals-pets", "description": "Long brush strokes along the lie of the coat",
+    "promptHint": "the subject presses a brush to the counterpart's flank and pulls it in long strokes along the lie of the coat, the free hand steadying the counterpart ahead of each pass, the shoulder swinging with the motion", "term": "brushes the counterpart's coat",
+    "counterpart": "a horse", "requires": ["horse"] },
+  { "id": "pat-horse-flank", "label": "Pat horse flank", "category": "animals-pets", "description": "Two firm open-palm pats, then rests the hand",
+    "promptHint": "the subject brings a flat hand in to pat the counterpart's flank twice with a firm open palm, then leaves the hand resting there and leans a little weight onto it", "term": "pats the counterpart on the flank",
+    "counterpart": "a horse", "requires": ["horse"] },
+  { "id": "mount-the-horse", "label": "Mount the horse", "category": "animals-pets", "description": "Foot in the stirrup, swings the leg over",
+    "promptHint": "the subject sets one foot into the stirrup, grips the saddle with both hands, springs off the ground and swings the trailing leg over, then settles down and finds the other stirrup", "term": "mounts a horse",
+    "deprecated": true, "replacementId": "mount-horse", "aliases": ["mount horse"] },
+  { "id": "back-away-slowly", "label": "Back away slowly from animal", "category": "animals-pets", "description": "Takes small cautious backward steps while facing the animal.",
+    "promptHint": "the subject faces the counterpart and takes small cautious backward steps, keeping the upper body steady and the gaze forward", "term": "takes cautious backward steps away from the counterpart",
+    "counterpart": "an animal", "requires": ["animal"], "fixedPace": true, "startPose": "standing", "endPose": "standing", "aliases": ["Back Away Slowly", "retreat"] },
+  { "id": "let-it-approach", "label": "Let it approach", "category": "animals-pets", "description": "Goes completely still and waits it out",
+    "promptHint": "the subject stops mid-step and goes completely still, arms hanging loose at the sides, the breathing shallow so the chest barely moves, only the eyes tracking the counterpart", "term": "freezes as the counterpart comes near",
+    "counterpart": "the animal", "requires": ["animal"] },
+  { "id": "crouch-to-photograph", "label": "Crouch to photograph", "category": "animals-pets", "description": "Drops low and frames the animal with a phone",
+    "promptHint": "the subject drops into a low crouch, braces the elbows on the knees and lifts a phone in both hands up in front of the face, holding dead still before tapping the screen with a thumb", "term": "crouches to photograph an animal" },
+  { "id": "tug-the-toy", "label": "Tug toy with dog", "category": "animals-pets", "description": "Pulls one end of a rope toy while the dog holds the other.",
+    "promptHint": "the subject holds one end of a rope toy while the counterpart holds the other, leans back with a gentle pull and then steps forward to loosen the tension", "term": "tugs a rope toy held by the counterpart",
+    "counterpart": "a dog", "requires": ["dog", "rope toy"], "aliases": ["Tug the Toy"] },
+  { "id": "wipe-muddy-paws", "label": "Wipe muddy paws", "category": "animals-pets", "description": "Kneels and towels one paw at a time",
+    "promptHint": "the subject kneels on one knee, lifts the counterpart's paw into a cupped hand, wraps a towel around it and rubs it clean, sets it back down and reaches for the next one", "term": "wipes the counterpart's muddy paws",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "brace-for-jump", "label": "Brace for jump", "category": "animals-pets", "description": "Plants the back foot to absorb a dog jumping up",
+    "promptHint": "the subject plants the back foot and drops the pelvis to take the counterpart's weight against the chest, both hands rising to catch its shoulders, the torso rocking back then steadying", "term": "braces as the counterpart jumps up",
+    "counterpart": "a dog", "requires": ["dog"] },
+  { "id": "dog-subject-sit", "label": "Dog sits", "category": "animals-pets", "description": "Dog sits.",
+    "term": "sits down on the hindquarters", "promptHint": "the subject is a dog that lowers its hindquarters to the ground while keeping the front legs upright",
+    "requires": ["dog as target subject"], "aliases": ["animal subject"] },
+  { "id": "dog-subject-lie-down", "label": "Dog lies down", "category": "animals-pets", "description": "Dog lies down.",
+    "term": "lies down with all four limbs resting", "promptHint": "the subject is a dog that lowers the chest and hindquarters to rest on the ground",
+    "requires": ["dog as target subject"], "aliases": ["animal subject"] },
+  { "id": "dog-subject-wag-tail", "label": "Dog wags tail", "category": "animals-pets", "description": "Dog wags tail.",
+    "term": "wags the tail", "promptHint": "the subject is a dog that wags its tail from side to side while keeping the body in place",
+    "requires": ["dog as target subject"], "aliases": ["animal subject"] },
+  { "id": "dog-subject-shake", "label": "Dog shakes body", "category": "animals-pets", "description": "Dog shakes body.",
+    "term": "shakes the body from head to tail", "promptHint": "the subject is a dog that shakes its body from head through torso to tail and then becomes still",
+    "requires": ["dog as target subject"], "aliases": ["animal subject"] },
+  { "id": "cat-subject-stretch", "label": "Cat stretches", "category": "animals-pets", "description": "Cat stretches.",
+    "term": "stretches the front legs and back", "promptHint": "the subject is a cat that extends both front legs, lowers the chest and lengthens the back before returning upright",
+    "requires": ["cat as target subject"], "aliases": ["animal subject"] },
+  { "id": "horse-subject-walk", "label": "Horse walks", "category": "animals-pets", "description": "Horse walks.",
+    "term": "walks with a steady four-beat gait", "promptHint": "the subject is a horse that walks steadily forward in a four-beat gait",
+    "requires": ["horse as target subject"], "aliases": ["animal subject"] },
+  { "id": "horse-subject-trot", "label": "Horse trots", "category": "animals-pets", "description": "Horse trots.",
+    "term": "trots with alternating diagonal leg pairs", "promptHint": "the subject is a horse that trots forward using alternating diagonal pairs of legs",
+    "requires": ["horse as target subject"], "aliases": ["animal subject"] },
+  { "id": "horse-subject-canter", "label": "Horse canters", "category": "animals-pets", "description": "Horse canters.",
+    "term": "canters in a rhythmic three-beat gait", "promptHint": "the subject is a horse that canters forward in a rhythmic three-beat gait",
+    "requires": ["horse as target subject"], "aliases": ["animal subject"] },
+  { "id": "bird-subject-hop", "label": "Bird hops", "category": "animals-pets", "description": "Bird hops.",
+    "term": "hops forward and settles", "promptHint": "the subject is a bird that makes a small hop forward and settles on both feet",
+    "requires": ["bird as target subject"], "aliases": ["animal subject"] },
+  { "id": "bird-subject-takeoff", "label": "Bird takes flight", "category": "animals-pets", "description": "Bird takes flight.",
+    "term": "pushes off, beating wings to take flight", "promptHint": "the subject is a bird that pushes off its perch and beats its wings to take flight",
+    "requires": ["bird as target subject"], "aliases": ["animal subject"] },
 ]