@nodaro/prompts 1.19.0 → 1.21.0

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"
@@ -91,3 +92,7 @@ export * from "./object-asset-presets.js"
 export * from "./factory-snippets/index.js"
 export * from "./picker-wiring.js"
 export * from "./surround-fill.js"
+
+// --- Start/end frame delivery: one plan for the dispatch and the editor ---
+export * from "./frame-delivery.js"
+export * from "./character-motion-diagnostics.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,55 @@ 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])))
+}
+
+/** The preview, diagnostics and execution use identical graph bindings. */
+export function getCharacterMotionBindings(node: HintNodeLike, ctx?: HintGraphContext) {
+  const targetNames: string[] = []
+  const partnerNames: string[] = []
+  const targetIds = new Set<string>()
+  const partnerIds = new Set<string>()
+  let subjectMinor = false
+  for (const edge of ctx?.edges ?? []) {
+    if (edge.target !== node.id || (edge.targetHandle !== "target" && edge.targetHandle !== "partner")) continue
+    const src = ctx?.nodes.find(n => n.id === edge.source)
+    if (!src) continue
+    if (edge.targetHandle === "target") targetIds.add(src.id)
+    else partnerIds.add(src.id)
+    if (extractCharacterRefMinor(src)) subjectMinor = true
+    const name = extractCharacterMotionRefName(src)
+    if (!name) continue
+    const names = edge.targetHandle === "target" ? targetNames : partnerNames
+    if (!names.includes(name)) names.push(name)
+  }
+  return { targetNames, partnerNames, subjectMinor, selfPairing: [...targetIds].some(id => partnerIds.has(id)) }
+}
+
 /** 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 +270,26 @@ 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, partnerNames, subjectMinor } = getCharacterMotionBindings(node, ctx)
+    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

@@ -1,3 +1,4 @@
+import type { CharacterMotionMetadata } from "./character-motion/types.js"
 /**
  * Public, discoverable registry of the parameter-picker catalogs.
  *
@@ -67,6 +68,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"
@@ -91,6 +99,9 @@ import { setComposedCatalogResolver } from "./catalog-overlay.js"
 import { deriveTerm, resolveTerm } from "./term.js"
 
 export interface PickerOption {
+  /** Character Motion only: authored prerequisites, state and search metadata. */
+  readonly motion?: CharacterMotionMetadata
+
   readonly id: string
   readonly label: string
   readonly description?: string
@@ -588,6 +599,26 @@ 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").map((option, index) => {
+      const { id: _id, label: _label, category: _category, description: _description, promptHint: _hint, term: _term, adultOnly: _adult, twoPerson: _duo, ...motion } = CHARACTER_MOTIONS[index]!
+      return { ...option, motion }
+    }),
+    // 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 --------
   {
@@ -915,8 +946,9 @@ function projectOption(o: PickerOption, detail: PickerCatalogDetail): ProjectedP
         promptHint: o.promptHint,
         term: o.term,
         icon: o.icon,
+        ...(o.motion ? { motion: o.motion } : {}),
       }
-    : { id: o.id, label: o.label, category: o.category, term: o.term, icon: o.icon }
+    : { id: o.id, label: o.label, category: o.category, term: o.term, icon: o.icon, ...(o.motion ? { motion: o.motion } : {}) }
 }
 
 /** Project a catalog to the wire shape: compact by default, optional category/field filter. */

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