@nodaro/prompts 1.8.0 → 1.9.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,7 +51,14 @@ 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 {
+  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 } 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"
@@ -127,7 +134,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 +457,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 +535,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",
@@ -816,10 +840,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 +901,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

@@ -10,6 +10,10 @@
  *   Seedance 2.0:
  *   - Official BytePlus ModelArk "Dreamina Seedance 2.0 series prompt guide"
  *     https://docs.byteplus.com/en/docs/ModelArk/2222480
+ *   - Official BytePlus ModelArk "Dreamina Seedance 2.5 prompt guide"
+ *     https://docs.byteplus.com/en/docs/ModelArk/2607689 — its "Differences
+ *     from Seedance 2.0" section is the authority for every 2.0-vs-2.5 split
+ *     below (timestamps, multi-view references, aspect ratios, MOV output).
  *   - Official launch post https://seed.bytedance.com/en/blog/official-launch-of-seedance-2-0
  *   - KIE API docs https://docs.kie.ai/market/bytedance/seedance-2
  *   Kling:
@@ -41,19 +45,19 @@ const SEEDANCE_2_DOCTRINE: ProviderPromptDoctrine = {
   providers: ["seedance-2", "seedance-2-fast", "seedance-2-mini", "seedance-2-5"],
   heading: "Seedance 2 (seedance-2, seedance-2-fast, seedance-2-mini, seedance-2-5)",
   tips: [
-    "Storyboard complex videos as 'Shot 1: … Shot 2: …' WITHOUT timestamps — timed shots like '(0-3s)' are officially unstable and can break generation.",
+    "Storyboard as 'Shot 1: … Shot 2: …'. The 2.0 SKUs ignore timestamps and '(0-3s)' shots are officially unstable there; seedance-2-5 honours integer-second timestamps ('0-3s: …', 'at the 5-second mark').",
     "One camera movement per shot; describe actions per body part with degree ('slowly raises a hand'); express emotion as physical detail, never abstract words.",
     "Native multi-track audio — cue it inline: （background music）, <sound effects>, and quoted dialogue.",
-    "References go by ordinal (@Image 1, Video 2) in attachment order; earlier = higher priority. Identity = ONE headshot + ONE full-body (multi-view sheets cause ID drift). 4-5 assets total beats maxing the 9/3/3 caps.",
+    "References go by ordinal (@Image 1, Video 2) in attachment order; earlier = higher priority. Identity = ONE headshot + ONE full-body (multi-view sheets drift on 2.0; 2.5 accepts them). 4-5 assets beats maxing 9/3/3.",
     "No negative-prompt parameter — put constraints in the prompt: 'keep it subtitle-free, do not generate a watermark, do not generate a logo'.",
-    "seedance-2-5 only: one shot runs to 30s (the 2.0 SKUs stop at 15s), so storyboard a whole beat instead of planning a stitch. Ref caps are wider (30/10/10), but 4-5 assets still gives the best identity fidelity.",
+    "seedance-2-5 only: one shot runs to 30s (2.0 stops at 15s) — storyboard a whole beat, not a stitch; timestamps work (gap-free, 1s units, don't overpack); refs 30/10/10 but 4-5 assets still gives the best identity.",
     "Auto-path formula: Subject → Action → Environment → Camera → Style → Constraints in 60-100 words; ONE camera instruction (chain with 'then'); separate camera motion from subject motion; always add one lighting phrase.",
   ],
   doctrine: `Prompt structure (front-load what matters most):
 precise subject → action details → scene/environment → lighting & color tone → camera movement → visual style → image quality → constraints.
 
 **Shots & pacing**
-- Storyboard complex videos as "Shot 1: … Shot 2: … Shot 3: …" in event order. Do NOT attach timestamps (e.g. "(0-3s)") — precise-timing support is officially unstable and forcing durations can break generation; let the model pace naturally.
+- Storyboard complex videos as "Shot 1: … Shot 2: … Shot 3: …" in event order. TIMESTAMPS ARE VERSION-SPLIT: the 2.0 SKUs (seedance-2 / -fast / -mini) respond to shot numbers only — do NOT attach timestamps there (e.g. "(0-3s)"; precise timing is officially unstable on 2.0 and forcing durations can break generation, so let the model pace). seedance-2-5 honours integer-second timestamps — the forms and limits are under "Generation differences" below.
 - Per shot cover, in order: camera move or transition, subject action + expression, spatial/position change, audio for that shot.
 - One camera movement type per shot — never ask for push + pan + orbit at once (image instability).
 - Prefer slow, gentle, continuous movements over high-burst action (sprints, big jumps, violent rolls morph). Describe actions per body part with quantified degree: "slowly raises a hand", "pushes hard off the ground". Chain actions with inertia: "uses the momentum of the turn to naturally raise an arm".
@@ -64,11 +68,14 @@ precise subject → action details → scene/environment → lighting & color to
 - 2.5 also takes far more reference material (30 images / 10 videos / 10 audio vs 9/3/3). Treat that as room for COVERAGE — more distinct characters, locations and props in one shot — not as licence to pile refs onto one identity. The "ONE headshot + ONE full-body, 4-5 assets total" rule above still produces the best likeness on 2.5.
 - 2.5 renders at 480p/720p/1080p (1080p since 2026-08-17): there is no 4K tier, so route a job that needs 4K to seedance-2 (which has it) or upscale afterwards.
 - With a start frame, 2.5 always derives the output aspect from that frame — an explicit aspect ratio is rejected outright, so compose the frame at the ratio you want.
+- Timestamps (official 2.5 guide, "Differences from Seedance 2.0"): 2.0 does not respond to them; 2.5 supports integer-second timestamps in three forms — gap-free intervals ("0-3s: … 3-7s: … 7-15s: …" or "[1s-4s] … [4s-8s] …"; never leave a hole like "0-3s … 5-6s"), time-point control ("At the 5-second mark, …"), and relative time ("After 3 seconds, …"). Use 1-second units. Too little content in a range lets the model improvise; too much packs in extra cuts or drops beats — budget the seconds. Never use timestamps to drive high-frequency actions ("shake three times per second").
+- Multi-view subject images: not recommended on 2.0 (the views read as separate people → twins); supported on 2.5. ONE headshot + ONE full-body remains the safest default on both.
+- 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.)
 - 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. Do NOT attach multi-view/three-view character sheets — the model reads the views as separate people, causing identity drift and twin duplicates.
+- 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.
 - Editing/extension instructions name clips directly: "Extend Video 1 backward…", "Remove the chair from Video 1". Saying "reference Video 1" flips the model into reference mode and breaks the edit. Track completion: "Video 1 + [transition description] + followed by Video 2" (≤3 clips, ≤15s total).
 

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 }),
   }
 }

package/src/transitions.ts

@@ -42,9 +42,23 @@ export interface Transition {
   readonly term?: string
 }
 
-export type TransitionPosition = "auto" | "start" | "middle" | "end" | "full"
-export type TransitionDuration = "auto" | "instant" | "short" | "medium" | "long"
-export type TransitionIntensity = "auto" | "subtle" | "natural" | "dynamic" | "crazy"
+/**
+ * The three timing scales, each derived from the catalog that defines it (see
+ * `TRANSITION_POSITIONS` and friends below).
+ *
+ * The direction matters. These used to be hand-written unions with the clause
+ * tables written out separately beside them, so the two could disagree: add a
+ * step to the union, forget the clause, and the composer indexed a missing key
+ * — pushing `undefined` into the parts list, which `join(", ")` renders as a
+ * dangling separator on a prompt that then ships to a provider with the user's
+ * chosen parameter silently dropped. Deriving the union FROM the catalog makes
+ * that unrepresentable: one array is the source of the type, the option list
+ * the API serves, and the clause table, so a new step reaches all three or
+ * none. The exact id sets are pinned by `transition-timing-catalogs.test.ts`.
+ */
+export type TransitionPosition = (typeof TRANSITION_POSITIONS)[number]["id"]
+export type TransitionDuration = (typeof TRANSITION_DURATIONS)[number]["id"]
+export type TransitionIntensity = (typeof TRANSITION_INTENSITIES)[number]["id"]
 
 export interface TransitionTiming {
   position?: TransitionPosition
@@ -303,27 +317,73 @@ export const TRANSITION_IDS: ReadonlyArray<string> = TRANSITIONS.map((t) => t.id
 // Graph-aware composer — start/end input handles + timing fields + multi-pick
 // ---------------------------------------------------------------------------
 
-const POSITION_CLAUSES: Record<Exclude<TransitionPosition, "auto">, string> = {
-  start:  "the transition occurs at the opening of the clip",
-  middle: "the transition occurs in the middle of the clip",
-  end:    "the transition occurs at the end of the clip",
-  full:   "the transition spans the entire clip",
+/**
+ * The transition node's three timing parameters, as catalogs.
+ *
+ * These are graded scales, not free numbers — the same shape as
+ * `exposure-settings`' aperture or `temporal`'s speed — so a consumer that can
+ * only send ids (Studio, the SDK, MCP) can offer them without composing prompt
+ * text of its own. `auto` is the no-op head of each scale: an empty
+ * `promptHint`, so an unset parameter contributes nothing and the model is left
+ * to decide, exactly as before these were enumerable.
+ *
+ * `POSITION_CLAUSES` / `DURATION_CLAUSES` / `INTENSITY_CLAUSES` below are
+ * DERIVED from these arrays, so the clause the composer injects and the hint
+ * the catalog advertises are the same string by construction and cannot drift.
+ */
+export interface TransitionTimingOption {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  readonly promptHint: string
+  readonly term?: string
 }
 
-const DURATION_CLAUSES: Record<Exclude<TransitionDuration, "auto">, string> = {
-  instant: "occurring instantaneously",
-  short:   "lasting approximately 1 second",
-  medium:  "lasting approximately 2 seconds",
-  long:    "lasting approximately 3 seconds",
-}
+export const TRANSITION_POSITIONS = [
+  { id: "auto",   label: "Auto",   description: "Let the model place it",        promptHint: "", term: "" },
+  { id: "start",  label: "Start",  description: "At the opening of the clip",    promptHint: "the transition occurs at the opening of the clip", term: "at the opening of the clip" },
+  { id: "middle", label: "Middle", description: "In the middle of the clip",     promptHint: "the transition occurs in the middle of the clip", term: "mid-clip" },
+  { id: "end",    label: "End",    description: "At the end of the clip",        promptHint: "the transition occurs at the end of the clip", term: "at the end of the clip" },
+  { id: "full",   label: "Full",   description: "Spans the entire clip",         promptHint: "the transition spans the entire clip", term: "across the whole clip" },
+] as const satisfies ReadonlyArray<TransitionTimingOption>
+
+export const TRANSITION_DURATIONS = [
+  { id: "auto",    label: "Auto",    description: "Let the model time it",       promptHint: "", term: "" },
+  { id: "instant", label: "Instant", description: "No perceptible duration",     promptHint: "occurring instantaneously", term: "instantaneous" },
+  { id: "short",   label: "Short (~1s)",   description: "Approximately 1 second",  promptHint: "lasting approximately 1 second", term: "about 1 second" },
+  { id: "medium",  label: "Medium (~2s)",  description: "Approximately 2 seconds", promptHint: "lasting approximately 2 seconds", term: "about 2 seconds" },
+  { id: "long",    label: "Long (~3s)",    description: "Approximately 3 seconds", promptHint: "lasting approximately 3 seconds", term: "about 3 seconds" },
+] as const satisfies ReadonlyArray<TransitionTimingOption>
+
+export const TRANSITION_INTENSITIES = [
+  { id: "auto",    label: "Auto",    description: "Let the model judge it",      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" },
+] as const satisfies ReadonlyArray<TransitionTimingOption>
 
-const INTENSITY_CLAUSES: Record<Exclude<TransitionIntensity, "auto">, string> = {
-  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",
+/**
+ * Index a timing catalog into the `Record<value, clause>` the composer reads.
+ *
+ * The key type is derived from the SAME array, so the record is total over the
+ * catalog by construction. That matters: the composer indexes these records
+ * without a fallback, and a missing key would push `undefined` into the parts
+ * list, which `join(", ")` renders as a dangling separator — a malformed prompt
+ * shipped to a provider with the user's chosen parameter silently dropped.
+ */
+function clausesOf<T extends TransitionTimingOption>(
+  options: ReadonlyArray<T>,
+): Record<Exclude<T["id"], "auto">, string> {
+  return Object.fromEntries(
+    options.filter((o) => o.id !== "auto").map((o) => [o.id, o.promptHint]),
+  ) as Record<Exclude<T["id"], "auto">, string>
 }
 
+const POSITION_CLAUSES = clausesOf(TRANSITION_POSITIONS)
+const DURATION_CLAUSES = clausesOf(TRANSITION_DURATIONS)
+const INTENSITY_CLAUSES = clausesOf(TRANSITION_INTENSITIES)
+
 /**
  * Compose a structural prompt-hint sentence from a transition id (or array
  * of 1-2 ids for multi-pick) plus optional start-state/end-state hints