@nodaro/prompts 1.8.1 → 1.10.0

package/src/node-prompt-fields.ts

@@ -0,0 +1,206 @@
+/**
+ * Single source of truth: which data field(s) hold a node's user-editable
+ * prompt text. Drives the quick-edit Prompt modal so it can work generically
+ * across every AI node without each call site hardcoding a field name.
+ *
+ * The registry LIVES HERE (`@nodaro/prompts`) so the backend orchestrator, the
+ * `/v1/nodes` registry, the prompt-affix totality tests and the docs tooling
+ * read the SAME list the editor does. `frontend/src/lib/prompt-fields.ts` is a
+ * pure re-export of this module — frontend code keeps importing
+ * `@/lib/prompt-fields` unchanged.
+ *
+ * Most nodes store the prompt in `data.prompt`, but several don't
+ * (`text-prompt` → `text`, `image-to-text` → `customPrompt`, …) — this map is
+ * where that knowledge lives, once.
+ *
+ * INVARIANT: every node that exposes a user-editable prompt MUST have an entry
+ * here, or the quick-edit modal silently does nothing for it. A guard test
+ * (`prompt-fields.test.ts`) keeps this in sync with the node set.
+ *
+ * This module is intentionally pure data (no React/lucide imports) so it can be
+ * pulled into the app-runtime bundle and any test without dragging in the icon
+ * library. The string `icon` kind is mapped to a concrete lucide component in
+ * `prompt-edit-button.tsx` (`getPromptIcon`), the only place that renders it.
+ */
+
+import type { SnippetMedia } from "./factory-snippets/types.js"
+import { NODE_PROMPT_CANDIDATE_FIELDS } from "./resolve-prompt.js"
+
+/** Which lucide glyph a node's prompt affordance uses. Kept as a string so this
+ *  module stays icon-library-free; mapped to a component in the strip button. */
+export type PromptIconKind = "pencil" | "paintbrush"
+
+export interface PromptFieldSpec {
+  /** Data key holding the primary prompt (e.g. "prompt", "text", "customPrompt"). */
+  readonly prompt: string
+  /** Data key holding the negative prompt, when the node supports one. */
+  readonly negative?: string
+  /** Label override for the primary field (defaults to "Prompt"). */
+  readonly promptLabel?: string
+  /** Icon for the prompt affordance (strip button + modal title). Defaults to a
+   *  pencil; image-editing nodes use a paintbrush to read as "edit". */
+  readonly icon?: PromptIconKind
+  /** Node modality for prompt-snippet scoping — drives which snippet pool the
+   *  "/" menu and Snippets button show for this node's prompt fields. REQUIRED
+   *  so a new node cannot forget to declare it (compile error). */
+  readonly media: SnippetMedia
+  /** True when this node renders a media-result preview body and therefore
+   *  participates in inline-prompt mode (the `InlineNodePrompt` editor on the
+   *  node face, centralized in `BaseNode`). REQUIRED (like `media`) so a new
+   *  prompt node must consciously choose — compile error if omitted. The set of
+   *  `inline: true` types is guarded in `prompt-fields.test.ts`. */
+  readonly inline: boolean
+  /** Some nodes only READ their prompt field when a sibling discriminator
+   *  selects it — TTS keeps `directText` but resolves it only while
+   *  `textSource === "direct"`, defaulting to `"connected"`. Writing the text
+   *  without flipping the discriminator saved the value and then failed with
+   *  "no text found" (founder hit it live, 2026-08-14). Declare the pair here
+   *  and every writer flips it automatically. */
+  readonly promptGate?: { readonly field: string; readonly value: string }
+  /** Prompt pre/post text (`promptPrefix` / `promptSuffix`) support. Defaults to
+   *  ON for every prompt node; set `false` ONLY for a node whose "prompt" is not
+   *  a model prompt (the plain Text input node). Read via `nodeSupportsPromptAffixes`. */
+  readonly affixes?: false
+}
+
+export const NODE_PROMPT_FIELDS: Readonly<Record<string, PromptFieldSpec>> = {
+  // ── Image ──
+  // (`edit-image` / `image-to-image` are legacy types consolidated into
+  // `modify-image`; they're not in the creatable node set, so a node of that
+  // type never mounts and needs no entry here. The guard test enforces that.)
+  "generate-image": { prompt: "prompt", negative: "negativePrompt", media: "image", inline: true },
+  "modify-image": { prompt: "prompt", negative: "negativePrompt", icon: "paintbrush", media: "image", inline: true },
+  "generate-mask": { prompt: "prompt", promptLabel: "What to mask", media: "image", inline: true },
+  // ── Video ──
+  "generate-video": { prompt: "prompt", negative: "negativePrompt", media: "video", inline: true },
+  // Trimmed multi-segment stitch sibling of generate-video — no negativePrompt field.
+  "generate-video-pro": { prompt: "prompt", media: "video", inline: true },
+  // Span-replace sibling of generate-video-pro — no negativePrompt field.
+  "edit-video-pro": { prompt: "prompt", media: "video", inline: true },
+  "text-to-video": { prompt: "prompt", negative: "negativePrompt", media: "video", inline: true },
+  "image-to-video": { prompt: "prompt", negative: "negativePrompt", promptLabel: "Motion prompt", media: "video", inline: true },
+  "video-to-video": { prompt: "prompt", negative: "negativePrompt", media: "video", inline: true },
+  "switchx": { prompt: "prompt", promptLabel: "Look prompt", media: "video", inline: true },
+  "extend-video": { prompt: "prompt", negative: "negativePrompt", media: "video", inline: true },
+  "speech-to-video": { prompt: "prompt", negative: "negativePrompt", media: "video", inline: true },
+  "motion-transfer": { prompt: "prompt", negative: "negativePrompt", media: "video", inline: true },
+  // Cinematic Avatar (HeyGen) — generative prompt (NOT a verbatim script),
+  // so it participates in the quick-edit Prompt modal like other AI video nodes.
+  "cinematic-avatar": { prompt: "prompt", media: "video", inline: true },
+  "video-sfx": { prompt: "prompt", negative: "negativePrompt", promptLabel: "Sound prompt", media: "audio", inline: true },
+  "video-retake": { prompt: "prompt", promptLabel: "Retake prompt", media: "video", inline: true },
+  // ── Audio / music ──
+  "generate-music": { prompt: "prompt", media: "audio", inline: true },
+  "suno-generate": { prompt: "prompt", media: "audio", inline: true },
+  "text-to-audio": { prompt: "prompt", media: "audio", inline: true },
+  // ── Text / LLM (no media-result preview body → no inline editor) ──
+  "text-prompt": { prompt: "text", promptLabel: "Text", media: "text", inline: false, affixes: false },
+  "image-to-text": { prompt: "customPrompt", promptLabel: "Question", media: "text", inline: false },
+  "llm-chat": { prompt: "userInput", promptLabel: "Prompt", media: "text", inline: false },
+  // ── Speech / voice ──
+  "text-to-speech": { prompt: "directText", promptLabel: "Text", media: "audio", inline: true, promptGate: { field: "textSource", value: "direct" } },
+  "voice-design": { prompt: "voiceDescription", promptLabel: "Voice description", media: "audio", inline: true },
+  "voice-remix": { prompt: "voiceDescription", promptLabel: "Voice description", media: "audio", inline: true },
+  "lip-sync": { prompt: "prompt", media: "audio", inline: true },
+  // ── Suno (music) ──
+  "suno-cover": { prompt: "prompt", media: "audio", inline: true },
+  "suno-extend": { prompt: "prompt", media: "audio", inline: true },
+  "suno-replace-section": { prompt: "prompt", media: "audio", inline: true },
+  "suno-upload-extend": { prompt: "prompt", media: "audio", inline: true },
+  // NOTE: `suno-add-vocals` is intentionally absent — its node has no
+  // user-editable prompt (SunoAddVocalsData declares only `model`; the config
+  // panel + backend route take taskId/audioId/model, never a prompt). A stale
+  // entry here rendered a phantom Prompt editor in the quick-edit modal that
+  // wrote to a `data.prompt` key nothing ever reads (the dead-field class the
+  // guard test now catches via defaultData ownership).
+  "suno-lyrics": { prompt: "prompt", media: "audio", inline: false },
+  "suno-style-boost": { prompt: "content", promptLabel: "Style", media: "audio", inline: false },
+  // ── Composition / FX (compact, no media-result preview → no inline editor) ──
+  "image-critic": { prompt: "prompt", promptLabel: "Criteria", media: "image", inline: false },
+  "motion-graphics": { prompt: "motionPrompt", promptLabel: "Motion prompt", media: "video", inline: false },
+  "3d-title": { prompt: "titlePrompt", promptLabel: "Title", media: "text", inline: false },
+  // ── Script / alignment (their primary text field) ──
+  "generate-script": { prompt: "styleGuide", promptLabel: "Style guide", media: "text", inline: false },
+  "forced-alignment": { prompt: "transcript", promptLabel: "Transcript", media: "audio", inline: false },
+  // Video Analysis — its focus hint is the editable prompt (renders a JSON scene
+  // table, not a media preview → no inline editor).
+  "video-analysis": { prompt: "analysisFocus", promptLabel: "Analysis focus", media: "video", inline: false },
+}
+
+/** The prompt-field spec for a node type, or undefined if it has none. */
+export function getPromptFields(nodeType: string | undefined): PromptFieldSpec | undefined {
+  return nodeType ? NODE_PROMPT_FIELDS[nodeType] : undefined
+}
+
+/** True when this node type has a registered, quick-editable prompt field. */
+export function nodeHasPromptField(nodeType: string | undefined): boolean {
+  return getPromptFields(nodeType) !== undefined
+}
+
+/** Snippet modality for a node type (drives the snippet pool), or undefined
+ *  when the node has no prompt field. */
+export function getSnippetMedia(nodeType: string | undefined): SnippetMedia | undefined {
+  return getPromptFields(nodeType)?.media
+}
+
+/** True when this node type renders the inline on-node prompt editor — the
+ *  media-preview nodes (image/video/audio result body). Single source for
+ *  BaseNode's centralized `InlineNodePrompt` rendering and the gold nodes'
+ *  `showInline` derivation (`useInlinePromptActive`). */
+export function nodeHasInlinePrompt(nodeType: string | undefined): boolean {
+  return getPromptFields(nodeType)?.inline === true
+}
+
+/** True when the node type carries `promptPrefix` / `promptSuffix` — every
+ *  registered prompt node except explicit opt-outs (`affixes: false`). The single
+ *  predicate the config panel, Final view, `/v1/nodes` registry, totality tests
+ *  and docs tooling all gate on. */
+export function nodeSupportsPromptAffixes(nodeType: string | undefined): boolean {
+  const spec = getPromptFields(nodeType)
+  return spec !== undefined && spec.affixes !== false
+}
+
+/**
+ * Where the RUN-TIME prompt lives when it differs from the editor's prompt
+ * field (spec §7). `generate-script`'s editable prompt is its `styleGuide`, but
+ * the run wraps the topic `prompt` with the affixes — so previewing the style
+ * guide must NOT show them.
+ */
+export const PROMPT_AFFIX_CORE_FIELD_OVERRIDES: Readonly<Record<string, string>> = { "generate-script": "prompt" }
+
+/** The data key whose value the run wraps with promptPrefix/promptSuffix, or
+ *  undefined when the node has no affixes. */
+export function promptAffixCoreField(nodeType: string | undefined): string | undefined {
+  if (!nodeSupportsPromptAffixes(nodeType)) return undefined
+  return PROMPT_AFFIX_CORE_FIELD_OVERRIDES[nodeType!] ?? getPromptFields(nodeType)!.prompt
+}
+
+/**
+ * True when a preview of `promptField` on this node must show the affixes —
+ * i.e. that key is what the run actually wraps. THE gate for the editor's Final
+ * view, so a sibling field (llm-chat's `systemPrompt`, generate-script's
+ * `styleGuide`) never renders a wrap the run doesn't perform.
+ *
+ * Two ways a key qualifies:
+ *  - it IS the core field ({@link promptAffixCoreField}), or
+ *  - it is a run-time FALLBACK candidate for the type
+ *    ({@link NODE_PROMPT_CANDIDATE_FIELDS}) — `computeNodePrompt` picks the
+ *    first present candidate and wraps THAT, so i2v's legacy `motionPrompt`
+ *    genuinely receives the affixes when `data.prompt` is empty.
+ *
+ * The two rules never collide: no override type declares candidates (guarded in
+ * `node-prompt-fields.test.ts`).
+ *
+ * `undefined` means "the node's primary prompt field" — the common call.
+ */
+export function promptFieldCarriesAffixes(nodeType: string | undefined, promptField: string | undefined): boolean {
+  const core = promptAffixCoreField(nodeType)
+  if (core === undefined) return false
+  if (promptField === undefined) return getPromptFields(nodeType)!.prompt === core
+  return promptField === core || (NODE_PROMPT_CANDIDATE_FIELDS[nodeType!] ?? []).includes(promptField)
+}
+
+/** The affix-capable node types, derived from the registry (never hand-listed). */
+export const PROMPT_AFFIX_NODE_TYPES: ReadonlySet<string> = new Set(
+  Object.entries(NODE_PROMPT_FIELDS).filter(([, s]) => s.affixes !== false).map(([t]) => t),
+)

package/src/picker-catalogs.ts

@@ -51,8 +51,22 @@ import { POST_PROCESS_EFFECTS } from "./post-process-effects.js"
 import { CAMERA_MOTIONS, CAMERA_MOTION_CATEGORY_LABELS, CAMERA_MOTION_CATEGORY_ORDER } from "./camera-motions.js"
 import { LENSES } from "./lens.js"
 import { CAMERA_FORMATS } from "./camera-format.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 {
+  TRANSITIONS,
+  TRANSITION_CATEGORY_LABELS,
+  TRANSITION_CATEGORY_ORDER,
+  TRANSITION_POSITIONS,
+  TRANSITION_DURATIONS,
+  TRANSITION_INTENSITIES,
+} from "./transitions.js"
+import {
+  CHARACTER_FX,
+  CHARACTER_FX_CATEGORY_LABELS,
+  CHARACTER_FX_CATEGORY_ORDER,
+  CHARACTER_FX_POSITIONS,
+  CHARACTER_FX_DURATIONS,
+  CHARACTER_FX_INTENSITIES,
+} from "./character-fx.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 } from "@nodaro/shared"
@@ -127,7 +141,10 @@ export interface PickerCatalog {
   readonly options?: readonly PickerOption[]
   /** multi-dim: the dimension keys (no single catalog to flatten). */
   readonly fields?: readonly string[]
-  /** multi-dim: one self-describing entry per dimension field, in `fields` order. */
+  /** Per-field option lists. Multi-dim catalogs always carry these, one per
+   *  `fields` entry in order; a single-dim catalog carries them when it has
+   *  secondary parameter fields beside its main picker (transition
+   *  position/duration/intensity). */
   readonly dimensions?: readonly PickerDimension[]
 }
 
@@ -447,7 +464,10 @@ const SINGLE_CATALOGS: readonly PickerCatalog[] = [
     catalogId: "composition-effects",
     kind: "single",
     valueField: "compositionEffect",
-    defaultValue: "bursting-through-frame",
+    // No default effect — composition effects are dramatic subject transforms,
+    // so an unset node injects nothing until the user picks one (matches the
+    // "unset folds nothing" behaviour every consumer already honours).
+    defaultValue: "none",
     options: toOptions(COMPOSITION_EFFECTS),
   },
   {
@@ -522,6 +542,17 @@ const SINGLE_CATALOGS: readonly PickerCatalog[] = [
     categoryOrder: TRANSITION_CATEGORY_ORDER,
     categoryLabels: TRANSITION_CATEGORY_LABELS,
     options: toOptions(TRANSITIONS, "category"),
+    // The node's three timing parameters, alongside the transition itself.
+    // `dimensions` on a single-dim catalog carries exactly what it says on a
+    // multi-dim one — extra value fields with their own option lists — so a
+    // consumer that only sends ids can offer Position/Duration/Intensity
+    // without composing the clauses itself. The rich picker UI still renders
+    // only `options`; these fields are secondary controls beside it.
+    dimensions: perFieldDims([
+      ["position", TRANSITION_POSITIONS],
+      ["duration", TRANSITION_DURATIONS],
+      ["intensity", TRANSITION_INTENSITIES],
+    ]),
   },
   {
     nodeType: "character-fx",
@@ -533,6 +564,16 @@ const SINGLE_CATALOGS: readonly PickerCatalog[] = [
     categoryOrder: CHARACTER_FX_CATEGORY_ORDER,
     categoryLabels: CHARACTER_FX_CATEGORY_LABELS,
     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 --------
@@ -816,10 +857,11 @@ export function summarizePickerCatalogs(): readonly PickerCatalogSummary[] {
     kind: c.kind,
     valueField: c.valueField,
     fields: c.fields,
+    // Every option the detail call will return, whichever kind — a single-dim
+    // catalog with secondary dimensions carries both.
     optionCount:
-      c.kind === "single"
-        ? (c.options?.length ?? 0)
-        : (c.dimensions?.reduce((n, d) => n + d.options.length, 0) ?? 0),
+      (c.options?.length ?? 0) +
+      (c.dimensions?.reduce((n, d) => n + d.options.length, 0) ?? 0),
   }))
 }
 
@@ -876,22 +918,29 @@ export function projectPickerCatalog(
     categoryLabels: c.categoryLabels,
     detail,
   }
+  const projectDims = (dims: readonly PickerDimension[]) =>
+    dims.map((d) => ({
+      field: d.field,
+      label: d.label,
+      options: d.options.map((o) => projectOption(o, detail)),
+    }))
+
   if (c.kind === "single") {
     let options = c.options ?? []
     if (opts.category) options = options.filter((o) => o.category === opts.category)
-    return { ...base, options: options.map((o) => projectOption(o, detail)) }
+    const projected = { ...base, options: options.map((o) => projectOption(o, detail)) }
+    // A single-dim catalog may still carry secondary parameter dimensions
+    // (transition's position/duration/intensity). They are additive — a
+    // consumer reading only `options` is unaffected — but dropping them here
+    // would hide the one thing an id-only client needs to offer those controls.
+    if (!c.dimensions) return projected
+    let dims = c.dimensions
+    if (opts.field) dims = dims.filter((d) => d.field === opts.field)
+    return { ...projected, dimensions: projectDims(dims) }
   }
   let dims = c.dimensions ?? []
   if (opts.field) dims = dims.filter((d) => d.field === opts.field)
-  return {
-    ...base,
-    fields: c.fields,
-    dimensions: dims.map((d) => ({
-      field: d.field,
-      label: d.label,
-      options: d.options.map((o) => projectOption(o, detail)),
-    })),
-  }
+  return { ...base, fields: c.fields, dimensions: projectDims(dims) }
 }
 
 /**

package/src/picker-wiring.ts

@@ -147,7 +147,8 @@ export const SINGLE_PICKER_WIRING: ReadonlyArray<SingleDimPickerWiring> = [
   { kind: "single", nodeType: "photo-genre", label: "Photo Genre", valueField: "photoGenre", defaultValue: "fashion-editorial", catalogId: "photo-genre", entries: mapCat(PHOTO_GENRES, "category"), groupOrder: PHOTO_GENRE_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: PHOTO_GENRE_CATEGORY_LABELS },
   { kind: "single", nodeType: "backdrop", label: "Backdrop", valueField: "backdrop", defaultValue: "white-seamless", catalogId: "backdrop", entries: mapCat(BACKDROPS, "category"), groupOrder: BACKDROP_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: BACKDROP_CATEGORY_LABELS },
   { kind: "single", nodeType: "render-quality", label: "Render Quality", valueField: "renderQuality", defaultValue: "raytracing", catalogId: "render-quality", entries: mapCat(RENDER_QUALITIES) },
-  { kind: "single", nodeType: "composition-effects", label: "Composition Effect", valueField: "compositionEffect", defaultValue: "bursting-through-frame", catalogId: "composition-effects", entries: mapCat(COMPOSITION_EFFECTS) },
+  // No default effect — see the note in picker-catalogs.ts.
+  { kind: "single", nodeType: "composition-effects", label: "Composition Effect", valueField: "compositionEffect", defaultValue: "none", catalogId: "composition-effects", entries: mapCat(COMPOSITION_EFFECTS) },
   { kind: "single", nodeType: "action-fx", label: "Action FX", valueField: "actionFx", defaultValue: "earthquake-tremor", catalogId: "action-fx", entries: mapCat(ACTION_FX, "category"), groupOrder: ACTION_FX_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: ACTION_FX_CATEGORY_LABELS as Record<string, string> },
   { kind: "single", nodeType: "loop-subject", label: "Loop Subject", valueField: "loopSubject", defaultValue: "tunnel", catalogId: "loop-subject", entries: mapCat(LOOP_SUBJECTS, "category"), groupOrder: LOOP_SUBJECT_CATEGORY_ORDER as ReadonlyArray<string>, groupLabels: LOOP_SUBJECT_CATEGORY_LABELS as Record<string, string> },
   { kind: "single", nodeType: "post-process-effects", label: "Post-Process Effect", valueField: "postProcess", defaultValue: "vignette-soft", catalogId: "post-process-effects", entries: mapCat(POST_PROCESS_EFFECTS) },

package/src/provider-prompt-doctrine.ts

@@ -73,7 +73,7 @@ precise subject → action details → scene/environment → lighting & color to
 - Transitions and camera terms on 2.5: state a transition's trigger point AND method in one sentence — "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] — 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 — put the most identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding — \`{image:1:person}\` resolves to "the person from @image_1" — 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 — put the most identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding — \`{image:1:person}\` resolves to "the person from @image_1" — 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 — \`{ref:<id>}\` / \`{ref:<id>:label}\` — 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' … '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 — 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.
@@ -177,7 +177,7 @@ precise subject → action details → scene/environment → lighting & color to
 - Nothing visual connected → text-to-video. A concrete aspect ratio is required (21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 — 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 — the platform substitutes the \`@image_N\` seat after numbering.)
 - Caps: 9 reference images; 3 reference videos, each 2-15s and ≤15s combined; 3 reference audio clips, ≤15s combined. Reference audio cannot be used alone — it must accompany an image or video reference.
 - Define each subject once, then reuse the label consistently ("the woman from @Image 1 … 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.

package/src/ref-binding.ts

@@ -0,0 +1,45 @@
+/**
+ * The reference-binding surface string — `@image_N` / `@video_N` / `@audio_N`
+ * — and the one identity sentence built on it. Split out of
+ * `video-reference-resolver.ts` so the id-addressed token resolver
+ * (`ref-id-tokens.ts`) can bind through the same arrows without a module
+ * cycle; the resolver re-exports both, so importers are unaffected.
+ */
+
+/**
+ * The SINGLE swap-point for the reference-binding surface-string (design D1/D7).
+ *
+ * Every place that renders an `@image_N`-style binding into a video prompt — the
+ * per-image subject phrasing, the bare ordinal in a "Use these characters" /
+ * pair-back bullet, and the opening/closing frame directive — MUST go through
+ * these five arrows. The default form is `@image_N`; if the D7 probe shows a
+ * provider prefers the legacy `Image N` form, flipping is editing ONLY these five
+ * arrows (`@image_${n}` → `Image ${n}`), nothing downstream.
+ *
+ * This IS the live swap-point: `resolveVideoReferenceCore` routes the per-image
+ * subject phrasing, the "Use these characters" / pair-back bullet ordinals, and
+ * the frame directive through these arrows, and `resolveReferenceTokens` resolves
+ * the body `{image:N}` tokens through `REF_BINDING[kind]` — so the five arrows
+ * are the ONLY emission sites for the binding surface string.
+ */
+/**
+ * The identity-reference binding sentence shared by the flat-image-list
+ * resolvers (gemini-omni, veo i2v): names the ordinal span as identities and
+ * says the two things a multimodal model needs to hear — match exactly, and
+ * these are not frames. One spelling; both resolvers ride it.
+ */
+export function identityRefsSentence(firstOrdinal: number, lastOrdinal: number): string {
+  return firstOrdinal === lastOrdinal
+    ? `${REF_BINDING.ordinal(firstOrdinal)} is an identity reference for this shot's subjects — 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 — match each subject's exact appearance; they are not frames.`
+}
+
+export const REF_BINDING = {
+  image: (label: string, n: number) => `the ${label} from @image_${n}`,
+  video: (label: string, n: number) => `the ${label} from @video_${n}`,
+  audio: (label: string, n: number) => `the ${label} from @audio_${n}`,
+  /** ordinal as it appears in a "Use these characters" bullet / pair-back */
+  ordinal: (n: number) => `@image_${n}`,
+  frame: (n: number, role: "opening" | "closing") =>
+    `Use @image_${n} as the ${role} (${role === "opening" ? "first" : "last"}) frame of the video.`,
+} as const

package/src/ref-id-tokens.ts

@@ -0,0 +1,112 @@
+/**
+ * `{ref:<id>}` / `{ref:<id>:<label>}` — id-addressed reference tokens.
+ *
+ * The API/Studio form of the positional `{image:N}` token: the client names a
+ * reference by its OWN `connectedReferences[].id` and the platform substitutes
+ * the `@image_N` seat after IT has done the numbering. Without it a client that
+ * wanted the binding inline had to mirror the numbering walk client-side — a
+ * duplicated rule that misbinds pictures the moment the walk changes.
+ *
+ * `resolveVideoReferenceCore` builds the `RefIdTokenContext` DURING its walk
+ * and calls `resolveRefIdTokens` before the `referenceOrder` reorder (so the
+ * binding follows the reference to its final seat); the video routes call it
+ * standalone on their no-image-reference early return (nothing seated, so
+ * every token degrades).
+ */
+
+import { REF_BINDING } from "./ref-binding.js"
+
+/** The label class of `REFERENCE_TOKEN_RE` (`{image:N:label}`), shared. */
+const REF_TOKEN_LABEL_RE = /^[a-zA-Z0-9_ -]+$/
+/** Cheap gate for the whole pass — a prompt without it is untouched. */
+const HAS_REF_ID_TOKEN_RE = /\{ref:/i
+/**
+ * One well-formed `{ref:…}` token: everything between `{ref:` and the next
+ * `}` that contains no brace. Greedy over a brace-free class, so the scan is
+ * LINEAR in the prompt length whatever the content — `prompt` is up to
+ * `PROMPT_HARD_CEILING` (30k) chars of caller-controlled text, so a lazy
+ * quantifier with a nested optional label group here would be a quadratic-time
+ * ReDoS surface. The id / label split happens in code (`splitLabel`), not in
+ * the regex. `ref` is case-insensitive; ids are not.
+ */
+const REF_ID_TOKEN_RE = /\{[rR][eE][fF]:([^{}]*)\}/g
+/**
+ * Last-resort net for a MALFORMED `{ref:` (a brace inside the id, or no
+ * closing `}`): drop the `{ref:` run up to the next whitespace or brace, so
+ * the prefix can never reach a model, without eating prose past the token.
+ */
+const MALFORMED_REF_ID_TOKEN_RE = /\{[rR][eE][fF]:[^\s{}]*\}?/g
+
+/** What `resolveRefIdTokens` resolves against — the numbering walk's output. */
+export interface RefIdTokenContext {
+  /** Reference id → the 1-based `@image_N` seat the walk gave it. */
+  readonly slotById: ReadonlyMap<string, number>
+  /** Reference id → display name, the degrade target of a token that cannot bind. */
+  readonly nameById: ReadonlyMap<string, string>
+  /**
+   * How many image references actually ship — the same range gate `{image:N}`
+   * uses. A seat past it (a capped-out or duplicate-URL ref) must not bind.
+   */
+  readonly imageCount: number
+}
+
+/**
+ * Split a token's content into `<id>` and an optional `<label>` at the LAST
+ * colon — only when the tail is a well-formed label. Ids are opaque and may
+ * themselves contain `:` (`slug:variant`) or `/` (a URL), so nothing before
+ * the last colon is ever interpreted.
+ */
+function splitLabel(content: string): { id: string; label?: string } {
+  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 }
+}
+
+/**
+ * Rewrite id-addressed reference tokens into the `@image_N` binding of the
+ * reference the caller sent under that id.
+ *
+ * Ids are matched by IDENTITY against the known ids (seated or named), never
+ * parsed by character class: the whole content is tried as an id first (the
+ * longest reading — an id may itself end in something label-shaped), then
+ * `<id>:<label>` split at the last colon, then the token is unknown. The label
+ * class is the one `REFERENCE_TOKEN_RE` uses. An id containing `{`, `}`, an
+ * `@name:N` mention or a `{image:N}` token is unsupported (the mention pass
+ * runs first and would rewrite it; a brace ends the token).
+ *
+ * Per token:
+ *   - id seated in range → `REF_BINDING.image(label, N)` when labeled, else the
+ *     bare `REF_BINDING.ordinal(N)` — exactly what `{image:N[:label]}` emits.
+ *   - otherwise (unknown id, ref skipped by the walk, capped out, or no image
+ *     references at all) → the label if given, else the ref's display name if
+ *     the id is known, else "". A token never ships raw — a malformed one is
+ *     dropped by the last-resort net.
+ *
+ * No whitespace tidy here: every caller runs `resolveReferenceTokens` after
+ * this (the core does at every return), and that collapses the gap a dropped
+ * token leaves. Returns the input untouched when it carries no `{ref:` at all.
+ */
+export function resolveRefIdTokens(
+  prompt: string | undefined,
+  ctx: RefIdTokenContext,
+): string | undefined {
+  if (!prompt || !HAS_REF_ID_TOKEN_RE.test(prompt)) return prompt
+  const known = (id: string): boolean => id.length > 0 && (ctx.slotById.has(id) || ctx.nameById.has(id))
+  const bind = (id: string, label: string | undefined): string => {
+    const slot = ctx.slotById.get(id)
+    if (slot !== undefined && 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: string) => {
+      if (known(content)) return bind(content, undefined)
+      const { id, label } = splitLabel(content)
+      if (known(id)) return bind(id, label)
+      return label ?? ""
+    })
+    .replace(MALFORMED_REF_ID_TOKEN_RE, "")
+}

package/src/resolve-prompt.ts

@@ -1,4 +1,4 @@
-import { resolveNodeRefs } from "@nodaro/shared"
+import { resolveNodeRefs, readPromptAffixes, type PromptAffixes } from "@nodaro/shared"
 import { SOCIAL_POST_NODE_TYPES } from "@nodaro/shared"
 
 export interface ResolvePromptArgs {
@@ -13,16 +13,71 @@ export interface ResolvePromptArgs {
    *  Off/undefined = exact legacy precedence (override > typed > wired) for every
    *  other node type. */
   appendWired?: boolean
+  /** Pre/post text wrapped around WHICHEVER core precedence produced (override,
+   *  typed, wired, or the appendWired combination). Applied last. */
+  affixes?: PromptAffixes
 }
 const present = (s?: string): s is string => typeof s === "string" && s.trim().length > 0
 const rr = (s: string, m: ReadonlyMap<string, string>) => (m.size > 0 ? resolveNodeRefs(s, m) : s)
 
+// ---------------------------------------------------------------------------
+// Prompt affixes (pre/post text) — see docs/prompt-pre-post-text.md (join rule, empty-core, no-op guarantee)
+// ---------------------------------------------------------------------------
+
+const GLUE_PUNCTUATION = new Set([",", ".", ";", ":", "!", "?", ")"])
+
+/** The ONE join rule between two non-blank prompt parts: a single space unless
+ *  the boundary already has whitespace on either side or the right part opens
+ *  with sentence punctuation. Shared by `joinPromptParts` and the editor's
+ *  Final-view segment builder so preview and run agree byte-for-byte. */
+export function promptPartSeparator(left: string, right: string): "" | " " {
+  if (left.length === 0 || right.length === 0) return ""
+  if (/\s$/.test(left) || /^\s/.test(right)) return ""
+  if (GLUE_PUNCTUATION.has(right[0])) return ""
+  return " "
+}
+
+/** Join prompt parts with `promptPartSeparator`; blank parts are dropped,
+ *  non-blank parts are used verbatim (no trimming). */
+export function joinPromptParts(parts: ReadonlyArray<string | undefined>): string {
+  let out = ""
+  for (const part of parts) {
+    if (!present(part)) continue
+    out = out.length === 0 ? part : out + promptPartSeparator(out, part) + part
+  }
+  return out
+}
+
+/**
+ * Wrap `core` with the node's pre/post text. `{Label}` refs are resolved in the
+ * AFFIXES only — the core arrives exactly as the caller's precedence produced it.
+ * NO-OP GUARANTEE: with no non-blank affix the core is returned unchanged (same
+ * reference) — every existing workflow stays byte-identical.
+ * EMPTY CORE: a blank core with affixes yields the joined affixes alone.
+ */
+export function applyPromptAffixes(core: string, affixes: PromptAffixes | undefined, refMap: ReadonlyMap<string, string>): string
+export function applyPromptAffixes(core: string | undefined, affixes: PromptAffixes | undefined, refMap: ReadonlyMap<string, string>): string | undefined
+export function applyPromptAffixes(
+  core: string | undefined,
+  affixes: PromptAffixes | undefined,
+  refMap: ReadonlyMap<string, string>,
+): string | undefined {
+  const prefix = present(affixes?.prefix) ? rr(affixes!.prefix!, refMap) : undefined
+  const suffix = present(affixes?.suffix) ? rr(affixes!.suffix!, refMap) : undefined
+  if (prefix === undefined && suffix === undefined) return core
+  return joinPromptParts([prefix, core, suffix])
+}
+
 /** SINGLE SOURCE OF TRUTH for prompt precedence across both DAG engines:
  *  override (list fan-out) > first present typed candidate > wired > "".
  *  "present" = non-empty after trim. {Label} refs are resolved on the chosen
  *  branch via the shared resolveNodeRefs. With `appendWired`, the chosen base
- *  AND the wired value are both emitted (joined ". "). */
-export function resolvePrompt({ override, typed = [], wired, refMap, appendWired }: ResolvePromptArgs): string {
+ *  AND the wired value are both emitted (joined ". "). Affixes wrap the result. */
+export function resolvePrompt({ override, typed = [], wired, refMap, appendWired, affixes }: ResolvePromptArgs): string {
+  return applyPromptAffixes(resolveCore({ override, typed, wired, refMap, appendWired }), affixes, refMap)
+}
+
+function resolveCore({ override, typed = [], wired, refMap, appendWired }: Omit<ResolvePromptArgs, "affixes">): string {
   // appendWired: a connected prompt APPENDS to the TYPED base. An `override`
   // (list fan-out item) still fully REPLACES — it never receives a wired append,
   // so per-item fan-out prompts are unchanged.
@@ -110,7 +165,7 @@ export function computeNodePrompt(
     const fields = NODE_PROMPT_CANDIDATE_FIELDS[nodeType] ?? ["prompt"]
     typed = fields.map((f) => data[f] as string | undefined)
   }
-  return resolvePrompt({ override, typed, wired, refMap, appendWired })
+  return resolvePrompt({ override, typed, wired, refMap, appendWired, affixes: readPromptAffixes(data) })
 }
 
 export interface LlmChatFieldArgs {
@@ -125,7 +180,7 @@ export function computeLlmChatFields(
   { override, wiredUserInput, wiredSystemPrompt, refMap }: LlmChatFieldArgs,
 ): { userInput: string; systemPrompt: string } {
   return {
-    userInput: resolvePrompt({ override, typed: [data.userInput as string | undefined], wired: wiredUserInput, refMap }),
+    userInput: resolvePrompt({ override, typed: [data.userInput as string | undefined], wired: wiredUserInput, refMap, affixes: readPromptAffixes(data) }),
     systemPrompt: resolvePrompt({ typed: [data.systemPrompt as string | undefined], wired: wiredSystemPrompt, refMap }),
   }
 }