@nodaro/prompts 1.8.1 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "description": "Nodaro's prompt-engineering layer — person/picker catalogs with prompt hints, identity-lock clauses, entity prompt builders, brand presets, and prompt/reference assembly shared by the Nodaro platform and SDK.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
@@ -20,7 +20,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@nodaro/shared": "^2.12.1"
+    "@nodaro/shared": "^2.14.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

package/src/__tests__/character-fx-timing-catalogs.test.ts

@@ -0,0 +1,240 @@
+/**
+ * The character-fx node's three timing parameters (position / duration /
+ * intensity) are enumerable catalogs, not free values, so a consumer that can
+ * only send ids — Studio, the SDK, MCP — can offer them without composing any
+ * prompt text of its own. This is the character-fx twin of
+ * `transition-timing-catalogs.test.ts`; the two nodes share ids and shape but
+ * NOT wording, and nothing here may couple them.
+ *
+ * Three properties matter, and each is easy to lose silently:
+ *
+ *  1. The clause the composer INJECTS and the hint the catalog ADVERTISES are
+ *     the same string. They are derived from one array in `character-fx.ts`,
+ *     and these tests fail the moment someone re-introduces a second copy.
+ *  2. The prompt text is exactly what shipped before it was enumerable. The
+ *     parameter-hint golden covers only three of the twelve clauses, so the
+ *     twelve literals are pinned here: a change is a deliberate diff, never a
+ *     side effect.
+ *  3. The dimensions survive the wire projection — `projectAllCatalogs()` is
+ *     what an id-only client actually reads, and a green in-memory catalog
+ *     proves nothing about it.
+ */
+import { describe, it, expect } from "vitest"
+import {
+  CHARACTER_FX_POSITIONS,
+  CHARACTER_FX_DURATIONS,
+  CHARACTER_FX_INTENSITIES,
+  composeCharacterFxHintFromConnections,
+} from "../character-fx.js"
+import { TRANSITION_POSITIONS, TRANSITION_DURATIONS } from "../transitions.js"
+import { PICKER_CATALOGS, projectPickerCatalog, projectAllCatalogs } from "../picker-catalogs.js"
+
+const DIMENSIONS = [
+  ["position", CHARACTER_FX_POSITIONS],
+  ["duration", CHARACTER_FX_DURATIONS],
+  ["intensity", CHARACTER_FX_INTENSITIES],
+] as const
+
+const characterFxCatalog = PICKER_CATALOGS.find((c) => c.nodeType === "character-fx")!
+
+describe("character-fx timing catalogs", () => {
+  // The `CharacterFxPosition` / `Duration` / `Intensity` unions are DERIVED
+  // from these arrays, so nothing at the type level can pin the values
+  // themselves. These are the values the editor dropdowns, the node data, and
+  // every stored workflow already use: changing one is a data migration, not a
+  // rename.
+  it("spells exactly the ids every stored workflow already uses", () => {
+    expect(CHARACTER_FX_POSITIONS.map((o) => o.id)).toEqual([
+      "auto", "start", "middle", "end", "full",
+    ])
+    expect(CHARACTER_FX_DURATIONS.map((o) => o.id)).toEqual([
+      "auto", "instant", "short", "medium", "long",
+    ])
+    expect(CHARACTER_FX_INTENSITIES.map((o) => o.id)).toEqual([
+      "auto", "subtle", "natural", "dynamic", "crazy",
+    ])
+  })
+
+  it("injects exactly the clauses that shipped before the scales were enumerable", () => {
+    // Byte-for-byte the literals the hand-written clause tables carried. This
+    // task was exposure, not authoring: if any of these move, that is a prompt
+    // change for real users and must be its own deliberate diff.
+    expect(CHARACTER_FX_POSITIONS.map((o) => o.promptHint)).toEqual([
+      "",
+      "the effect occurs at the opening of the clip",
+      "the effect occurs in the middle of the clip",
+      "the effect occurs at the end of the clip",
+      "the effect persists for the entire clip",
+    ])
+    expect(CHARACTER_FX_DURATIONS.map((o) => o.promptHint)).toEqual([
+      "",
+      "manifesting instantaneously",
+      "manifesting over approximately 1 second",
+      "manifesting over approximately 2 seconds",
+      "manifesting over approximately 3 seconds",
+    ])
+    expect(CHARACTER_FX_INTENSITIES.map((o) => o.promptHint)).toEqual([
+      "",
+      "with subtle restrained energy and minimal flourish",
+      "with natural unhurried timing",
+      "with dynamic energy and assertive flourish",
+      "with extreme exaggerated energy, wild flourishes, and dramatic distortion",
+    ])
+  })
+
+  it("keeps its own wording — an effect manifests and persists, a transition occurs and spans", () => {
+    // The one constraint that matters most: these scales must never be unified
+    // with the transition ones. Position and duration are worded differently
+    // on purpose, so pointing character-fx at the transition rows fails here.
+    // Intensity is deliberately NOT compared: its three clauses happen to be
+    // identical today, and that is a coincidence, not a shared definition.
+    expect(CHARACTER_FX_POSITIONS.map((o) => o.promptHint)).not.toEqual(
+      TRANSITION_POSITIONS.map((o) => o.promptHint),
+    )
+    expect(CHARACTER_FX_DURATIONS.map((o) => o.promptHint)).not.toEqual(
+      TRANSITION_DURATIONS.map((o) => o.promptHint),
+    )
+  })
+
+  it("carries the timing precision users read off the dropdown", () => {
+    // The editor renders straight from here (its own catalogs, not the
+    // transition ones), so this is the one place the numbers live.
+    expect(CHARACTER_FX_DURATIONS.map((o) => o.label)).toEqual([
+      "Auto", "Instant", "Short (~1s)", "Medium (~2s)", "Long (~3s)",
+    ])
+  })
+
+  it("gives every injecting step a compact term, so compact mode never drops it", () => {
+    // `catalog-terms.test.ts` enforces this globally; pinned here too because
+    // the platform composes timing from `promptHint` in BOTH hint modes, so a
+    // broken `term` would only ever surface on an external compact client.
+    for (const [field, options] of DIMENSIONS) {
+      for (const o of options.slice(1)) {
+        expect(o.term, `${field}/${o.id} needs a compact term`).toBeTruthy()
+      }
+      expect(options[0]!.term, `${field}/auto injects nothing`).toBe("")
+    }
+  })
+
+  it("derives a clause for every non-auto step, so the composer can't index a hole", () => {
+    // The regression this guards: a step present in the catalog but missing
+    // from the clause table made `parts.push(undefined)` render as a dangling
+    // ", " on a prompt that shipped to the provider. Walks the ARRAYS, not a
+    // hardcoded id list, so a step added to a catalog is exercised here too.
+    for (const [field, options] of DIMENSIONS) {
+      for (const o of options.slice(1)) {
+        const composed = composeCharacterFxHintFromConnections("werewolf", [], {
+          [field]: o.id,
+        } as never)
+        expect(composed, `${field}/${o.id} composed a dangling separator`).not.toMatch(/,\s*$/)
+        expect(composed, `${field}/${o.id}`).not.toContain("undefined")
+      }
+    }
+  })
+
+  it("every scale leads with a no-op `auto` that injects nothing", () => {
+    for (const [field, options] of DIMENSIONS) {
+      expect(options[0]!.id, `${field} must lead with auto`).toBe("auto")
+      expect(options[0]!.promptHint, `${field}/auto must inject nothing`).toBe("")
+      // Every other step must actually carry a clause.
+      for (const o of options.slice(1)) {
+        expect(o.promptHint, `${field}/${o.id} needs a promptHint`).not.toBe("")
+      }
+    }
+  })
+
+  it("the composed clause is the catalog's own promptHint, verbatim", () => {
+    // One source of truth: if the composer ever grows a private copy of these
+    // strings, the composed sentence stops containing the advertised hint.
+    for (const o of CHARACTER_FX_POSITIONS.slice(1)) {
+      const composed = composeCharacterFxHintFromConnections("werewolf", [], { position: o.id as never })
+      expect(composed, `position/${o.id}`).toContain(o.promptHint)
+    }
+    for (const o of CHARACTER_FX_DURATIONS.slice(1)) {
+      const composed = composeCharacterFxHintFromConnections("werewolf", [], { duration: o.id as never })
+      expect(composed, `duration/${o.id}`).toContain(o.promptHint)
+    }
+    for (const o of CHARACTER_FX_INTENSITIES.slice(1)) {
+      const composed = composeCharacterFxHintFromConnections("werewolf", [], { intensity: o.id as never })
+      expect(composed, `intensity/${o.id}`).toContain(o.promptHint)
+    }
+  })
+
+  it("the clauses are emitted identically in compact hint mode", () => {
+    // Timing is composed from `promptHint` in BOTH modes — only the effect's
+    // base fragment swaps to its term. Pinned so a compact-mode refactor cannot
+    // quietly start reading `term` for the timing rows.
+    for (const [field, options] of DIMENSIONS) {
+      for (const o of options.slice(1)) {
+        const compact = composeCharacterFxHintFromConnections("werewolf", [], {
+          [field]: o.id,
+        } as never, "compact")
+        expect(compact, `${field}/${o.id} in compact mode`).toContain(o.promptHint)
+      }
+    }
+  })
+
+  it("`auto` adds nothing to the composed sentence", () => {
+    const bare = composeCharacterFxHintFromConnections("werewolf", [])
+    const allAuto = composeCharacterFxHintFromConnections("werewolf", [], { position: "auto", duration: "auto", intensity: "auto" })
+    expect(allAuto).toBe(bare)
+  })
+
+  it("exposes the three dimensions on the character-fx catalog", () => {
+    expect(characterFxCatalog.kind).toBe("single")
+    expect(characterFxCatalog.dimensions?.map((d) => d.field)).toEqual([
+      "position",
+      "duration",
+      "intensity",
+    ])
+  })
+
+  it("keeps the dimensions through the wire projection", () => {
+    const wire = projectPickerCatalog(characterFxCatalog, { detail: "full" })
+
+    // The 57-option effect list is untouched by the addition.
+    expect(wire.options?.length).toBe(characterFxCatalog.options?.length)
+
+    expect(wire.dimensions).toHaveLength(3)
+    for (const [field, options] of DIMENSIONS) {
+      const dim = wire.dimensions?.find((d) => d.field === field)
+      expect(dim, `${field} must reach the wire`).toBeDefined()
+      expect(dim!.options.map((o) => o.id)).toEqual(options.map((o) => o.id))
+      expect(dim!.options.map((o) => o.promptHint)).toEqual(options.map((o) => o.promptHint))
+    }
+  })
+
+  it("field filter narrows a single-dim catalog to one secondary dimension", () => {
+    const wire = projectPickerCatalog(characterFxCatalog, { field: "duration" })
+    expect(wire.options?.length).toBe(characterFxCatalog.options?.length)
+    expect(wire.dimensions?.map((d) => d.field)).toEqual(["duration"])
+  })
+
+  describe("projectAllCatalogs — what an id-only client actually reads", () => {
+    // `GET /v1/catalogs` is built from this call. Both detail levels must carry
+    // the three dimensions with ids and labels; `full` must also carry the
+    // clause, and `compact` must carry the term so a thin client can inject
+    // without a second fetch.
+    for (const detail of ["compact", "full"] as const) {
+      it(`detail=${detail}: three dimensions with ids, labels${detail === "full" ? " and hints" : " and terms"}`, () => {
+        const wire = projectAllCatalogs({ detail }).find((c) => c.nodeType === "character-fx")!
+        expect(wire.detail).toBe(detail)
+        expect(wire.kind).toBe("single")
+        expect(wire.dimensions?.map((d) => d.field)).toEqual(["position", "duration", "intensity"])
+
+        for (const [field, options] of DIMENSIONS) {
+          const dim = wire.dimensions!.find((d) => d.field === field)!
+          expect(dim.label, `${field} label`).toBeTruthy()
+          expect(dim.options.map((o) => o.id)).toEqual(options.map((o) => o.id))
+          expect(dim.options.map((o) => o.label)).toEqual(options.map((o) => o.label))
+          expect(dim.options.map((o) => o.term)).toEqual(options.map((o) => o.term))
+          if (detail === "full") {
+            expect(dim.options.map((o) => o.promptHint)).toEqual(options.map((o) => o.promptHint))
+          } else {
+            for (const o of dim.options) expect(o, `${field}/${o.id} compact`).not.toHaveProperty("promptHint")
+          }
+        }
+      })
+    }
+  })
+})

package/src/__tests__/factory-presets.test.ts

@@ -3,8 +3,24 @@ import { FACTORY_PRESETS, getFactoryPresets, groupFactoryPresets } from "../fact
 import { extractPresetData, PRESET_APPLY_CLEAR_KEYS } from "@nodaro/shared"
 import { COMPOSER_PLAN_MAP, COMPOSER_PLAN_FIELDS } from "@nodaro/shared"
 import { STYLE_IDS } from "../index.js"
+import { joinPromptParts } from "../resolve-prompt.js"
+import { nodeSupportsPromptAffixes } from "../node-prompt-fields.js"
 import { IMAGE_GEN_PROVIDERS, MODIFY_IMAGE_PROVIDERS, VIDEO_GEN_PROVIDERS, VIDEO_TO_VIDEO_PROVIDERS, MUSIC_PROVIDERS, SUNO_MODELS, TTS_PROVIDERS, TEXT_TO_AUDIO_PROVIDERS, ALL_CAPTION_STYLES, COMBINE_TRANSITION_IDS, AUDIO_CROSSFADE_CURVE_IDS, aspectRatioOptionsByKind, durationsByMode, IMAGE_PROMPT_MAX, MODEL_CATALOG, NATIVE_NEGATIVE_VIDEO_PROVIDERS } from "@nodaro/shared"
 
+/**
+ * The text a preset ACTUALLY sends: a preset may ship its doctrine as pre/post
+ * text (`promptPrefix` / `promptSuffix`) with the `prompt` field left free for
+ * the user — see docs/prompt-pre-post-text.md. Every content guard below reads
+ * the ASSEMBLED prompt through this helper (same join rule the run uses) so a
+ * prompt→affix move can never silently drop a clause or blow a length cap.
+ */
+const effectivePrompt = (d: Record<string, unknown>) =>
+  joinPromptParts([
+    d.promptPrefix as string | undefined,
+    d.prompt as string | undefined,
+    d.promptSuffix as string | undefined,
+  ])
+
 describe("FACTORY_PRESETS", () => {
   it("has presets for generate-image", () => {
     expect(getFactoryPresets("generate-image").length).toBeGreaterThan(0)
@@ -74,7 +90,7 @@ describe("Seedance Director factory presets", () => {
     for (const p of pack) {
       const prompt = p.data.prompt as string
       expect(prompt).not.toMatch(/\(\s*\d+\s*[-–]\s*\d+\s*s\s*\)/i) // "(0-3s)" style
-      expect(prompt.length).toBeLessThanOrEqual(2000)
+      expect(effectivePrompt(p.data).length).toBeLessThanOrEqual(2000)
       expect(prompt).toContain("subtitle-free")
     }
   })
@@ -157,7 +173,7 @@ describe("generate-image factory preset data validity", () => {
 
   it("respects prompt (IMAGE_PROMPT_MAX) and negativePrompt (5000) length caps", () => {
     for (const p of presets) {
-      const prompt = (p.data.prompt as string | undefined) ?? ""
+      const prompt = effectivePrompt(p.data)
       const neg = (p.data.negativePrompt as string | undefined) ?? ""
       expect(prompt.length, `${p.id}: prompt exceeds cap`).toBeLessThanOrEqual(IMAGE_PROMPT_MAX)
       expect(neg.length, `${p.id}: negativePrompt exceeds 5000 chars`).toBeLessThanOrEqual(5000)
@@ -211,7 +227,7 @@ describe("generate-image factory preset data validity", () => {
     const boards = presets.filter((p) => p.group === "Reference Sheet")
     expect(boards.length).toBeGreaterThanOrEqual(11)
     for (const b of boards) {
-      expect(b.data.prompt as string, `${b.id}: missing the never-merge-panels clause`).toContain(
+      expect(effectivePrompt(b.data), `${b.id}: missing the never-merge-panels clause`).toContain(
         "never merging or omitting a panel",
       )
     }
@@ -239,7 +255,7 @@ describe("generate-image factory preset data validity", () => {
     const handmade = presets.filter((p) => p.group === "Handmade & Stop-Motion")
     expect(handmade.length).toBeGreaterThanOrEqual(6)
     for (const p of handmade) {
-      expect(p.data.prompt as string, `${p.id}: missing the NOT digital CG clause`).toContain("NOT digital CG")
+      expect(effectivePrompt(p.data), `${p.id}: missing the NOT digital CG clause`).toContain("NOT digital CG")
     }
   })
 
@@ -264,7 +280,7 @@ describe("generate-image factory preset data validity", () => {
   it("non-style-pinned generate-image prompts are substantive (no thin one-liners)", () => {
     for (const p of presets) {
       if (p.data.style !== undefined) continue // style field carries the look; short prompt is fine
-      const prompt = (p.data.prompt as string | undefined) ?? ""
+      const prompt = effectivePrompt(p.data)
       expect(prompt.trim().length, `${p.id}: prompt too thin (${prompt.length} chars)`).toBeGreaterThanOrEqual(40)
     }
   })
@@ -296,7 +312,7 @@ describe("modify-image factory preset data validity", () => {
 
   it("respects the prompt 2000-char cap", () => {
     for (const p of presets) {
-      const prompt = (p.data.prompt as string | undefined) ?? ""
+      const prompt = effectivePrompt(p.data)
       expect(prompt.length, `${p.id}: prompt exceeds 2000 chars`).toBeLessThanOrEqual(2000)
     }
   })
@@ -349,7 +365,7 @@ describe("generate-video factory preset data validity", () => {
 
   it("respects prompt/negativePrompt length caps (2500)", () => {
     for (const p of presets) {
-      expect(((p.data.prompt as string) ?? "").length, `${p.id}: prompt too long`).toBeLessThanOrEqual(2500)
+      expect(effectivePrompt(p.data).length, `${p.id}: prompt too long`).toBeLessThanOrEqual(2500)
       expect(((p.data.negativePrompt as string) ?? "").length, `${p.id}: negativePrompt too long`).toBeLessThanOrEqual(2500)
     }
   })
@@ -737,7 +753,7 @@ describe("video-to-video factory preset data validity", () => {
 
   it("respects prompt (5000) and negativePrompt (500) caps", () => {
     for (const p of presets) {
-      expect(((p.data.prompt as string) ?? "").length, `${p.id}: prompt > 5000`).toBeLessThanOrEqual(5000)
+      expect(effectivePrompt(p.data).length, `${p.id}: prompt > 5000`).toBeLessThanOrEqual(5000)
       expect(((p.data.negativePrompt as string) ?? "").length, `${p.id}: negativePrompt > 500`).toBeLessThanOrEqual(500)
     }
   })
@@ -1006,13 +1022,19 @@ describe("presets don't bake config-field values (framing) into the prompt", ()
   const ratioRe = new RegExp(`(^|[^0-9.])(${RATIO_TOKENS.map((t) => t.replace(/\./g, "\\.")).join("|")})([^0-9]|$)`)
 
   it("no factory preset prompt names an aspect ratio", () => {
+    // Checks all three prompt-bearing fields: a preset may ship its doctrine as
+    // pre/post text, and a ratio smuggled into an affix reaches the model just
+    // the same. The message names the offending field.
     const offenders: string[] = []
     for (const [, presets] of Object.entries(FACTORY_PRESETS)) {
       for (const p of presets) {
-        const prompt = (p.data as Record<string, unknown>).prompt
-        if (typeof prompt !== "string") continue
-        const m = prompt.match(ratioRe)
-        if (m) offenders.push(`${p.id} → "${m[2]}"`)
+        const d = p.data as Record<string, unknown>
+        for (const field of ["promptPrefix", "prompt", "promptSuffix"] as const) {
+          const text = d[field]
+          if (typeof text !== "string") continue
+          const m = text.match(ratioRe)
+          if (m) offenders.push(`${p.id}.${field} → "${m[2]}"`)
+        }
       }
     }
     expect(
@@ -1022,6 +1044,34 @@ describe("presets don't bake config-field values (framing) into the prompt", ()
   })
 })
 
+describe("factory preset pre/post text (promptPrefix / promptSuffix)", () => {
+  // A preset may ship its doctrine as pre/post text so the prompt field stays
+  // free for the user (docs/prompt-pre-post-text.md). Two invariants: the node
+  // type must actually support affixes — otherwise the text is dead data the
+  // run never wraps — and a shipped affix must carry real content, since a
+  // blank one is dropped by the join and silently loses the doctrine.
+  it("every affix-carrying factory preset is affix-capable and ships no empty affix", () => {
+    for (const [nodeType, presets] of Object.entries(FACTORY_PRESETS)) {
+      for (const p of presets) {
+        const d = p.data as Record<string, unknown>
+        const affixes = (["promptPrefix", "promptSuffix"] as const).filter(
+          (k) => d[k] !== undefined,
+        )
+        if (affixes.length === 0) continue
+        expect(
+          nodeSupportsPromptAffixes(nodeType),
+          `${p.id}: ships ${affixes.join("/")} but "${nodeType}" does not support pre/post text`,
+        ).toBe(true)
+        for (const k of affixes) {
+          const v = d[k]
+          expect(typeof v, `${p.id}: ${k} must be a string`).toBe("string")
+          expect((v as string).trim().length, `${p.id}: ${k} is blank`).toBeGreaterThan(0)
+        }
+      }
+    }
+  })
+})
+
 describe("factory-presets split integrity", () => {
   // The exact node-type keys, in the exact insertion order the single-file
   // catalog declared them. The split's index.ts must reproduce this order.

package/src/__tests__/node-prompt-fields.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest"
+import { NODE_PROMPT_FIELDS, nodeSupportsPromptAffixes, PROMPT_AFFIX_NODE_TYPES, getPromptFields, promptAffixCoreField, promptFieldCarriesAffixes, PROMPT_AFFIX_CORE_FIELD_OVERRIDES } from "../node-prompt-fields.js"
+import { NODE_PROMPT_CANDIDATE_FIELDS } from "../resolve-prompt.js"
+
+describe("nodeSupportsPromptAffixes", () => {
+  it("is true for every registered prompt node except explicit opt-outs", () => {
+    for (const [type, spec] of Object.entries(NODE_PROMPT_FIELDS)) {
+      expect(nodeSupportsPromptAffixes(type)).toBe(spec.affixes !== false)
+    }
+  })
+  it("text-prompt (plain Text input) opts out", () => expect(nodeSupportsPromptAffixes("text-prompt")).toBe(false))
+  it("generate-image / llm-chat / video-analysis support affixes", () => {
+    for (const t of ["generate-image", "llm-chat", "video-analysis"]) expect(nodeSupportsPromptAffixes(t)).toBe(true)
+  })
+  it("unknown / undefined → false", () => {
+    expect(nodeSupportsPromptAffixes("not-a-node")).toBe(false)
+    expect(nodeSupportsPromptAffixes(undefined)).toBe(false)
+  })
+  it("PROMPT_AFFIX_NODE_TYPES is exactly the registry minus opt-outs (37 types)", () => {
+    const expected = Object.entries(NODE_PROMPT_FIELDS).filter(([, s]) => s.affixes !== false).map(([t]) => t)
+    expect([...PROMPT_AFFIX_NODE_TYPES].sort()).toEqual(expected.sort())
+    expect(PROMPT_AFFIX_NODE_TYPES.size).toBe(37)
+  })
+  it("getPromptFields still resolves", () => expect(getPromptFields("generate-image")?.prompt).toBe("prompt"))
+})
+
+describe("promptAffixCoreField — the data key the RUN wraps with pre/post text", () => {
+  it("most nodes: the editor's primary prompt field", () => {
+    expect(promptAffixCoreField("generate-image")).toBe("prompt")
+    expect(promptAffixCoreField("llm-chat")).toBe("userInput")
+    expect(promptAffixCoreField("text-to-speech")).toBe("directText")
+  })
+  it("generate-script: the run wraps the topic `prompt`, NOT the editor's styleGuide (spec §7)", () => {
+    expect(getPromptFields("generate-script")?.prompt).toBe("styleGuide")
+    expect(promptAffixCoreField("generate-script")).toBe("prompt")
+  })
+  it("nodes with no affixes have no core field", () => {
+    expect(promptAffixCoreField("text-prompt")).toBeUndefined()
+    expect(promptAffixCoreField("not-a-node")).toBeUndefined()
+    expect(promptAffixCoreField(undefined)).toBeUndefined()
+  })
+  it("every affix-capable type resolves to a core field", () => {
+    for (const t of PROMPT_AFFIX_NODE_TYPES) expect(promptAffixCoreField(t)).toBeTruthy()
+  })
+  it("every override key is an affix-capable node type", () => {
+    for (const t of Object.keys(PROMPT_AFFIX_CORE_FIELD_OVERRIDES)) {
+      expect(PROMPT_AFFIX_NODE_TYPES.has(t)).toBe(true)
+    }
+  })
+})
+
+describe("promptFieldCarriesAffixes — does previewing this key show the run's affixes?", () => {
+  it("the core field carries them; a sibling field does not", () => {
+    expect(promptFieldCarriesAffixes("llm-chat", "userInput")).toBe(true)
+    expect(promptFieldCarriesAffixes("llm-chat", "systemPrompt")).toBe(false)
+    expect(promptFieldCarriesAffixes("generate-script", "prompt")).toBe(true)
+    expect(promptFieldCarriesAffixes("generate-script", "styleGuide")).toBe(false)
+  })
+  it("a run-time FALLBACK candidate carries them too (i2v's legacy motionPrompt)", () => {
+    // computeNodePrompt picks the first present of ["prompt", "motionPrompt"]
+    // and wraps THAT with the affixes — so previewing motionPrompt must wrap.
+    expect(promptFieldCarriesAffixes("image-to-video", "motionPrompt")).toBe(true)
+    expect(promptFieldCarriesAffixes("generate-video", "motionPrompt")).toBe(true)
+    expect(promptFieldCarriesAffixes("text-to-audio", "text")).toBe(true)
+  })
+  it("an affix-less node never carries them, whatever the field", () => {
+    expect(promptFieldCarriesAffixes("text-prompt", "text")).toBe(false)
+    expect(promptFieldCarriesAffixes("not-a-node", "prompt")).toBe(false)
+  })
+  it("omitting the field falls back to the node's primary prompt field", () => {
+    expect(promptFieldCarriesAffixes("generate-image", undefined)).toBe(true)
+    // generate-script's primary (styleGuide) is NOT the core → no wrap.
+    expect(promptFieldCarriesAffixes("generate-script", undefined)).toBe(false)
+    expect(promptFieldCarriesAffixes("text-prompt", undefined)).toBe(false)
+  })
+  it("no override type also declares run-time candidates (the two rules never collide)", () => {
+    for (const t of Object.keys(PROMPT_AFFIX_CORE_FIELD_OVERRIDES)) {
+      expect(NODE_PROMPT_CANDIDATE_FIELDS[t]).toBeUndefined()
+    }
+  })
+})

package/src/__tests__/parameter-registry-sync.test.ts

@@ -134,7 +134,10 @@ const SAMPLE_DATA_BY_TYPE: Record<string, Record<string, unknown>> = {
   "held-prop": { heldProp: firstId(HELD_PROPS) },
   "exposure-settings": { aperture: firstId(EXPOSURE_SETTINGS) },
   "render-quality": { renderQuality: firstId(RENDER_QUALITIES) },
-  "composition-effects": { compositionEffect: firstId(COMPOSITION_EFFECTS) },
+  // Not firstId: the head of the catalog is the neutral "none" entry, whose
+  // promptHint is deliberately empty (same reason transition/character-fx below
+  // name a real id instead of their "auto" head).
+  "composition-effects": { compositionEffect: "bursting-through-frame" },
   "post-process-effects": { postProcess: firstId(POST_PROCESS_EFFECTS) },
   "action-fx": { actionFx: firstId(ACTION_FX) },
   // TRANSITIONS[0] is "auto" with an intentionally empty promptHint — use a

package/src/__tests__/prompt-affixes.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from "vitest"
+import {
+  promptPartSeparator,
+  joinPromptParts,
+  applyPromptAffixes,
+  resolvePrompt,
+  computeNodePrompt,
+  computeLlmChatFields,
+} from "../resolve-prompt.js"
+
+const M = new Map<string, string>()
+const R = new Map([["Character", "Mira"], ["Hero", "a knight"]])
+
+describe("promptPartSeparator", () => {
+  it("inserts a space between two words", () => expect(promptPartSeparator("a", "b")).toBe(" "))
+  it("no space when left ends with whitespace", () => expect(promptPartSeparator("a ", "b")).toBe(""))
+  it("no space when left ends with a newline", () => expect(promptPartSeparator("a\n\n", "b")).toBe(""))
+  it("no space when right starts with whitespace", () => expect(promptPartSeparator("a", " b")).toBe(""))
+  it.each([",", ".", ";", ":", "!", "?", ")"])("no space when right starts with %s", (p) =>
+    expect(promptPartSeparator("a", `${p} b`)).toBe(""))
+})
+
+describe("joinPromptParts (spec §4.2)", () => {
+  it("prefix + core + comma-suffix", () =>
+    expect(joinPromptParts(["Cinematic 35mm still of", "a woman in Tokyo", ", golden hour"]))
+      .toBe("Cinematic 35mm still of a woman in Tokyo, golden hour"))
+  it("keeps an author's trailing newlines", () =>
+    expect(joinPromptParts(["RULES:\n- no text\n\n", "a red shoe", undefined])).toBe("RULES:\n- no text\n\na red shoe"))
+  it("core + sentence suffix", () =>
+    expect(joinPromptParts([undefined, "a red shoe", "Avoid clutter."])).toBe("a red shoe Avoid clutter."))
+  it("drops blank parts", () => expect(joinPromptParts(["  ", "x", ""])).toBe("x"))
+  it("all blank → empty string", () => expect(joinPromptParts(["", undefined, "  "])).toBe(""))
+})
+
+describe("applyPromptAffixes", () => {
+  it("no affixes → returns the SAME core reference", () => {
+    const core = "a red shoe"
+    expect(applyPromptAffixes(core, undefined, M)).toBe(core)
+    expect(applyPromptAffixes(core, {}, M)).toBe(core)
+    expect(applyPromptAffixes(undefined, {}, M)).toBeUndefined()
+  })
+  it("whitespace-only affixes are a no-op", () => {
+    const core = "x"
+    expect(applyPromptAffixes(core, { prefix: "  ", suffix: "" }, M)).toBe(core)
+  })
+  it("wraps with the join rule", () =>
+    expect(applyPromptAffixes("a woman in Tokyo", { prefix: "Cinematic 35mm still of", suffix: ", golden hour" }, M))
+      .toBe("Cinematic 35mm still of a woman in Tokyo, golden hour"))
+  it("resolves {Label} refs inside the affixes", () =>
+    expect(applyPromptAffixes("", { prefix: "Portrait of {Character}" }, R)).toBe("Portrait of Mira"))
+  it("empty core + affixes → the affixes alone", () =>
+    expect(applyPromptAffixes(undefined, { prefix: "PRE", suffix: "POST" }, M)).toBe("PRE POST"))
+  it("does not touch the core (no ref resolution, no trim)", () =>
+    expect(applyPromptAffixes(" {Hero} ", { suffix: "S" }, R)).toBe(" {Hero} S"))
+})
+
+describe("resolvePrompt × affixes", () => {
+  const A = { prefix: "PRE", suffix: "POST" }
+  it("wraps the override", () =>
+    expect(resolvePrompt({ override: "o", typed: ["t"], wired: "w", refMap: M, affixes: A })).toBe("PRE o POST"))
+  it("wraps the typed winner", () =>
+    expect(resolvePrompt({ typed: ["t"], wired: "w", refMap: M, affixes: A })).toBe("PRE t POST"))
+  it("wraps the wired fallback", () =>
+    expect(resolvePrompt({ typed: [""], wired: "w", refMap: M, affixes: A })).toBe("PRE w POST"))
+  it("appendWired: wraps the COMBINED typed. wired core", () =>
+    expect(resolvePrompt({ typed: ["t"], wired: "w", refMap: M, appendWired: true, affixes: A })).toBe("PRE t. w POST"))
+  it("nothing + affixes → affixes alone", () =>
+    expect(resolvePrompt({ typed: [], refMap: M, affixes: A })).toBe("PRE POST"))
+  it("without affixes is byte-identical to before", () =>
+    expect(resolvePrompt({ typed: ["x {Hero} y"], refMap: R })).toBe("x a knight y"))
+})
+
+describe("computeNodePrompt / computeLlmChatFields read affixes off data", () => {
+  it("generate-image", () =>
+    expect(computeNodePrompt("generate-image", { prompt: "typed", promptPrefix: "PRE", promptSuffix: "POST" }, { wired: "wire", refMap: M }))
+      .toBe("PRE typed POST"))
+  it("text-to-speech direct", () =>
+    expect(computeNodePrompt("text-to-speech", { textSource: "direct", directText: "d", promptSuffix: "POST" }, { refMap: M }))
+      .toBe("d POST"))
+  it("llm-chat: userInput wrapped, systemPrompt never", () =>
+    expect(computeLlmChatFields({ userInput: "u", systemPrompt: "s", promptPrefix: "PRE" }, { refMap: M }))
+      .toEqual({ userInput: "PRE u", systemPrompt: "s" }))
+})