@nodaro/prompts 1.18.0 → 1.20.0

package/src/parameter-prompt-hint.ts

@@ -35,8 +35,11 @@ import { buildPoseHints } from "./pose.js"
 import { buildStylingHints } from "./styling.js"
 import { buildTemporalHints } from "./temporal.js"
 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"
@@ -72,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
@@ -84,7 +114,7 @@ function withCustomText(data: Record<string, unknown>, mainHint: string): string
   if (mainHint) fragments.push(mainHint)
   const post = typeof data.postText === "string" ? data.postText.trim() : ""
   if (post) fragments.push(post)
-  return fragments.join(", ")
+  return joinHintFragments(fragments)
 }
 
 /**
@@ -218,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",
@@ -333,11 +331,17 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "minimax": "General music generation, multiple genres",
   },
   "suno-generate": {
-    "V4": "Standard Suno generation",
-    "V4_5": "Improved quality and coherence",
+    // Current generation first (V6 = default), then the earlier ones — all
+    // offered in the picker; mirrors SUNO_MODELS order in @nodaro/shared.
+    "V6": "Flagship — greater musical expression, more natural vocals, richer details",
+    "V6_WILD": "Bolder, more distinctive, less predictable results for exploration",
+    "V6_MINI": "Lightweight and fast — quality/speed balance",
+    "V5_5": "Custom-model tuning with strong vocal quality",
+    "V5": "Superior musical expression, faster generation",
     "V4_5PLUS": "Enhanced V4.5 with better production",
     "V4_5ALL": "Full-featured V4.5",
-    "V5": "Latest Suno with highest quality",
+    "V4_5": "Improved quality and coherence",
+    "V4": "Standard Suno generation",
   },
   "text-to-audio": {
     "elevenlabs-sfx": "High quality sound effects and ambient audio",

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".

package/src/sound-aggregator.ts

@@ -96,7 +96,7 @@ export function composeSoundHintFromConnections(
   // Music consumers (suno-generate, generate-music) accept BOTH music nodes
   // AND voice nodes — voice description (gender, age, accent, language,
   // timbre, delivery archetype) is valid input for music with vocals. Suno
-  // V5 in particular benefits from rich voice description; the typed
+  // V6 in particular benefits from rich voice description; the typed
   // `vocalGender` field on Suno is also extracted below from voice-character.
   //
   // Voice Design rejects music nodes (different domain). Text-to-Audio