@nodaro/prompts 1.9.0 → 1.10.0

package/dist/index.cjs

@@ -5892,24 +5892,35 @@ function getCharacterFxTerm(id) {
   return resolveTerm(getCharacterFx(id));
 }
 var CHARACTER_FX_IDS = CHARACTER_FX.map((c) => c.id);
-var POSITION_CLAUSES2 = {
-  start: "the effect occurs at the opening of the clip",
-  middle: "the effect occurs in the middle of the clip",
-  end: "the effect occurs at the end of the clip",
-  full: "the effect persists for the entire clip"
-};
-var DURATION_CLAUSES2 = {
-  instant: "manifesting instantaneously",
-  short: "manifesting over approximately 1 second",
-  medium: "manifesting over approximately 2 seconds",
-  long: "manifesting over approximately 3 seconds"
-};
-var INTENSITY_CLAUSES2 = {
-  subtle: "with subtle restrained energy and minimal flourish",
-  natural: "with natural unhurried timing",
-  dynamic: "with dynamic energy and assertive flourish",
-  crazy: "with extreme exaggerated energy, wild flourishes, and dramatic distortion"
-};
+var CHARACTER_FX_POSITIONS = [
+  { id: "auto", label: "Auto", description: "Let the model place the effect", promptHint: "", term: "" },
+  { id: "start", label: "Start", description: "Occurs at the opening of the clip", promptHint: "the effect occurs at the opening of the clip", term: "at the opening of the clip" },
+  { id: "middle", label: "Middle", description: "Occurs in the middle of the clip", promptHint: "the effect occurs in the middle of the clip", term: "mid-clip" },
+  { id: "end", label: "End", description: "Occurs at the end of the clip", promptHint: "the effect occurs at the end of the clip", term: "at the end of the clip" },
+  { id: "full", label: "Full", description: "Persists for the entire clip", promptHint: "the effect persists for the entire clip", term: "persisting for the whole clip" }
+];
+var CHARACTER_FX_DURATIONS = [
+  { id: "auto", label: "Auto", description: "Let the model time the effect", promptHint: "", term: "" },
+  { id: "instant", label: "Instant", description: "Manifests instantaneously", promptHint: "manifesting instantaneously", term: "manifesting instantly" },
+  { id: "short", label: "Short (~1s)", description: "Manifests over approximately 1 second", promptHint: "manifesting over approximately 1 second", term: "manifesting over about 1 second" },
+  { id: "medium", label: "Medium (~2s)", description: "Manifests over approximately 2 seconds", promptHint: "manifesting over approximately 2 seconds", term: "manifesting over about 2 seconds" },
+  { id: "long", label: "Long (~3s)", description: "Manifests over approximately 3 seconds", promptHint: "manifesting over approximately 3 seconds", term: "manifesting over about 3 seconds" }
+];
+var CHARACTER_FX_INTENSITIES = [
+  { id: "auto", label: "Auto", description: "Let the model judge the effect's energy", promptHint: "", term: "" },
+  { id: "subtle", label: "Subtle", description: "Restrained, minimal flourish", promptHint: "with subtle restrained energy and minimal flourish", term: "subtly" },
+  { id: "natural", label: "Natural", description: "Unhurried, unforced timing", promptHint: "with natural unhurried timing", term: "at a natural pace" },
+  { id: "dynamic", label: "Dynamic", description: "Assertive, energetic", promptHint: "with dynamic energy and assertive flourish", term: "energetically" },
+  { id: "crazy", label: "Crazy", description: "Extreme, wild, distorted", promptHint: "with extreme exaggerated energy, wild flourishes, and dramatic distortion", term: "wildly exaggerated" }
+];
+function clausesOf2(options) {
+  return Object.fromEntries(
+    options.filter((o) => o.id !== "auto").map((o) => [o.id, o.promptHint])
+  );
+}
+var POSITION_CLAUSES2 = clausesOf2(CHARACTER_FX_POSITIONS);
+var DURATION_CLAUSES2 = clausesOf2(CHARACTER_FX_DURATIONS);
+var INTENSITY_CLAUSES2 = clausesOf2(CHARACTER_FX_INTENSITIES);
 function composeCharacterFxHintFromConnections(effectId, targetHints, timing, mode = "full") {
   const ids = Array.isArray(effectId) ? Array.from(new Set(effectId)).slice(0, 2) : effectId ? [effectId] : [];
   const resolveBase = mode === "compact" ? getCharacterFxTerm : getCharacterFxPromptHint;
@@ -9518,7 +9529,17 @@ var SINGLE_CATALOGS = [
     defaultValue: "auto",
     categoryOrder: CHARACTER_FX_CATEGORY_ORDER,
     categoryLabels: CHARACTER_FX_CATEGORY_LABELS,
-    options: toOptions(CHARACTER_FX, "category")
+    options: toOptions(CHARACTER_FX, "category"),
+    // The node's three timing parameters, alongside the effect itself — the
+    // same shape `transition` carries above, but the character-fx scales, not
+    // the transition ones: the wording is deliberately different (an effect
+    // manifests and persists; a transition occurs and spans), so an id-only
+    // consumer must read these rows, never reuse the transition rows.
+    dimensions: perFieldDims([
+      ["position", CHARACTER_FX_POSITIONS],
+      ["duration", CHARACTER_FX_DURATIONS],
+      ["intensity", CHARACTER_FX_INTENSITIES]
+    ])
   },
   // -------- "Subject / Object" family --------
   {
@@ -11600,6 +11621,8 @@ function renderLens(l) {
   if (l.aperture) bits.push(`f/${l.aperture}`);
   return bits.length > 0 ? `Lens: ${bits.join(", ")}.` : "";
 }
+
+// src/ref-binding.ts
 function identityRefsSentence(firstOrdinal, lastOrdinal) {
   return firstOrdinal === lastOrdinal ? `${REF_BINDING.ordinal(firstOrdinal)} is an identity reference for this shot's subjects \u2014 match its subject's exact appearance; it is not a frame.` : `${REF_BINDING.ordinal(firstOrdinal)} through ${REF_BINDING.ordinal(lastOrdinal)} are identity references for this shot's subjects \u2014 match each subject's exact appearance; they are not frames.`;
 }
@@ -11611,6 +11634,38 @@ var REF_BINDING = {
   ordinal: (n) => `@image_${n}`,
   frame: (n, role) => `Use @image_${n} as the ${role} (${role === "opening" ? "first" : "last"}) frame of the video.`
 };
+
+// src/ref-id-tokens.ts
+var REF_TOKEN_LABEL_RE = /^[a-zA-Z0-9_ -]+$/;
+var HAS_REF_ID_TOKEN_RE = /\{ref:/i;
+var REF_ID_TOKEN_RE = /\{[rR][eE][fF]:([^{}]*)\}/g;
+var MALFORMED_REF_ID_TOKEN_RE = /\{[rR][eE][fF]:[^\s{}]*\}?/g;
+function splitLabel(content) {
+  const at = content.lastIndexOf(":");
+  if (at === -1) return { id: content };
+  const tail = content.slice(at + 1);
+  if (!REF_TOKEN_LABEL_RE.test(tail)) return { id: content };
+  return { id: content.slice(0, at), label: tail };
+}
+function resolveRefIdTokens(prompt, ctx) {
+  if (!prompt || !HAS_REF_ID_TOKEN_RE.test(prompt)) return prompt;
+  const known = (id) => id.length > 0 && (ctx.slotById.has(id) || ctx.nameById.has(id));
+  const bind = (id, label) => {
+    const slot = ctx.slotById.get(id);
+    if (slot !== void 0 && slot >= 1 && slot <= ctx.imageCount) {
+      return label ? REF_BINDING.image(label, slot) : REF_BINDING.ordinal(slot);
+    }
+    return label ?? ctx.nameById.get(id) ?? "";
+  };
+  return prompt.replace(REF_ID_TOKEN_RE, (_match, content) => {
+    if (known(content)) return bind(content, void 0);
+    const { id, label } = splitLabel(content);
+    if (known(id)) return bind(id, label);
+    return label ?? "";
+  }).replace(MALFORMED_REF_ID_TOKEN_RE, "");
+}
+
+// src/video-reference-resolver.ts
 var REFERENCE_TOKEN_RE = /\{(image|video|audio):(\d+)(?::([a-zA-Z0-9_ -]+))?\}/gi;
 function resolveReferenceTokens(prompt, counts) {
   if (!prompt) return prompt;
@@ -11711,12 +11766,27 @@ function resolveVideoReferenceCore(args) {
     });
   }
   const hasExtras = (args.extraRefs?.length ?? 0) > 0;
+  const nameByRefId = /* @__PURE__ */ new Map();
+  for (const r of args.wiredCharRefs) {
+    if (r.id && !nameByRefId.has(r.id)) nameByRefId.set(r.id, r.defaultName || r.characterSlug || "");
+  }
+  for (const ex of args.extraRefs ?? []) {
+    if (ex.id && !nameByRefId.has(ex.id)) nameByRefId.set(ex.id, "");
+  }
+  for (const [id, name] of args.refNamesById ?? []) {
+    if (id) nameByRefId.set(id, name);
+  }
+  const slotByRefId = /* @__PURE__ */ new Map();
   if (wiredCharRefs.length === 0 && !hasExtras) {
+    const counts = tokenCounts(leadingRefUrls.length);
     return {
       // tokenCounts(leadingRefUrls.length) → image count == offset (no assets here):
       // leadingRefUrls mode counts the leading refs; ordinalOffset mode counts the
       // caller-owned leading refs the offset stands in for.
-      prompt: resolveReferenceTokens(args.prompt, tokenCounts(leadingRefUrls.length)),
+      prompt: resolveReferenceTokens(
+        resolveRefIdTokens(args.prompt, { slotById: slotByRefId, nameById: nameByRefId, imageCount: counts.image }),
+        counts
+      ),
       additionalUrls: [...leadingRefUrls]
     };
   }
@@ -11749,9 +11819,13 @@ function resolveVideoReferenceCore(args) {
   let position = offset;
   for (let i = 0; i < resolved.additionalUrls.length; i++) {
     position += 1;
-    const ref = wiredCharRefs.find((r) => r.url === resolved.additionalUrls[i]);
+    const url2 = resolved.additionalUrls[i];
+    const ref = wiredCharRefs.find((r) => r.url === url2);
     const slug = ref?.characterSlug;
     if (slug && !positionsByChar.has(slug)) positionsByChar.set(slug, position);
+    for (const r of wiredCharRefs) {
+      if (r.url === url2 && r.id && !slotByRefId.has(r.id)) slotByRefId.set(r.id, position);
+    }
   }
   for (const r of wiredCharRefs) {
     if (r.source !== "wired-character") continue;
@@ -11764,6 +11838,7 @@ function resolveVideoReferenceCore(args) {
     fallbackUrls.push(r.url);
     position += 1;
     if (!positionsByChar.has(r.characterSlug)) positionsByChar.set(r.characterSlug, position);
+    if (r.id && !slotByRefId.has(r.id)) slotByRefId.set(r.id, position);
     if (hybrid) {
       const binding = REF_BINDING.ordinal(position);
       canonicalPhrases.push(shared.roleToPhrase(shared.resolveDefaultRole(r.defaultRole, r.defaultUsageMode, r.source), binding));
@@ -11801,6 +11876,7 @@ function resolveVideoReferenceCore(args) {
     for (const ex of args.extraRefs) {
       if (!ex.url) continue;
       position += 1;
+      if (ex.id && !slotByRefId.has(ex.id)) slotByRefId.set(ex.id, position);
       const desc = (ex.description ?? "").trim();
       if (ex.characterSlug) {
         const meta3 = args.lookupCharacterBySlug?.(ex.characterSlug);
@@ -11947,6 +12023,11 @@ ${finalPrompt}` : block;
       merged.push(u);
     }
   }
+  finalPrompt = resolveRefIdTokens(finalPrompt, {
+    slotById: slotByRefId,
+    nameById: nameByRefId,
+    imageCount: tokenCounts(merged.length).image
+  }) ?? finalPrompt;
   const referenceOrder = args.referenceOrder;
   const assetUrls = merged.slice(leadingRefUrls.length);
   if (referenceOrder && referenceOrder.length > 0 && assetUrls.length > 1) {
@@ -27333,7 +27414,7 @@ precise subject \u2192 action details \u2192 scene/environment \u2192 lighting &
 - Transitions and camera terms on 2.5: state a transition's trigger point AND method in one sentence \u2014 "At the 5-second mark, the camera quickly transitions leftward using a left wipe combined with a natural dissolve." Basic shot and camera terms are written directly (push in / pull out / pan / track / orbit / dolly zoom / whip pan / hard cut / dissolve / one-shot / speed ramp); only niche terms need [term + descriptive explanation] \u2014 which is exactly what the pickers' compact hint mode emits versus their long hints.
 
 **References (when reference media is attached)**
-- Refer to assets by ordinal in attachment order: "@Image 1", "Video 2", "Audio 1". Asset ORDER is priority \u2014 put the most identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding \u2014 \`{image:1:person}\` resolves to "the person from @image_1" \u2014 so a wired reference and its mention stay in sync.)
+- Refer to assets by ordinal in attachment order: "@Image 1", "Video 2", "Audio 1". Asset ORDER is priority \u2014 put the most identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding \u2014 \`{image:1:person}\` resolves to "the person from @image_1" \u2014 so a wired reference and its mention stay in sync. An API caller that passes \`connectedReferences\` can instead name a reference by its own id \u2014 \`{ref:<id>}\` / \`{ref:<id>:label}\` \u2014 and the platform substitutes the \`@image_N\` seat after it has numbered the references, so the client never computes N; a token whose reference was not attached drops to its label or name.)
 - Define each subject once, then reuse the label consistently: 'Define the woman in the red dress in Image 1 as the courier' \u2026 'the courier opens the door'. In multi-character scenes bind every character to its image ("the man from Image 1 hands the box to the woman from Image 2") and append: "do not generate duplicate copies of the same character".
 - Character identity: ONE close-up headshot + ONE full-body image is ideal. On the 2.0 SKUs do NOT attach multi-view/three-view character sheets \u2014 the model reads the views as separate people, causing identity drift and twin duplicates; 2.5 accepts multi-view images (see "Generation differences").
 - 4-5 assets total works best (1-2 character images + 1 scene image + 1 camera-movement video + 1 audio clip). Maxing out the 9-image/3-video/3-audio limits degrades feature priority and adherence.
@@ -27435,7 +27516,7 @@ precise subject \u2192 action details \u2192 scene/environment \u2192 lighting &
 - Nothing visual connected \u2192 text-to-video. A concrete aspect ratio is required (21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 \u2014 no adaptive); Nodaro renders 16:9 unless one is picked.
 
 **References (when reference media is attached)**
-- Refer to assets by ordinal in attachment order: "@Image 1", "Video 1", "Audio 1". Put the identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding, so a wired reference and its mention stay in sync.)
+- Refer to assets by ordinal in attachment order: "@Image 1", "Video 1", "Audio 1". Put the identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding, so a wired reference and its mention stay in sync. An API caller that passes \`connectedReferences\` can instead write \`{ref:<id>}\` / \`{ref:<id>:label}\` with the reference's own id \u2014 the platform substitutes the \`@image_N\` seat after numbering.)
 - Caps: 9 reference images; 3 reference videos, each 2-15s and \u226415s combined; 3 reference audio clips, \u226415s combined. Reference audio cannot be used alone \u2014 it must accompany an image or video reference.
 - Define each subject once, then reuse the label consistently ("the woman from @Image 1 \u2026 the woman opens the door"). A focused set of 4-5 assets beats maxing every cap.
 - Billing note: generated seconds AND reference-video input seconds bill at the same per-second rate; the first 5 input images are free and each extra image adds a small surcharge; audio input is free.
@@ -33402,7 +33483,10 @@ exports.CAMERA_MOTION_IDS = CAMERA_MOTION_IDS;
 exports.CHARACTER_FX = CHARACTER_FX;
 exports.CHARACTER_FX_CATEGORY_LABELS = CHARACTER_FX_CATEGORY_LABELS;
 exports.CHARACTER_FX_CATEGORY_ORDER = CHARACTER_FX_CATEGORY_ORDER;
+exports.CHARACTER_FX_DURATIONS = CHARACTER_FX_DURATIONS;
 exports.CHARACTER_FX_IDS = CHARACTER_FX_IDS;
+exports.CHARACTER_FX_INTENSITIES = CHARACTER_FX_INTENSITIES;
+exports.CHARACTER_FX_POSITIONS = CHARACTER_FX_POSITIONS;
 exports.CINEMATIC_LOOK_TAIL = CINEMATIC_LOOK_TAIL;
 exports.COLOR_LOOKS = COLOR_LOOKS;
 exports.COLOR_LOOK_CATEGORY_LABELS = COLOR_LOOK_CATEGORY_LABELS;
@@ -33866,6 +33950,7 @@ exports.resolveCharacterMentions = resolveCharacterMentions;
 exports.resolveGeminiOmniI2vInputs = resolveGeminiOmniI2vInputs;
 exports.resolveLocationMentions = resolveLocationMentions;
 exports.resolvePrompt = resolvePrompt;
+exports.resolveRefIdTokens = resolveRefIdTokens;
 exports.resolveReferenceTokens = resolveReferenceTokens;
 exports.resolveSeedance2Inputs = resolveSeedance2Inputs;
 exports.resolveTemplate = resolveTemplate;