@nodaro/prompts 1.20.0 → 1.21.0

package/src/frame-delivery.ts

@@ -0,0 +1,106 @@
+/**
+ * HOW A START/END FRAME TRAVELS — one plan, read by both ends.
+ *
+ * A frame can reach a model two ways: as a real frame, or as a reference image
+ * bound in prose as the opening (or closing) frame. Which one is right is
+ * measured per model — the Seedance 2.0 family crop-zooms a frame 2% and drifts
+ * 11-26% darker within six frames, but holds its look from frame 0 when the same
+ * image rides as a reference; every other model measured reproduces the opening
+ * frame better as a frame (see `resolveFrameDelivery` in @nodaro/shared).
+ *
+ * The composition — where the frames sit in the reference list, which sentence
+ * binds them, when the switch is refused — lives HERE rather than at the
+ * dispatch site, because two places need the same answer:
+ *
+ *   - `backend/src/lib/video-frame-dispatch.ts` builds the actual request,
+ *   - the editor's config panel tells the user which mode their node will run in.
+ *
+ * When those two disagree the panel lies, which is worse than having no panel
+ * text at all. One function, two callers, no drift.
+ */
+import { VIDEO_REF_LIMITS_BY_PROVIDER, resolveFrameDelivery, type FrameDelivery } from "@nodaro/shared"
+import { REF_BINDING } from "./ref-binding.js"
+import { promptBindsFirstFrame } from "./seedance-2-inputs.js"
+
+export interface FrameDeliveryPlanArgs {
+  readonly provider: string | undefined
+  /** The node's / caller's choice. `auto` (or absent) resolves per model. */
+  readonly requested?: FrameDelivery
+  /** Whether the model accepts reference images at all. */
+  readonly supportsReferenceImages: boolean
+  readonly startFrameUrl?: string
+  readonly endFrameUrl?: string
+  /** The user's OWN reference images, in their existing order. */
+  readonly userReferenceUrls?: readonly string[]
+  /** Consulted only to avoid a duplicate opening-frame sentence. */
+  readonly prompt?: string
+}
+
+export interface FrameDeliveryPlan {
+  /** What will actually happen — never `auto`. */
+  readonly delivery: Exclude<FrameDelivery, "auto">
+  /** The full reference list to send. Equals the user's own list under `frame`. */
+  readonly referenceImageUrls: readonly string[]
+  /** Sentence(s) to append to the prompt. Empty under `frame`. */
+  readonly promptSuffix: string
+  /** Set when reference delivery was WANTED but refused, so a caller can say why. */
+  readonly refusedReason?: "no-reference-support" | "image-cap"
+}
+
+/**
+ * Resolve delivery and compose the request shape that follows from it.
+ *
+ * Two refusals, both deliberate:
+ *   - a model with no reference-image support keeps frame mode (there is nowhere
+ *     for the frame to go);
+ *   - a switch that would push past the model's image cap keeps frame mode,
+ *     because the alternative is dropping one of the USER's reference images to
+ *     make room for ours.
+ *
+ * The frames are appended AFTER the user's own images so their `@image_N`
+ * ordinals never shift, and the opening sentence is skipped when the prompt
+ * already binds its own first frame — a second binding at another position
+ * dilutes the first back into coin-flip behaviour (field finding 2026-07-20).
+ */
+export function planFrameDelivery(args: FrameDeliveryPlanArgs): FrameDeliveryPlan {
+  const userRefs = (args.userReferenceUrls ?? []).filter(Boolean)
+  const requested = args.requested ?? "auto"
+  const delivery = resolveFrameDelivery({
+    provider: args.provider,
+    requested,
+    supportsReferenceImages: args.supportsReferenceImages,
+  })
+
+  const frames = [args.startFrameUrl, args.endFrameUrl].filter((u): u is string => Boolean(u))
+
+  if (delivery === "frame" || frames.length === 0) {
+    return {
+      delivery: "frame",
+      referenceImageUrls: userRefs,
+      promptSuffix: "",
+      ...(requested === "reference" && !args.supportsReferenceImages
+        ? { refusedReason: "no-reference-support" as const }
+        : {}),
+    }
+  }
+
+  const cap = VIDEO_REF_LIMITS_BY_PROVIDER[args.provider ?? ""]?.images
+  if (cap !== undefined && userRefs.length + frames.length > cap) {
+    return { delivery: "frame", referenceImageUrls: userRefs, promptSuffix: "", refusedReason: "image-cap" }
+  }
+
+  const referenceImageUrls = [...userRefs]
+  const sentences: string[] = []
+  if (args.startFrameUrl) {
+    referenceImageUrls.push(args.startFrameUrl)
+    if (!promptBindsFirstFrame(args.prompt)) {
+      sentences.push(REF_BINDING.frame(referenceImageUrls.length, "opening"))
+    }
+  }
+  if (args.endFrameUrl) {
+    referenceImageUrls.push(args.endFrameUrl)
+    sentences.push(REF_BINDING.frame(referenceImageUrls.length, "closing"))
+  }
+
+  return { delivery: "reference", referenceImageUrls, promptSuffix: sentences.join(" ") }
+}

package/src/index.ts

@@ -92,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

@@ -102,6 +102,28 @@ function extractCharacterRefMinor(node: HintNodeLike): boolean {
   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
@@ -261,23 +283,7 @@ function resolveParameterHint(
     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)
-    }
+    const { targetNames, partnerNames, subjectMinor } = getCharacterMotionBindings(node, ctx)
     return withCustomText(
       data,
       composeCharacterMotionHintFromConnections(motionId, targetNames, partnerNames, timing, mode, { subjectMinor }),

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.
  *
@@ -98,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
@@ -604,7 +608,10 @@ const SINGLE_CATALOGS: readonly PickerCatalog[] = [
     defaultValue: "auto",
     categoryOrder: CHARACTER_MOTION_CATEGORY_ORDER,
     categoryLabels: CHARACTER_MOTION_CATEGORY_LABELS,
-    options: toOptions(CHARACTER_MOTIONS, "category"),
+    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([
@@ -939,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. */