@nodaro/prompts 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.8.0",
+  "version": "1.9.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": "*"
+    "@nodaro/shared": "^2.13.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

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__/fixtures/parameter-hint-golden.json

@@ -1182,7 +1182,7 @@
         }
       },
       "ctx": null,
-      "expected": "macro lens, extreme close-up revealing fine detail with shallow depth of field"
+      "expected": "macro lens, capable of extreme close focus and life-size magnification with a very shallow depth of field"
     },
     {
       "key": "lens/id:petzval",

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" }))
+})

package/src/__tests__/provider-prompt-doctrine.test.ts

@@ -48,4 +48,22 @@ describe("PROVIDER_PROMPT_DOCTRINES", () => {
     // no native negative-prompt param
     expect(d.doctrine).toMatch(/negative/i)
   })
+
+  it("splits the timestamp + multi-view rules by version: 2.0 SKUs no, seedance-2-5 yes (official 2.5 guide)", () => {
+    // Official "Dreamina Seedance 2.5 prompt guide" → Differences from Seedance 2.0:
+    // 2.0 does not respond to timestamps (shot numbers only) and multi-view
+    // subject images are not recommended; 2.5 supports integer-second
+    // timestamps and multi-view references. The doctrine is one group for the
+    // whole family, so BOTH halves must be stated — a rewrite that drops
+    // either side re-applies a 2.0 rule to 2.5 (or vice versa).
+    const d = getPromptDoctrine("seedance-2-5")!
+    expect(d.providers).toContain("seedance-2")
+    expect(d.doctrine).toMatch(/2\.0[^.]*(ignore|do not respond to|respond to shot numbers only)[^.]*timestamps|timestamps[^.]*2\.0/i)
+    expect(d.doctrine).toMatch(/seedance-2-5[^.]*integer-second timestamps|integer-second timestamps[^.]*2\.5/i)
+    expect(d.doctrine).toMatch(/At the 5-second mark/)
+    expect(d.doctrine).toMatch(/2\.5 accepts multi-view|supported on 2\.5/i)
+    const tips = getPromptTips("seedance-2-5").join(" ")
+    expect(tips).toMatch(/2\.0 SKUs ignore timestamps/)
+    expect(tips).toMatch(/seedance-2-5 honours integer-second timestamps/)
+  })
 })

package/src/__tests__/transition-timing-catalogs.test.ts

@@ -0,0 +1,151 @@
+/**
+ * The transition 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.
+ *
+ * Two properties matter, and both are 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 `transitions.ts`, and
+ *     these tests fail the moment someone re-introduces a second copy.
+ *  2. The dimensions survive the wire projection. `projectPickerCatalog` used
+ *     to return `options` only for a `kind: "single"` catalog, which silently
+ *     dropped them — green unit tests on the in-memory catalog would not have
+ *     caught it.
+ */
+import { describe, it, expect } from "vitest"
+import {
+  TRANSITION_POSITIONS,
+  TRANSITION_DURATIONS,
+  TRANSITION_INTENSITIES,
+  composeTransitionHintFromConnections,
+} from "../transitions.js"
+import { PICKER_CATALOGS, projectPickerCatalog } from "../picker-catalogs.js"
+
+const DIMENSIONS = [
+  ["position", TRANSITION_POSITIONS],
+  ["duration", TRANSITION_DURATIONS],
+  ["intensity", TRANSITION_INTENSITIES],
+] as const
+
+const transitionCatalog = PICKER_CATALOGS.find((c) => c.nodeType === "transition")!
+
+describe("transition timing catalogs", () => {
+  // The `TransitionPosition` / `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(TRANSITION_POSITIONS.map((o) => o.id)).toEqual([
+      "auto", "start", "middle", "end", "full",
+    ])
+    expect(TRANSITION_DURATIONS.map((o) => o.id)).toEqual([
+      "auto", "instant", "short", "medium", "long",
+    ])
+    expect(TRANSITION_INTENSITIES.map((o) => o.id)).toEqual([
+      "auto", "subtle", "natural", "dynamic", "crazy",
+    ])
+  })
+
+  it("carries the timing precision users read off the dropdown", () => {
+    // The editor used to hand-write these labels and had already drifted from
+    // the catalog on all three rows. It now renders straight from here, so this
+    // is the one place the numbers live.
+    expect(TRANSITION_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.
+    for (const [field, options] of DIMENSIONS) {
+      for (const o of options.slice(1)) {
+        const composed = composeTransitionHintFromConnections("cross-dissolve", [], [], {
+          [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 TRANSITION_POSITIONS.slice(1)) {
+      const composed = composeTransitionHintFromConnections("cross-dissolve", [], [], { position: o.id as never })
+      expect(composed, `position/${o.id}`).toContain(o.promptHint)
+    }
+    for (const o of TRANSITION_DURATIONS.slice(1)) {
+      const composed = composeTransitionHintFromConnections("cross-dissolve", [], [], { duration: o.id as never })
+      expect(composed, `duration/${o.id}`).toContain(o.promptHint)
+    }
+    for (const o of TRANSITION_INTENSITIES.slice(1)) {
+      const composed = composeTransitionHintFromConnections("cross-dissolve", [], [], { intensity: o.id as never })
+      expect(composed, `intensity/${o.id}`).toContain(o.promptHint)
+    }
+  })
+
+  it("`auto` adds nothing to the composed sentence", () => {
+    const bare = composeTransitionHintFromConnections("cross-dissolve", [], [])
+    const allAuto = composeTransitionHintFromConnections("cross-dissolve", [], [], { position: "auto", duration: "auto", intensity: "auto" })
+    expect(allAuto).toBe(bare)
+  })
+
+  it("exposes the three dimensions on the transition catalog", () => {
+    expect(transitionCatalog.kind).toBe("single")
+    expect(transitionCatalog.dimensions?.map((d) => d.field)).toEqual([
+      "position",
+      "duration",
+      "intensity",
+    ])
+  })
+
+  it("keeps the dimensions through the wire projection", () => {
+    const wire = projectPickerCatalog(transitionCatalog, { detail: "full" })
+
+    // The 82-option transition list is untouched by the addition.
+    expect(wire.options?.length).toBe(transitionCatalog.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("leaves every other single-dim catalog without dimensions", () => {
+    const singlesWithDims = PICKER_CATALOGS.filter(
+      (c) => c.kind === "single" && c.dimensions,
+    ).map((c) => c.nodeType)
+    expect(singlesWithDims).toEqual(["transition"])
+  })
+})

package/src/composition-effects.ts

@@ -32,6 +32,12 @@ export interface CompositionEffect {
 }
 
 export const COMPOSITION_EFFECTS: ReadonlyArray<CompositionEffect> = [
+  // The neutral default. Every other entry is a dramatic subject transform, so
+  // an unconfigured node must inject nothing — the same no-op-entry convention
+  // `transitions`/`character-fx` use for their "auto" default, which keeps the
+  // default a real catalog id (see the `defaultValue` contract in
+  // picker-catalogs.ts) instead of a value absent from the option list.
+  { id: "none",                   label: "None",                   description: "No composition effect",              promptHint: "", term: "" },
   { id: "bursting-through-frame", label: "Bursting Through Frame", description: "3D paper-tear breaking the frame",   promptHint: "the subject bursting forward through a torn paper frame in a 3D paper-tear effect, head and shoulders breaking the plane of the canvas with ragged paper edges curling outward", term: "3d pop-out through a torn paper frame" },
   { id: "breaking-out-of-frame",  label: "Breaking Out of Frame",  description: "Limb extends past canvas border",     promptHint: "the subject's hand or limb extending past the canvas border, breaking the fourth wall and reaching beyond the frame's edge into the viewer's space", term: "out-of-bounds effect, limb past the frame" },
   { id: "pixel-disintegration",   label: "Pixel Disintegration",   description: "Subject dissolving into particles",   promptHint: "the subject pixelating and dissolving into floating geometric particles drifting outward, ordered chaos with crisp pixel-cube fragments scattering away from the silhouette" },
@@ -45,7 +51,6 @@ export const COMPOSITION_EFFECTS: ReadonlyArray<CompositionEffect> = [
   { id: "floating-fragments",     label: "Floating Fragments",     description: "Body partially drifting away",        promptHint: "the subject's body partially floating away in fragments, broken pieces of the figure detaching and drifting upward like windborne paper, leaving a partially dissolved silhouette", term: "body fragmenting into drifting pieces" },
   { id: "silhouette-outline",     label: "Silhouette Outline",     description: "Clean black silhouette on flat BG",   promptHint: "the subject reduced to a clean black silhouette outline against a flat single-color background, no internal detail, pure shape language", term: "flat black silhouette on a solid background" },
   { id: "exploding-particles",    label: "Exploding Particles",    description: "Outline scattering into particles",   promptHint: "the subject's outline exploding outward into a cloud of fine particles, dust and motes scattering radially around a partially intact core figure" },
-  { id: "3x3-grid-collage",       label: "3x3 Grid Collage",       description: "Contact-sheet 9-pose montage",        promptHint: "the subject shown in a 3x3 grid of varied poses and expressions arranged as a contact-sheet collage, nine clean panels with consistent lighting and slight pose variation in each cell" },
   { id: "matte-painting",         label: "Matte Painting",         description: "Composite matte-painted background blended with live action, classic VFX", promptHint: "the subject composited against a matte-painted background blended seamlessly with live action, classic VFX matte-painting integration with hand-painted environment extension behind the figure" },
   { id: "double-exposure",        label: "Double Exposure",        description: "Two layered photographic exposures fused into one image", promptHint: "two layered photographic exposures fused into one image, the subject's silhouette filled with a secondary scene and translucent overlapping forms in classic darkroom double-exposure technique" },
   { id: "multiple-exposure",      label: "Multiple Exposure",      description: "Three or more exposures stacked, kaleidoscopic layering", promptHint: "three or more photographic exposures stacked into a single frame, kaleidoscopic layering of repeated subject positions with translucent overlapping silhouettes echoing across the canvas" },