@nodaro/prompts 1.9.0 → 1.11.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 --------
   {
@@ -10456,6 +10477,55 @@ function resolveLocationMentionsHybrid(prompt, tokens, refs, existingUrls) {
   }
   return { prompt: resolvedPrompt, additionalUrls, mentionedLocationSlugs, lockLines, elementDirectives };
 }
+function resolveImageMentionsHybrid(prompt, tokens, refs, existingUrls) {
+  const bySlug = /* @__PURE__ */ new Map();
+  for (const r of refs) {
+    const slug = shared.imageMentionSlugForRef(r);
+    if (!slug) continue;
+    if (!bySlug.has(slug)) bySlug.set(slug, r);
+  }
+  const additionalUrls = [];
+  const refByUrl = /* @__PURE__ */ new Map();
+  const lockOverrideByUrl = /* @__PURE__ */ new Map();
+  const matched = [];
+  for (const t of tokens) {
+    const match = bySlug.get(t.imageSlug);
+    if (!match || !match.url) continue;
+    additionalUrls.push(match.url);
+    refByUrl.set(match.url, match);
+    if (t.lock !== void 0) lockOverrideByUrl.set(match.url, t.lock);
+    const role = (t.role ?? "").trim() || shared.resolveDefaultRole(match.defaultRole, match.defaultUsageMode, match.source);
+    matched.push({ token: t.token, offset: t.offset, url: match.url, role });
+  }
+  const slotByUrl = /* @__PURE__ */ new Map();
+  for (const u of [...existingUrls, ...additionalUrls]) {
+    if (!slotByUrl.has(u)) slotByUrl.set(u, slotByUrl.size + 1);
+  }
+  const bindingFor = (url2) => {
+    const slot = slotByUrl.get(url2);
+    return slot ? `reference image ${slotToLetter(slot)}` : "the reference image";
+  };
+  let resolvedPrompt = prompt;
+  for (const m of [...matched].sort((a, b) => b.offset - a.offset)) {
+    const phrase = shared.roleToPhrase(m.role, bindingFor(m.url));
+    resolvedPrompt = resolvedPrompt.slice(0, m.offset) + phrase + resolvedPrompt.slice(m.offset + m.token.length);
+  }
+  const lockLines = [];
+  const elementDirectives = [];
+  const seenUrls = /* @__PURE__ */ new Set();
+  for (const m of matched) {
+    if (seenUrls.has(m.url)) continue;
+    seenUrls.add(m.url);
+    const ref = refByUrl.get(m.url);
+    if (!ref) continue;
+    const binding = bindingFor(m.url);
+    const lock = buildIdentityLockLine(withForcedIdentityLock(ref, lockOverrideByUrl.get(m.url)), binding);
+    if (lock) lockLines.push(lock);
+    const inject = ref.elementInjection?.trim();
+    if (inject) elementDirectives.push(inject);
+  }
+  return { prompt: resolvedPrompt, additionalUrls, lockLines, elementDirectives };
+}
 function buildCanonicalFallback(refs, mentionedSlugs, startIndex) {
   const directiveLines = [];
   const urls = [];
@@ -10838,7 +10908,9 @@ function buildImagePromptInternal(config2, marks) {
         connectedReferences.map((r) => r.locationSlug).filter((s) => typeof s === "string" && s.length > 0)
       )
     );
-    if (knownCharacterSlugs.length > 0 || hasExtraRefs || knownLocationSlugs.length > 0) {
+    const knownImageSlugs = shared.knownImageSlugsFromRefs(connectedReferences);
+    const hasImageMentionTokens = isHybrid && knownImageSlugs.length > 0 && shared.findImageMentionTokens(config2.prompt, knownImageSlugs).length > 0;
+    if (knownCharacterSlugs.length > 0 || hasExtraRefs || knownLocationSlugs.length > 0 || hasImageMentionTokens) {
       const mentionTokens = knownCharacterSlugs.length > 0 ? shared.findCharacterMentionTokens(config2.prompt, knownCharacterSlugs) : [];
       let hybridLockLines = [];
       let hybridElementDirectives = [];
@@ -10892,6 +10964,24 @@ function buildImagePromptInternal(config2, marks) {
         if (r.locationVariantBucket) return false;
         return !mentionedLocationSlugs.has(r.locationSlug);
       });
+      let hybridImageLockLines = [];
+      let hybridImageElementDirectives = [];
+      if (hasImageMentionTokens) {
+        const imageTokens = shared.findImageMentionTokens(resolved.prompt, knownImageSlugs);
+        if (imageTokens.length > 0) {
+          const hi = resolveImageMentionsHybrid(
+            resolved.prompt,
+            imageTokens,
+            connectedReferences,
+            [...referenceImageUrls || [], ...resolved.additionalUrls]
+          );
+          resolved.prompt = hi.prompt;
+          resolved.additionalUrls = [...resolved.additionalUrls, ...hi.additionalUrls];
+          hybridImageLockLines = hi.lockLines;
+          hybridImageElementDirectives = hi.elementDirectives;
+          if (hi.additionalUrls.length > 0) hybridBodyConverged = true;
+        }
+      }
       const prefixDedupedLength = [
         ...referenceImageUrls || [],
         ...resolved.additionalUrls
@@ -10972,12 +11062,14 @@ ${promptForNext}`;
         const allLockLines = [.../* @__PURE__ */ new Set([
           ...hybridLockLines,
           ...hybridLocationLockLines,
+          ...hybridImageLockLines,
           ...canonical.lockLines,
           ...extrasRendered.lockLines
         ])];
         const trailingLines = [
           ...hybridElementDirectives,
           ...hybridLocationElementDirectives,
+          ...hybridImageElementDirectives,
           ...canonical.phrases,
           ...canonical.elementDirectives,
           ...extrasRendered.bodyLines,
@@ -11600,6 +11692,134 @@ function renderLens(l) {
   if (l.aperture) bits.push(`f/${l.aperture}`);
   return bits.length > 0 ? `Lens: ${bits.join(", ")}.` : "";
 }
+
+// src/direction-registry.ts
+var perId = (full, compact) => (ids, mode) => {
+  const out = [];
+  for (const id of ids) {
+    const frag = mode === "compact" ? compact(id) : full(id);
+    if (frag.length > 0) out.push(frag);
+  }
+  return out;
+};
+var viaListBuilder = (build) => (ids, mode) => build(ids.length === 1 ? ids[0] : [...ids], mode).filter((s) => s.length > 0);
+var viaStringBuilder = (build) => (ids, mode) => {
+  const s = build(ids.length === 1 ? ids[0] : [...ids], mode);
+  return s.length > 0 ? [s] : [];
+};
+var viaMood = (ids, mode) => buildMoodHints({ mood: ids.length === 1 ? ids[0] : [...ids] }, mode).filter(
+  (s) => s.length > 0
+);
+var framing = perId(getFramingPromptHint, getFramingTerm);
+var lighting = perId(getLightingPromptHint, getLightingTerm);
+var exposure = perId(getExposurePromptHint, getExposureTerm);
+var temporal = perId(getTemporalPromptHint, getTemporalTerm);
+var DIRECTION_FIELDS = [
+  { key: "cameraMotion", surface: "video", family: "motion", maxPicks: 1, render: perId(getCameraMotionPromptHint, getCameraMotionTerm) },
+  // Composition (the Framing catalog, one row per category).
+  { key: "shotSize", surface: "both", family: "look", maxPicks: 1, render: framing },
+  { key: "angle", surface: "both", family: "look", maxPicks: 1, render: framing },
+  { key: "coverage", surface: "both", family: "look", maxPicks: 1, render: framing },
+  { key: "composition", surface: "both", family: "look", maxPicks: 2, render: framing },
+  { key: "vantage", surface: "both", family: "look", maxPicks: 1, render: framing },
+  { key: "pose", surface: "both", family: "look", maxPicks: 1, render: perId(getPosePromptHint, getPoseTerm) },
+  { key: "compositionEffect", surface: "both", family: "look", maxPicks: 1, render: perId(getCompositionEffectPromptHint, getCompositionEffectTerm) },
+  // Camera.
+  { key: "cameraFormat", surface: "both", family: "look", maxPicks: 1, render: perId(getCameraFormatPromptHint, getCameraFormatTerm) },
+  { key: "lens", surface: "both", family: "look", maxPicks: 1, render: perId(getLensPromptHint, getLensTerm) },
+  // Exposure (stills only — a video's exposure rides its own temporal levers).
+  { key: "aperture", surface: "image", family: "look", maxPicks: 1, render: exposure },
+  { key: "shutterSpeed", surface: "image", family: "look", maxPicks: 1, render: exposure },
+  { key: "isoValue", surface: "image", family: "look", maxPicks: 1, render: exposure },
+  // Light (the Lighting catalog, one row per category).
+  { key: "timeOfDay", surface: "both", family: "look", maxPicks: 1, render: lighting },
+  { key: "lightingStyle", surface: "both", family: "look", maxPicks: 2, render: lighting },
+  { key: "lightingDirection", surface: "both", family: "look", maxPicks: 1, render: lighting },
+  { key: "lightingRatio", surface: "both", family: "look", maxPicks: 1, render: lighting },
+  { key: "colorTemperature", surface: "both", family: "look", maxPicks: 1, render: lighting },
+  { key: "colorLook", surface: "both", family: "look", maxPicks: 1, render: perId(getColorLookPromptHint, getColorLookTerm) },
+  { key: "atmosphere", surface: "both", family: "look", maxPicks: 2, render: viaListBuilder(buildAtmosphereHints) },
+  { key: "postProcess", surface: "image", family: "look", maxPicks: 2, render: viaListBuilder(buildPostProcessHints) },
+  // Style.
+  { key: "style", surface: "both", family: "look", maxPicks: 1, render: perId(getStylePromptHint, getStyleTerm) },
+  { key: "mood", surface: "both", family: "look", maxPicks: 2, render: viaMood },
+  { key: "aesthetic", surface: "both", family: "look", maxPicks: 2, render: viaStringBuilder(buildAestheticHints) },
+  { key: "photoGenre", surface: "image", family: "look", maxPicks: 1, render: perId(getPhotoGenrePromptHint, getPhotoGenreTerm) },
+  { key: "photographer", surface: "image", family: "look", maxPicks: 2, render: viaStringBuilder(buildPhotographerHints) },
+  { key: "renderQuality", surface: "image", family: "look", maxPicks: 1, render: perId(getRenderQualityPromptHint, getRenderQualityTerm) },
+  // Scene.
+  { key: "setting", surface: "both", family: "look", maxPicks: 1, render: perId(getSettingPromptHint, getSettingTerm) },
+  { key: "era", surface: "both", family: "look", maxPicks: 1, render: perId(getEraPromptHint, getEraTerm) },
+  { key: "backdrop", surface: "both", family: "look", maxPicks: 1, render: perId(getBackdropPromptHint, getBackdropTerm) },
+  // Motion & time.
+  { key: "actionFx", surface: "video", family: "motion", maxPicks: 2, render: viaListBuilder(buildActionFxHints) },
+  { key: "temporalSpeed", surface: "video", family: "motion", maxPicks: 1, render: temporal },
+  { key: "temporalFreeze", surface: "video", family: "motion", maxPicks: 1, render: temporal },
+  { key: "temporalDirection", surface: "video", family: "motion", maxPicks: 1, render: temporal },
+  { key: "temporalShutter", surface: "video", family: "motion", maxPicks: 1, render: temporal },
+  { key: "transition", surface: "video", family: "motion", maxPicks: 2, render: perId(getTransitionPromptHint, getTransitionTerm) },
+  { key: "loopSubject", surface: "video", family: "motion", maxPicks: 1, render: perId(getLoopSubjectPromptHint, getLoopSubjectTerm) },
+  // ── LEGACY BLOCK — see the table doc above. Placed LAST, in today's exact
+  //    `composePromptText` order, so every pre-registry caller is byte-identical.
+  { key: "framingId", surface: "both", family: "look", maxPicks: 1, render: framing },
+  { key: "framingAngleId", surface: "both", family: "look", maxPicks: 1, render: framing },
+  { key: "lightingId", surface: "both", family: "look", maxPicks: 1, render: lighting },
+  { key: "lensId", surface: "both", family: "look", maxPicks: 1, render: perId(getLensPromptHint, getLensTerm) },
+  { key: "cameraFormatId", surface: "both", family: "look", maxPicks: 1, render: perId(getCameraFormatPromptHint, getCameraFormatTerm) }
+];
+var DIRECTION_KEYS = DIRECTION_FIELDS.map((f) => f.key);
+var IMAGE_HINT_MODE_DEFAULT = "full";
+var VIDEO_HINT_MODE_DEFAULT = { look: "full", motion: "compact" };
+function modeForFamily(mode, family) {
+  return typeof mode === "string" ? mode : family === "motion" ? mode.motion : mode.look;
+}
+var DIRECTION_ARRAY_CEILING = 8;
+var DIRECTION_ID_MAX_CHARS = 100;
+function normalizeDirectionIds(value, maxPicks) {
+  const ids = [];
+  if (typeof value === "string") {
+    if (value) ids.push(value);
+  } else if (Array.isArray(value)) {
+    for (const v of value) {
+      if (ids.length >= maxPicks) break;
+      if (typeof v === "string" && v && !ids.includes(v)) ids.push(v);
+    }
+  }
+  return ids.slice(0, maxPicks);
+}
+function directionFieldsForSurface(surface) {
+  return DIRECTION_FIELDS.filter((f) => f.surface === "both" || f.surface === surface);
+}
+function renderDirectionHints(direction, opts) {
+  if (!direction) return [];
+  const mode = opts.mode ?? "full";
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const spec of DIRECTION_FIELDS) {
+    if (spec.surface !== "both" && spec.surface !== opts.surface) continue;
+    const ids = normalizeDirectionIds(
+      direction[spec.key],
+      spec.maxPicks
+    );
+    if (ids.length === 0) continue;
+    for (const hint of spec.render(ids, modeForFamily(mode, spec.family))) {
+      if (hint.length > 0 && !seen.has(hint)) {
+        seen.add(hint);
+        out.push(hint);
+      }
+    }
+  }
+  return out;
+}
+
+// src/prompt-hint-join.ts
+var PROMPT_HINT_SEPARATOR = ". ";
+function joinPromptHints(userPrompt, hints) {
+  if (hints.length === 0) return userPrompt;
+  return [userPrompt.trim(), ...hints].filter((p) => p.length > 0).join(PROMPT_HINT_SEPARATOR);
+}
+
+// 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 +11831,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 +11963,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 +12016,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 +12035,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 +12073,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 +12220,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) {
@@ -12128,15 +12406,10 @@ function assembleSunoInput(input) {
 // src/assemble-image-input.ts
 function composePromptText(userPrompt, direction, structured) {
   const hints = [
-    getFramingPromptHint(direction?.framingId),
-    getFramingPromptHint(direction?.framingAngleId),
-    getLightingPromptHint(direction?.lightingId),
-    getLensPromptHint(direction?.lensId),
-    getCameraFormatPromptHint(direction?.cameraFormatId),
+    ...renderDirectionHints(direction, { surface: "image", mode: IMAGE_HINT_MODE_DEFAULT }),
     structured ? renderStructuredFields(structured) : ""
   ].filter((p) => p.length > 0);
-  if (hints.length === 0) return userPrompt;
-  return [userPrompt.trim(), ...hints].filter((p) => p.length > 0).join(". ");
+  return joinPromptHints(userPrompt, hints);
 }
 function assembleImageInput(input) {
   const prompt = composePromptText(input.userPrompt, input.direction, input.structured);
@@ -12171,6 +12444,106 @@ function assembleImageInput(input) {
   }
   return result;
 }
+
+// src/assemble-video-input.ts
+function composeVideoPromptText(userPrompt, direction, structured, opts) {
+  const hints = [
+    ...renderDirectionHints(direction, {
+      surface: "video",
+      mode: opts?.hintMode ?? VIDEO_HINT_MODE_DEFAULT
+    }),
+    structured ? renderStructuredFields(structured) : ""
+  ].filter((p) => p.length > 0);
+  if (hints.length === 0) return userPrompt;
+  return joinPromptHints(userPrompt ?? "", hints);
+}
+
+// src/read-node-direction.ts
+function readDirectionFields(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const src = value;
+  const out = {};
+  for (const spec of DIRECTION_FIELDS) {
+    const v = src[spec.key];
+    if (typeof v === "string") {
+      if (v.length > 0 && v.length <= DIRECTION_ID_MAX_CHARS) out[spec.key] = v;
+    } else if (Array.isArray(v)) {
+      const kept = [];
+      for (const x of v) {
+        if (kept.length >= DIRECTION_ARRAY_CEILING) break;
+        if (typeof x === "string" && x.length > 0 && x.length <= DIRECTION_ID_MAX_CHARS) {
+          kept.push(x);
+        }
+      }
+      if (kept.length > 0) out[spec.key] = kept;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+var GENDERS = ["man", "woman", "child", "non-binary"];
+var MAX_STRUCTURED_VALUE_CHARS = 200;
+var PERSON_FIELDS2 = {
+  age: "number",
+  gender: "gender",
+  hair: "string",
+  eyes: "string",
+  expression: "string",
+  profession: "string",
+  warriorType: "string"
+};
+var STYLING_FIELDS2 = {
+  mood: "string",
+  lighting: "string",
+  aesthetic: "string",
+  colorLook: "string"
+};
+var SETTING_FIELDS = {
+  era: "string",
+  atmosphere: "string",
+  backdrop: "string"
+};
+var CAMERA_FIELDS = {
+  framing: "string",
+  motion: "string",
+  format: "string"
+};
+var LENS_FIELDS = { focalLength: "string", aperture: "string" };
+var STRUCTURED_GROUPS = {
+  person: PERSON_FIELDS2,
+  styling: STYLING_FIELDS2,
+  setting: SETTING_FIELDS,
+  camera: CAMERA_FIELDS,
+  lens: LENS_FIELDS
+};
+function readField(v, kind) {
+  if (kind === "number") return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+  if (typeof v !== "string" || v.length === 0 || v.length > MAX_STRUCTURED_VALUE_CHARS) {
+    return void 0;
+  }
+  if (kind === "gender") return GENDERS.includes(v) ? v : void 0;
+  return v;
+}
+function readStructuredFields(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const src = value;
+  const out = {};
+  for (const group of Object.keys(STRUCTURED_GROUPS)) {
+    const raw = src[group];
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) continue;
+    const rawRec = raw;
+    const kept = {};
+    for (const [field, kind] of Object.entries(
+      STRUCTURED_GROUPS[group]
+    )) {
+      const v = readField(rawRec[field], kind);
+      if (v !== void 0) kept[field] = v;
+    }
+    if (Object.keys(kept).length > 0) out[group] = kept;
+  }
+  const mood = readField(src.mood, "string");
+  if (mood !== void 0) out.mood = mood;
+  return Object.keys(out).length > 0 ? out : void 0;
+}
 var clean = (u) => {
   const t = u?.trim();
   return t && t.length > 0 ? t : void 0;
@@ -27333,7 +27706,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 +27808,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.
@@ -33187,8 +33560,8 @@ var SINGLE_PICKER_WIRING = [
   { kind: "single", nodeType: "furniture", label: "Furniture", valueField: "furniture", defaultValue: "sofa", catalogId: "furniture", entries: mapCat(shared.FURNITURE, "subcategory"), groupOrder: shared.FURNITURE_SUBCATEGORY_ORDER, groupLabels: shared.FURNITURE_SUBCATEGORY_LABELS },
   { kind: "single", nodeType: "held-prop", label: "Held Prop", valueField: "heldProp", defaultValue: "smartphone", catalogId: "held-prop", entries: mapCat(HELD_PROPS, "category"), groupOrder: HELD_PROP_CATEGORY_ORDER, groupLabels: HELD_PROP_CATEGORY_LABELS }
 ];
-var STYLING_FIELDS2 = STYLING_DIMENSION_ORDER.map((d) => STYLING_FIELD_BY_DIMENSION[d]);
-var PERSON_FIELDS2 = PERSON_DIMENSION_ORDER.map((d) => PERSON_FIELD_BY_DIMENSION[d]);
+var STYLING_FIELDS3 = STYLING_DIMENSION_ORDER.map((d) => STYLING_FIELD_BY_DIMENSION[d]);
+var PERSON_FIELDS3 = PERSON_DIMENSION_ORDER.map((d) => PERSON_FIELD_BY_DIMENSION[d]);
 var LIGHTING_FIELDS2 = LIGHTING_CATEGORY_ORDER.map((c) => LIGHTING_FIELD_BY_CATEGORY[c]);
 var TEMPORAL_FIELD_BY_CATEGORY2 = {
   speed: "temporalSpeed",
@@ -33224,7 +33597,7 @@ var MULTI_PICKER_WIRING = [
     kind: "multi",
     nodeType: "person",
     label: "Person",
-    fields: PERSON_FIELDS2,
+    fields: PERSON_FIELDS3,
     catalogId: "person",
     catalogEntries: flatCat(PEOPLE),
     fieldOptions: optionsByDiscriminator(PEOPLE, (e) => e.dimension, PERSON_FIELD_BY_DIMENSION)
@@ -33233,7 +33606,7 @@ var MULTI_PICKER_WIRING = [
     kind: "multi",
     nodeType: "styling",
     label: "Styling",
-    fields: STYLING_FIELDS2,
+    fields: STYLING_FIELDS3,
     catalogId: "styling",
     catalogEntries: flatCat(STYLINGS),
     fieldOptions: optionsByDiscriminator(STYLINGS, (e) => e.dimension, STYLING_FIELD_BY_DIMENSION)
@@ -33402,7 +33775,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;
@@ -33412,6 +33788,10 @@ exports.COMPOSITION_EFFECTS = COMPOSITION_EFFECTS;
 exports.COMPOSITION_EFFECT_IDS = COMPOSITION_EFFECT_IDS;
 exports.DEFAULT_IDENTITY_LOCK = DEFAULT_IDENTITY_LOCK;
 exports.DEFAULT_TEMPLATES = DEFAULT_TEMPLATES;
+exports.DIRECTION_ARRAY_CEILING = DIRECTION_ARRAY_CEILING;
+exports.DIRECTION_FIELDS = DIRECTION_FIELDS;
+exports.DIRECTION_ID_MAX_CHARS = DIRECTION_ID_MAX_CHARS;
+exports.DIRECTION_KEYS = DIRECTION_KEYS;
 exports.ERAS = ERAS;
 exports.ERA_CATEGORY_LABELS = ERA_CATEGORY_LABELS;
 exports.ERA_CATEGORY_ORDER = ERA_CATEGORY_ORDER;
@@ -33434,6 +33814,7 @@ exports.HELD_PROPS = HELD_PROPS;
 exports.HELD_PROP_CATEGORY_LABELS = HELD_PROP_CATEGORY_LABELS;
 exports.HELD_PROP_CATEGORY_ORDER = HELD_PROP_CATEGORY_ORDER;
 exports.HELD_PROP_IDS = HELD_PROP_IDS;
+exports.IMAGE_HINT_MODE_DEFAULT = IMAGE_HINT_MODE_DEFAULT;
 exports.IMAGE_REFERENCE_PROMPT_DOCTRINE = IMAGE_REFERENCE_PROMPT_DOCTRINE;
 exports.IMAGE_WIZARD_CATEGORIES = IMAGE_WIZARD_CATEGORIES;
 exports.INSTRUMENTATION_DEFAULT_DATA = INSTRUMENTATION_DEFAULT_DATA;
@@ -33511,6 +33892,7 @@ exports.POST_PROCESS_EFFECT_IDS = POST_PROCESS_EFFECT_IDS;
 exports.PRODUCTION_STYLES = PRODUCTION_STYLES;
 exports.PROMPT_AFFIX_CORE_FIELD_OVERRIDES = PROMPT_AFFIX_CORE_FIELD_OVERRIDES;
 exports.PROMPT_AFFIX_NODE_TYPES = PROMPT_AFFIX_NODE_TYPES;
+exports.PROMPT_HINT_SEPARATOR = PROMPT_HINT_SEPARATOR;
 exports.PROVIDER_CAPABILITIES = PROVIDER_CAPABILITIES;
 exports.PROVIDER_PROMPT_DOCTRINES = PROVIDER_PROMPT_DOCTRINES;
 exports.REFERENCE_IMAGE_ROLES = REFERENCE_IMAGE_ROLES;
@@ -33550,6 +33932,7 @@ exports.TRANSITION_DURATIONS = TRANSITION_DURATIONS;
 exports.TRANSITION_IDS = TRANSITION_IDS;
 exports.TRANSITION_INTENSITIES = TRANSITION_INTENSITIES;
 exports.TRANSITION_POSITIONS = TRANSITION_POSITIONS;
+exports.VIDEO_HINT_MODE_DEFAULT = VIDEO_HINT_MODE_DEFAULT;
 exports.VIDEO_WIZARD_CATEGORIES = VIDEO_WIZARD_CATEGORIES;
 exports.VOCAL_PRESENCE = VOCAL_PRESENCE;
 exports.VOCAL_PRESENCE_INSTRUMENTAL_ID = VOCAL_PRESENCE_INSTRUMENTAL_ID;
@@ -33647,10 +34030,12 @@ exports.composeNegative = composeNegative;
 exports.composePickerCatalogs = composePickerCatalogs;
 exports.composeSoundHintFromConnections = composeSoundHintFromConnections;
 exports.composeTransitionHintFromConnections = composeTransitionHintFromConnections;
+exports.composeVideoPromptText = composeVideoPromptText;
 exports.computeLlmChatFields = computeLlmChatFields;
 exports.computeNodePrompt = computeNodePrompt;
 exports.computePackSidecarCoverage = computePackSidecarCoverage;
 exports.deriveTerm = deriveTerm;
+exports.directionFieldsForSurface = directionFieldsForSurface;
 exports.expandImagePositionRefs = expandImagePositionRefs;
 exports.expandImageRefTokens = expandImageRefTokens;
 exports.filmStillPrefix = filmStillPrefix;
@@ -33841,9 +34226,11 @@ exports.isInstrumentalVocal = isInstrumentalVocal;
 exports.isSuspiciousDerivedTerm = isSuspiciousDerivedTerm;
 exports.isVantageFraming = isVantageFraming;
 exports.isWizardSupported = isWizardSupported;
+exports.joinPromptHints = joinPromptHints;
 exports.joinPromptParts = joinPromptParts;
 exports.listPickerCatalogs = listPickerCatalogs;
 exports.migratePersonValue = migratePersonValue;
+exports.modeForFamily = modeForFamily;
 exports.nodeHasInlinePrompt = nodeHasInlinePrompt;
 exports.nodeHasPromptField = nodeHasPromptField;
 exports.nodeSupportsPromptAffixes = nodeSupportsPromptAffixes;
@@ -33855,9 +34242,12 @@ exports.promptAffixCoreField = promptAffixCoreField;
 exports.promptBindsFirstFrame = promptBindsFirstFrame;
 exports.promptFieldCarriesAffixes = promptFieldCarriesAffixes;
 exports.promptPartSeparator = promptPartSeparator;
+exports.readDirectionFields = readDirectionFields;
+exports.readStructuredFields = readStructuredFields;
 exports.referenceRulesBlock = referenceRulesBlock;
 exports.registerCatalogPack = registerCatalogPack;
 exports.registerPersonPack = registerPersonPack;
+exports.renderDirectionHints = renderDirectionHints;
 exports.renderStructuredFields = renderStructuredFields;
 exports.resetCatalogPacks = resetCatalogPacks;
 exports.resetPersonPacks = resetPersonPacks;
@@ -33866,6 +34256,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;