@nodaro/prompts 1.19.0 → 1.20.0

package/src/character-motion.ts

@@ -0,0 +1,286 @@
+/**
+ * Canonical catalog of CHARACTER MOTION choices — what the subject DOES across
+ * a video clip: walks in, turns to camera, breaks into a smile, ducks, draws and
+ * fires, runway-walks, dances. Temporal by definition.
+ *
+ * Distinct from:
+ *  - Pose            — a static SNAPSHOT of body position (serves still images too).
+ *  - Character FX    — supernatural change to the subject's body (werewolf, fire breath).
+ *  - Action FX       — a scene event (explosion, lightning); motion is the BODY acting.
+ *  - Camera Motion   — the camera moves, never the subject.
+ *
+ * Shared between the picker UI, the standalone Character Motion parameter node,
+ * and the prompt-hint injection on both the frontend DAG executor and the
+ * backend orchestrator. Video-only: never injected into still-image consumers.
+ *
+ * Every non-empty `promptHint` references "the subject" at least once — the
+ * composer does a global regex replace of "the subject" with the wired target's
+ * display name. Two-person moves ALSO contain the literal words "the partner",
+ * replaced with the wired partner's name, or "another person" when unwired.
+ *
+ * Multi-pick is an ORDERED SEQUENCE: value field accepts `string | string[]`
+ * (cap 3), joined with ", then " in BOTH hint modes (a movement happens after
+ * the previous one; Character FX joins with ", and " because effects coincide).
+ *
+ * `adultOnly` marks the W1-a minor-age floor. The composer drops flagged ids
+ * when its caller reports a minor subject (`floor.subjectMinor`); the AI Fill
+ * strip drops them from analyzer output. Hand-curated; the `adult-only-ratchet`
+ * test only ratchets. Never set on neutral movement or the `auto` / `none` heads.
+ */
+
+import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
+export type { CharacterMotion, CharacterMotionCategory } from "./character-motion/types.js"
+import type { CharacterMotion, CharacterMotionCategory } from "./character-motion/types.js"
+import { ENTRANCES_EXITS_MOTIONS } from "./character-motion/entrances-exits.js"
+import { TURNS_LOOKS_MOTIONS } from "./character-motion/turns-looks.js"
+import { HEAD_GESTURES_MOTIONS } from "./character-motion/head-gestures.js"
+import { WALKS_RUNS_MOTIONS } from "./character-motion/walks-runs.js"
+import { RUNWAY_MOTIONS } from "./character-motion/runway.js"
+import { DANCE_MOTIONS } from "./character-motion/dance.js"
+import { FACE_EXPRESSION_MOTIONS } from "./character-motion/face-expression.js"
+import { GESTURES_MOTIONS } from "./character-motion/gestures.js"
+import { CAMERA_INTERACTION_MOTIONS } from "./character-motion/camera-interaction.js"
+import { COMBAT_WEAPONS_MOTIONS } from "./character-motion/combat-weapons.js"
+import { ATHLETIC_STUNTS_MOTIONS } from "./character-motion/athletic-stunts.js"
+import { EVASIVE_FALLS_MOTIONS } from "./character-motion/evasive-falls.js"
+import { POSTURE_SHIFTS_MOTIONS } from "./character-motion/posture-shifts.js"
+import { EVERYDAY_ACTIONS_MOTIONS } from "./character-motion/everyday-actions.js"
+import { VEHICLES_MOUNTS_MOTIONS } from "./character-motion/vehicles-mounts.js"
+import { ANIMALS_PETS_MOTIONS } from "./character-motion/animals-pets.js"
+import { TWO_PERSON_MOTIONS } from "./character-motion/two-person.js"
+import { IDLE_AMBIENT_MOTIONS } from "./character-motion/idle-ambient.js"
+import { STAGE_PERFORMANCE_MOTIONS } from "./character-motion/stage-performance.js"
+import { UNNATURAL_HORROR_MOTIONS } from "./character-motion/unnatural-horror.js"
+
+export const CHARACTER_MOTION_CATEGORY_ORDER: ReadonlyArray<CharacterMotionCategory> = [
+  "entrances-exits",
+  "turns-looks",
+  "head-gestures",
+  "walks-runs",
+  "runway",
+  "dance",
+  "face-expression",
+  "gestures",
+  "camera-interaction",
+  "combat-weapons",
+  "athletic-stunts",
+  "evasive-falls",
+  "posture-shifts",
+  "everyday-actions",
+  "vehicles-mounts",
+  "animals-pets",
+  "two-person",
+  "idle-ambient",
+  "stage-performance",
+  "unnatural-horror",
+] as const
+
+export const CHARACTER_MOTION_CATEGORY_LABELS: Readonly<Record<CharacterMotionCategory, string>> = {
+  "entrances-exits": "Entrances & Exits",
+  "turns-looks": "Turns & Looks",
+  "head-gestures": "Head Gestures",
+  "walks-runs": "Walks & Runs",
+  "runway": "Runway & Model",
+  "dance": "Dance",
+  "face-expression": "Face & Expression",
+  "gestures": "Gestures",
+  "camera-interaction": "Camera Interaction",
+  "combat-weapons": "Combat & Weapons",
+  "athletic-stunts": "Athletic & Stunts",
+  "evasive-falls": "Evasive & Falls",
+  "posture-shifts": "Posture Shifts",
+  "everyday-actions": "Everyday Actions",
+  "vehicles-mounts": "Vehicles & Mounts",
+  "animals-pets": "Animals & Pets",
+  "two-person": "Two-Person",
+  "idle-ambient": "Idle & Ambient",
+  "stage-performance": "Stage & Performance",
+  "unnatural-horror": "Unnatural & Horror",
+} as const
+
+/**
+ * The catalog: two no-op heads + every category array, in category order.
+ * 1003 injecting entries across 20 categories.
+ */
+export const CHARACTER_MOTIONS: ReadonlyArray<CharacterMotion> = [
+  // Defaults — both inject nothing (empty promptHint ⇒ empty term).
+  { id: "auto", label: "Auto", category: "entrances-exits", description: "Let the model choose the movement", promptHint: "" },
+  { id: "none", label: "None", category: "entrances-exits", description: "No scripted character movement", promptHint: "" },
+  ...ENTRANCES_EXITS_MOTIONS,
+  ...TURNS_LOOKS_MOTIONS,
+  ...HEAD_GESTURES_MOTIONS,
+  ...WALKS_RUNS_MOTIONS,
+  ...RUNWAY_MOTIONS,
+  ...DANCE_MOTIONS,
+  ...FACE_EXPRESSION_MOTIONS,
+  ...GESTURES_MOTIONS,
+  ...CAMERA_INTERACTION_MOTIONS,
+  ...COMBAT_WEAPONS_MOTIONS,
+  ...ATHLETIC_STUNTS_MOTIONS,
+  ...EVASIVE_FALLS_MOTIONS,
+  ...POSTURE_SHIFTS_MOTIONS,
+  ...EVERYDAY_ACTIONS_MOTIONS,
+  ...VEHICLES_MOUNTS_MOTIONS,
+  ...ANIMALS_PETS_MOTIONS,
+  ...TWO_PERSON_MOTIONS,
+  ...IDLE_AMBIENT_MOTIONS,
+  ...STAGE_PERFORMANCE_MOTIONS,
+  ...UNNATURAL_HORROR_MOTIONS,
+]
+
+const characterMotionById = new Map<string, CharacterMotion>(
+  CHARACTER_MOTIONS.map((m) => [m.id, m]),
+)
+
+export function getCharacterMotion(id: string | undefined | null): CharacterMotion | undefined {
+  if (!id) return undefined
+  return overlayEntry("character-motion", id, characterMotionById.get(id))
+}
+
+export function getCharacterMotionLabel(id: string | undefined | null, fallback?: string): string {
+  const m = getCharacterMotion(id)
+  if (m) return m.label
+  if (fallback !== undefined) return fallback
+  return (id ?? "").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+export function getCharacterMotionPromptHint(id: string | undefined | null): string {
+  return getCharacterMotion(id)?.promptHint ?? ""
+}
+
+/** Compact counterpart of `getCharacterMotionPromptHint` — same lookup, same
+ *  empty-string-on-miss, and the no-op `auto` / `none` heads inject nothing. */
+export function getCharacterMotionTerm(id: string | undefined | null): string {
+  return resolveTerm(getCharacterMotion(id))
+}
+
+export const CHARACTER_MOTION_IDS: ReadonlyArray<string> = CHARACTER_MOTIONS.map((m) => m.id)
+
+/** Cap on ordered picks. Shared by the composer (`.slice(0, N)`), the picker
+ *  (`maxSelected`) and the config panel — the three must agree. */
+export const CHARACTER_MOTION_MAX_PICKS = 3
+
+// ---------------------------------------------------------------------------
+// Timing scales — Position + Pace. Own wording; NOT the character-fx or the
+// transition rows (an effect manifests, a transition occurs, a MOVEMENT is
+// performed). `POSITION_CLAUSES` / `PACE_CLAUSES` are DERIVED from these arrays
+// so the clause the composer injects and the hint the catalog advertises are
+// the same string by construction.
+// ---------------------------------------------------------------------------
+
+export interface CharacterMotionTimingOption {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  readonly promptHint: string
+  readonly term?: string
+}
+
+export const CHARACTER_MOTION_POSITIONS = [
+  { id: "auto",   label: "Auto",   description: "Let the model place the movement",          promptHint: "", term: "" },
+  { id: "start",  label: "Start",  description: "Begins at the opening of the clip",         promptHint: "the movement begins at the opening of the clip", term: "starting as the clip opens" },
+  { id: "middle", label: "Middle", description: "Begins midway through the clip",            promptHint: "the movement begins midway through the clip", term: "starting midway through the clip" },
+  { id: "end",    label: "End",    description: "Happens in the closing moments of the clip", promptHint: "the movement happens in the closing moments of the clip", term: "in the closing moments of the clip" },
+  { id: "full",   label: "Full",   description: "Plays out across the entire clip",          promptHint: "the movement plays out across the entire clip", term: "playing out across the whole clip" },
+] as const satisfies ReadonlyArray<CharacterMotionTimingOption>
+
+export const CHARACTER_MOTION_PACES = [
+  { id: "auto",        label: "Auto",        description: "Let the model set the tempo",                          promptHint: "", term: "" },
+  { id: "slow-motion", label: "Slow Motion", description: "The action itself is rendered in slow motion",         promptHint: "the action is rendered in slow motion, every phase of the movement stretched and drawn out", term: "in slow motion" },
+  { id: "slow",        label: "Slow",        description: "Performed slowly and deliberately",                    promptHint: "performed slowly and deliberately, each phase of the movement given its full time", term: "slow and deliberate" },
+  { id: "natural",     label: "Natural",     description: "Performed at an everyday tempo",                       promptHint: "performed at a natural everyday tempo, neither rushed nor drawn out", term: "at a natural everyday tempo" },
+  { id: "fast",        label: "Fast",        description: "Performed quickly, brisk and urgent",                  promptHint: "performed quickly, with brisk urgent tempo and sharp transitions between phases", term: "fast and brisk" },
+  { id: "explosive",   label: "Explosive",   description: "A sudden burst from stillness into full-speed motion", promptHint: "performed with an explosive burst of energy, snapping from stillness into full-speed motion", term: "with an explosive burst" },
+] as const satisfies ReadonlyArray<CharacterMotionTimingOption>
+
+export type CharacterMotionPosition = (typeof CHARACTER_MOTION_POSITIONS)[number]["id"]
+export type CharacterMotionPace     = (typeof CHARACTER_MOTION_PACES)[number]["id"]
+
+export interface CharacterMotionTiming {
+  position?: CharacterMotionPosition
+  pace?:     CharacterMotionPace
+}
+
+/** Private twin of the helper in character-fx.ts / transitions.ts — the
+ *  catalogs must stay independent. Total over the array by construction. */
+function clausesOf<T extends CharacterMotionTimingOption>(
+  options: ReadonlyArray<T>,
+): Record<Exclude<T["id"], "auto">, string> {
+  return Object.fromEntries(
+    options.filter((o) => o.id !== "auto").map((o) => [o.id, o.promptHint]),
+  ) as Record<Exclude<T["id"], "auto">, string>
+}
+
+const POSITION_CLAUSES = clausesOf(CHARACTER_MOTION_POSITIONS)
+const PACE_CLAUSES     = clausesOf(CHARACTER_MOTION_PACES)
+
+/** Widening guard — `as const` on the two arrays is load-bearing (see character-fx.ts). */
+type NarrowIds<T> = string extends T ? never : true
+const _timingIdsStayNarrow: [NarrowIds<CharacterMotionPosition>, NarrowIds<CharacterMotionPace>] = [true, true]
+void _timingIdsStayNarrow
+
+// ---------------------------------------------------------------------------
+// Graph-aware composer — target + partner handles, ordered multi-pick, timing
+// ---------------------------------------------------------------------------
+
+const PARTNER_FALLBACK = "another person"
+
+/** What the caller knows about the wired target. `subjectMinor: true` drops
+ *  every `adultOnly` pick after the cap; otherwise the output is unchanged. */
+export interface CharacterMotionFloor {
+  readonly subjectMinor?: boolean
+}
+
+/**
+ * Compose a character-motion prompt fragment from an ORDERED list of 1–3 move
+ * ids, the display names wired to the `target` and `partner` handles, and the
+ * optional Position / Pace timing.
+ *
+ * Full mode: each hint has "the subject" rewritten to the target name(s) (only
+ * when a target is wired) and "the partner" rewritten to the partner name (or
+ * "another person" — ALWAYS, so the literal words "the partner" never ship);
+ * both BEFORE the ", then " join. Compact mode: terms joined with ", then ",
+ * prefixed `"{target}: "` when a target is wired. A term never contains "the
+ * subject" (the prefix names the target) but a two-person term always contains
+ * "the partner", which is substituted exactly as in full mode.
+ * Timing clauses follow in the fixed order position, pace, in both modes.
+ * `floor.subjectMinor` drops adult-only picks after the cap; none left ⇒ "".
+ */
+export function composeCharacterMotionHintFromConnections(
+  motionId: string | ReadonlyArray<string> | undefined | null,
+  targetHints: ReadonlyArray<string>,
+  partnerHints: ReadonlyArray<string>,
+  timing?: CharacterMotionTiming,
+  mode: PickerHintMode = "full",
+  floor?: CharacterMotionFloor,
+): string {
+  const picked = Array.isArray(motionId)
+    ? Array.from(new Set(motionId as ReadonlyArray<string>)).slice(0, CHARACTER_MOTION_MAX_PICKS)
+    : motionId ? [motionId as string] : []
+  // Cap the user's picks FIRST, then floor: a dropped pick never lets a later one backfill.
+  const ids = floor?.subjectMinor === true
+    ? picked.filter((id) => getCharacterMotion(id)?.adultOnly !== true)
+    : picked
+  const resolveBase = mode === "compact" ? getCharacterMotionTerm : getCharacterMotionPromptHint
+  const entries = ids.map((id) => ({ id, base: resolveBase(id) })).filter((e) => e.base.length > 0)
+  if (entries.length === 0) return ""
+
+  const targetClause  = targetHints.filter((h) => h && h.length > 0).join(" and ")
+  const partnerClause = partnerHints.filter((h) => h && h.length > 0).join(" and ")
+  const partnerName   = partnerClause || PARTNER_FALLBACK
+
+  const substituted = entries.map(({ base }) => {
+    const named = mode !== "compact" && targetClause
+      ? base.replace(/\bthe subject\b/g, targetClause)
+      : base
+    return named.replace(/\bthe partner\b/g, partnerName)
+  })
+
+  const joined = substituted.join(", then ")
+  const combinedBase = mode === "compact" && targetClause ? `${targetClause}: ${joined}` : joined
+  const parts: string[] = [combinedBase]
+  if (timing?.position && timing.position !== "auto") parts.push(POSITION_CLAUSES[timing.position])
+  if (timing?.pace     && timing.pace     !== "auto") parts.push(PACE_CLAUSES[timing.pace])
+  return parts.join(", ")
+}

package/src/index.ts

@@ -51,6 +51,7 @@ export * from "./camera-format.js"
 export * from "./camera-motions.js"
 export * from "./hint-join.js"
 export * from "./character-fx.js"
+export * from "./character-motion.js"
 export * from "./color-look.js"
 export * from "./composition-effects.js"
 export * from "./era.js"

package/src/parameter-prompt-hint.ts

@@ -38,6 +38,8 @@ import { composeCameraMotionHintFromConnections } from "./camera-motions.js"
 import { joinHintFragments } from "./hint-join.js"
 import { composeTransitionHintFromConnections, type TransitionDuration, type TransitionIntensity, type TransitionPosition, type TransitionTiming } from "./transitions.js"
 import { composeCharacterFxHintFromConnections, type CharacterFxDuration, type CharacterFxIntensity, type CharacterFxPosition, type CharacterFxTiming } from "./character-fx.js"
+import { composeCharacterMotionHintFromConnections, type CharacterMotionPace, type CharacterMotionPosition, type CharacterMotionTiming } from "./character-motion.js"
+import { containsMinorAgeHint, isMinorAge } from "./age-floor.js"
 import { buildMaterialHints } from "./materials.js"
 import { curatedAnimalPromptHint, curatedAnimalTerm, curatedVehicleText, curatedWeaponText, curatedFurnitureText } from "./shared-catalog-overlay.js"
 import { getPhotoGenrePromptHint, getPhotoGenreTerm } from "./photo-genre.js"
@@ -73,6 +75,33 @@ function extractCharacterRefName(node: HintNodeLike): string | undefined {
   return undefined
 }
 
+/** Character Motion's name read: the shared character / face / object / location
+ *  read, then a creature's `creatureName`. Local to Character Motion so the
+ *  Character FX prompt, which shares `extractCharacterRefName`, stays unchanged. */
+function extractCharacterMotionRefName(node: HintNodeLike): string | undefined {
+  const name = extractCharacterRefName(node)
+  if (name) return name
+  const creatureName = asStr(((node.data ?? {}) as Record<string, unknown>).creatureName).trim()
+  return creatureName.length > 0 ? creatureName : undefined
+}
+
+/** Free-text fields a character / face / object / location ref node describes its subject in.
+ *  A creature ref uses the same `description` / `canonicalDescription` names. */
+const REF_DESCRIPTION_FIELDS = ["description", "seedPrompt", "canonicalDescription"] as const
+
+/** True when a character / face / object / location ref node describes a minor:
+ *  its structured `person` age (the primary signal) or an age phrase in its
+ *  free-text description. Feeds the Character Motion floor (adult-only moves
+ *  dropped) — errs toward flooring, never toward letting an adult-only move through. */
+function extractCharacterRefMinor(node: HintNodeLike): boolean {
+  const d = (node.data ?? {}) as Record<string, unknown>
+  const person = d.person
+  if (person && typeof person === "object" && !Array.isArray(person) && isMinorAge(person as Parameters<typeof isMinorAge>[0])) {
+    return true
+  }
+  return REF_DESCRIPTION_FIELDS.some((field) => containsMinorAgeHint(asStr(d[field])))
+}
+
 /** Compose `[preText, mainHint, postText]` into a comma-joined string,
  *  honoring the user's free-text fragments around the structured hint.
  *  Helpers like `getStylePromptHint` that already include preText/postText
@@ -219,6 +248,42 @@ function resolveParameterHint(
     return withCustomText(data, composeCharacterFxHintFromConnections(effectId, targetNames, timing, mode))
   }
 
+  if (node.type === "character-motion") {
+    const raw = data.characterMotion
+    const motionId: string | string[] | undefined =
+      Array.isArray(raw)
+        ? raw.filter((s): s is string => typeof s === "string" && s.length > 0)
+        : (asStr(raw) || undefined)
+    const timing: CharacterMotionTiming = {
+      position: asStr(data.position) as CharacterMotionPosition | undefined,
+      pace:     asStr(data.pace)     as CharacterMotionPace     | undefined,
+    }
+    if (!ctx) {
+      return withCustomText(data, composeCharacterMotionHintFromConnections(motionId, [], [], timing, mode))
+    }
+    const targetNames: string[] = []
+    const partnerNames: string[] = []
+    // Minor-age floor: ANY ref wired to target or partner that describes a
+    // minor drops every adultOnly move from the composed sequence.
+    let subjectMinor = false
+    for (const edge of ctx.edges) {
+      if (edge.target !== node.id) continue
+      if (edge.targetHandle !== "target" && edge.targetHandle !== "partner") continue
+      const src = ctx.nodes.find((n) => n.id === edge.source)
+      if (!src) continue
+      // Before the name check: an unnamed ref that describes a minor still floors.
+      if (!subjectMinor && extractCharacterRefMinor(src)) subjectMinor = true
+      const name = extractCharacterMotionRefName(src)
+      if (!name) continue
+      if (edge.targetHandle === "target") targetNames.push(name)
+      else partnerNames.push(name)
+    }
+    return withCustomText(
+      data,
+      composeCharacterMotionHintFromConnections(motionId, targetNames, partnerNames, timing, mode, { subjectMinor }),
+    )
+  }
+
   const base = resolveBaseHint(node.type, data, mode)
   if (base) return base
   // Pack-extend fallback: a single-dim pack entry the per-catalog getter (which

package/src/picker-analyzer-registry.ts

@@ -29,6 +29,7 @@ import { ACTION_FX } from "./action-fx.js"
 import { LOOP_SUBJECTS } from "./loop-subject.js"
 import { TRANSITIONS } from "./transitions.js"
 import { CHARACTER_FX } from "./character-fx.js"
+import { CHARACTER_MOTIONS } from "./character-motion.js"
 import { POSES } from "./pose.js"
 import { MATERIALS } from "./materials.js"
 import { HELD_PROPS } from "./held-prop.js"
@@ -183,6 +184,7 @@ export const PICKER_ANALYZER_REGISTRY = {
   "loop-subject": { kind: "flat", toolName: "emit_loop_subject", field: "loopSubject", label: "Loop Subject", entries: LOOP_SUBJECTS as ReadonlyArray<AnalyzerEntry> },
   transition: { kind: "flat", toolName: "emit_transition", field: "transition", label: "Transition", entries: TRANSITIONS as ReadonlyArray<AnalyzerEntry> },
   "character-fx": { kind: "flat", toolName: "emit_character_fx", field: "characterFx", label: "Character FX", entries: CHARACTER_FX as ReadonlyArray<AnalyzerEntry> },
+  "character-motion": { kind: "flat", toolName: "emit_character_motion", field: "characterMotion", label: "Character Motion", entries: CHARACTER_MOTIONS as ReadonlyArray<AnalyzerEntry> },
   pose: { kind: "flat", toolName: "emit_pose", field: "pose", label: "Pose", entries: POSES as ReadonlyArray<AnalyzerEntry> },
   material: { kind: "flat", toolName: "emit_material", field: "material", label: "Material", entries: MATERIALS as ReadonlyArray<AnalyzerEntry> },
   "held-prop": { kind: "flat", toolName: "emit_held_prop", field: "heldProp", label: "Held Prop", entries: HELD_PROPS as ReadonlyArray<AnalyzerEntry> },
@@ -301,18 +303,20 @@ export type PickerType = keyof typeof PICKER_ANALYZER_REGISTRY
 export const PICKER_TYPES = Object.keys(PICKER_ANALYZER_REGISTRY) as PickerType[]
 
 /**
- * Family grouping for BATCHED analysis. A single call across all 38 catalogs
- * carries a ~211k-char legend (~53k tokens — measured 2026-08-09, the
+ * Family grouping for BATCHED analysis. A single call across the first 38
+ * catalogs carried a ~211k-char legend (~53k tokens — measured 2026-08-09, the
  * measure-first probe from the text-to-picker spec), which is slow, costly,
  * and dilutes per-section accuracy. The text-to-picker route fans out one
- * structured call per family (6-15k tokens each) and merges. Mirrors the
- * build-brief's §5 UI grouping so Cine can reuse the same partition.
+ * structured call per family (6-15k tokens each) and merges. The character
+ * family is the exception: Character Motion's 1005-id legend alone is ~82k
+ * chars (~46k input tokens measured 2026-09-15), making it the heaviest call.
+ * Mirrors the build-brief's §5 UI grouping so Cine can reuse the same partition.
  */
 export const PICKER_ANALYZER_FAMILIES: Readonly<Record<string, ReadonlyArray<PickerType>>> = {
   scene: ["setting", "atmosphere", "backdrop", "era", "temporal"],
   look: ["style", "color-look", "mood", "aesthetic", "photographer", "photo-genre", "render-quality", "composition-effects", "post-process-effects"],
   camera: ["framing", "camera-motion", "lens", "camera-format", "lighting", "exposure-settings"],
-  character: ["person", "styling", "pose", "character-fx"],
+  character: ["person", "styling", "pose", "character-fx", "character-motion"],
   elements: ["animal", "vehicle", "weapon", "furniture", "held-prop", "material", "action-fx", "loop-subject", "transition"],
   audio: ["music-genre", "music-mood", "instrumentation", "voice-character", "voice-delivery"],
 }

package/src/picker-catalogs.ts

@@ -67,6 +67,13 @@ import {
   CHARACTER_FX_DURATIONS,
   CHARACTER_FX_INTENSITIES,
 } from "./character-fx.js"
+import {
+  CHARACTER_MOTIONS,
+  CHARACTER_MOTION_CATEGORY_LABELS,
+  CHARACTER_MOTION_CATEGORY_ORDER,
+  CHARACTER_MOTION_POSITIONS,
+  CHARACTER_MOTION_PACES,
+} from "./character-motion.js"
 import { POSES, POSE_CATEGORY_LABELS, POSE_CATEGORY_ORDER } from "./pose.js"
 import { MATERIALS, MATERIAL_CATEGORY_LABELS, MATERIAL_CATEGORY_ORDER } from "./materials.js"
 import { ANIMALS, ANIMAL_SUBCATEGORY_LABELS, ANIMAL_SUBCATEGORY_ORDER, getAnimalPromptHint } from "@nodaro/shared"
@@ -588,6 +595,23 @@ const SINGLE_CATALOGS: readonly PickerCatalog[] = [
       ["intensity", CHARACTER_FX_INTENSITIES],
     ]),
   },
+  {
+    nodeType: "character-motion",
+    label: "Character Motion",
+    catalogId: "character-motion",
+    kind: "single",
+    valueField: "characterMotion",
+    defaultValue: "auto",
+    categoryOrder: CHARACTER_MOTION_CATEGORY_ORDER,
+    categoryLabels: CHARACTER_MOTION_CATEGORY_LABELS,
+    options: toOptions(CHARACTER_MOTIONS, "category"),
+    // Position + Pace, this node's own wording (a movement begins / plays out;
+    // an effect manifests; a transition occurs) — never the sibling rows.
+    dimensions: perFieldDims([
+      ["position", CHARACTER_MOTION_POSITIONS],
+      ["pace", CHARACTER_MOTION_PACES],
+    ]),
+  },
 
   // -------- "Subject / Object" family --------
   {

package/src/picker-wiring.ts

@@ -51,6 +51,7 @@ import { ACTION_FX, ACTION_FX_CATEGORY_LABELS, ACTION_FX_CATEGORY_ORDER } from "
 import { LOOP_SUBJECTS, LOOP_SUBJECT_CATEGORY_LABELS, LOOP_SUBJECT_CATEGORY_ORDER } from "./loop-subject.js"
 import { TRANSITIONS, TRANSITION_CATEGORY_LABELS, TRANSITION_CATEGORY_ORDER } from "./transitions.js"
 import { CHARACTER_FX, CHARACTER_FX_CATEGORY_LABELS, CHARACTER_FX_CATEGORY_ORDER } from "./character-fx.js"
+import { CHARACTER_MOTIONS, CHARACTER_MOTION_CATEGORY_LABELS, CHARACTER_MOTION_CATEGORY_ORDER } from "./character-motion.js"
 import { FRAMINGS, FRAMING_CATEGORY_ORDER, FRAMING_FIELD_BY_CATEGORY } from "./framing.js"
 import { LIGHTINGS, LIGHTING_CATEGORY_ORDER, LIGHTING_FIELD_BY_CATEGORY } from "./lighting.js"
 import { STYLINGS, STYLING_DIMENSION_ORDER, STYLING_FIELD_BY_DIMENSION } from "./styling.js"
@@ -159,6 +160,7 @@ export const SINGLE_PICKER_WIRING: ReadonlyArray<SingleDimPickerWiring> = [
   { kind: "single", nodeType: "camera-format", label: "Camera / Film", valueField: "cameraFormat", defaultValue: "35mm-film", catalogId: "camera-format", entries: mapCat(CAMERA_FORMATS) },
   { kind: "single", nodeType: "transition", label: "Transition", valueField: "transition", defaultValue: "auto", catalogId: "transitions", entries: mapCat(TRANSITIONS, "category"), groupOrder: TRANSITION_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: TRANSITION_CATEGORY_LABELS },
   { kind: "single", nodeType: "character-fx", label: "Character FX", valueField: "characterFx", defaultValue: "auto", catalogId: "character-fx", entries: mapCat(CHARACTER_FX, "category"), groupOrder: CHARACTER_FX_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: CHARACTER_FX_CATEGORY_LABELS },
+  { kind: "single", nodeType: "character-motion", label: "Character Motion", valueField: "characterMotion", defaultValue: "auto", catalogId: "character-motion", entries: mapCat(CHARACTER_MOTIONS, "category"), groupOrder: CHARACTER_MOTION_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: CHARACTER_MOTION_CATEGORY_LABELS },
 
   // -------- "Subject / Object" family --------
   { kind: "single", nodeType: "pose", label: "Pose", valueField: "pose", defaultValue: "standing-upright", catalogId: "pose", entries: mapCat(POSES, "category"), groupOrder: POSE_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: POSE_CATEGORY_LABELS },

package/src/prompt-wizard-categories.ts

@@ -196,7 +196,6 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "gpt-image-2-5-sunburst-i2i": "Precision GPT Image 2.5 edits — up to 16 sources, tightest control on demanding retouches; slower",
     "ideogram-edit": "Instruction-based editing with text preservation",
     "ideogram-remix": "Style remixing while preserving structure",
-    "ideogram-reframe": "Aspect ratio changes with AI fill",
     "qwen-i2i": "Versatile transformation",
     "qwen-edit": "Instruction-based editing",
     "seedream-edit": "Artistic style editing",
@@ -221,7 +220,6 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "gpt-image-2-5-sunburst-i2i": "Precision GPT Image 2.5 edits — up to 16 sources, tightest control on demanding retouches; slower",
     "ideogram-edit": "Instruction-based editing with text preservation",
     "ideogram-remix": "Style remixing while preserving structure",
-    "ideogram-reframe": "Aspect ratio changes with AI fill",
     "qwen-i2i": "Versatile transformation",
     "qwen-edit": "Instruction-based editing",
     "seedream-edit": "Artistic style editing",

package/src/provider-prompt-doctrine.ts

@@ -227,7 +227,7 @@ Example: "Medium shot, a tired corporate worker, rubbing his temples in exhausti
 
 **Frames & references**
 - Start + end frame: wire both (imageUrls [start, end]) and describe the camera path between them — "a smooth 180-degree arc shot, starting front-facing and circling to end on the POV from behind her".
-- Reference images (ingredients): attach character/object/scene refs and name them in the prompt ("using the provided images for the detective and the office, …"). Reference runs DO generate audio.
+- Reference images (ingredients) — **Fast (veo3.1) and Lite (veo3_lite) only**; the Quality SKU (veo3) has no reference-to-video mode at the provider, so wire it with frames alone. Where they are available: attach character/object/scene refs and name them in the prompt ("using the provided images for the detective and the office, …"). Reference runs DO generate audio.
 
 **Constraints**
 - Negative prompting works by positive description: write "a desolate landscape with no buildings or roads", not "no buildings".