@nodaro/prompts 1.8.1 → 1.10.0

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

@@ -0,0 +1,153 @@
+/**
+ * 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", () => {
+    // `character-fx` carries the same three timing fields with its own,
+    // deliberately different wording (see `character-fx-timing-catalogs.test.ts`).
+    const singlesWithDims = PICKER_CATALOGS.filter(
+      (c) => c.kind === "single" && c.dimensions,
+    ).map((c) => c.nodeType)
+    expect(singlesWithDims).toEqual(["transition", "character-fx"])
+  })
+})

package/src/__tests__/video-reference-ref-id-tokens.test.ts

@@ -0,0 +1,301 @@
+/**
+ * `{ref:<id>}` / `{ref:<id>:<label>}` — id-addressed reference tokens.
+ *
+ * A client that names a reference by the `connectedReferences[].id` it sent
+ * (Studio's bound `@`-chips) gets the `@image_N` slot substituted by the
+ * platform AFTER the platform has numbered the references. That removes the
+ * client-side mirror of the numbering walk — the one duplicated rule that could
+ * silently misbind pictures for a client built against an older package.
+ *
+ * Contract pinned here:
+ *   - the slot comes from the SAME walk that numbers the directives (mention
+ *     URLs → canonical fallback → extras, offset by the leading flat refs);
+ *   - the token is resolved BEFORE the `referenceOrder` reorder, so the
+ *     renumber pass carries the binding to the ref's final seat — the opposite
+ *     of `{image:N}`, which is resolved AFTER it to keep the author's N;
+ *   - an unresolvable token never ships raw: label → the ref's display name
+ *     (when the id is known) → "";
+ *   - a prompt with no `{ref:` token is byte-identical to before.
+ */
+import { describe, it, expect } from "vitest"
+import {
+  resolveVideoReferenceCore,
+  resolveRefIdTokens,
+  resolveReferenceTokens,
+} from "../video-reference-resolver.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const charRef = (over: Partial<ConnectedReference> = {}): ConnectedReference => ({
+  id: "char-kira", defaultName: "Kira", source: "wired-character", url: "https://r2/kira.png",
+  characterSlug: "kira", variantSlug: undefined, characterCanonicalDescription: null,
+  variantDescription: null, variantDisplayName: "canonical", ...over,
+})
+
+const A = "https://cdn/a.png"
+const B = "https://cdn/b.png"
+
+/** Every case: the token must be gone, whatever it resolved to. */
+function expectNoRawToken(prompt: string | undefined) {
+  expect(prompt ?? "").not.toMatch(/\{ref:/i)
+}
+
+describe("resolveVideoReferenceCore — {ref:<id>} id-addressed tokens", () => {
+  it("bare {ref:<id>} binds an image extra to its @image_N slot", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "drive {ref:car-1} fast",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+    })
+    expect(out.additionalUrls).toEqual(["https://r2/car.png"])
+    expect(out.prompt).toContain("- @image_1 (reference): a red car.")
+    expect(out.prompt).toContain("drive @image_1 fast")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("labeled {ref:<id>:<label>} binds through REF_BINDING.image (parity with {image:N:label})", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "drive {ref:car-1:car} fast",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+    })
+    expect(out.prompt).toContain("drive the car from @image_1 fast")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a canonical wired character binds to its canonical-fallback slot", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:char-kira} walks in",
+      wiredCharRefs: [charRef()],
+    })
+    expect(out.additionalUrls).toEqual(["https://r2/kira.png"])
+    expect(out.prompt).toContain("Use these characters:")
+    expect(out.prompt).toContain("@image_1 walks in")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a character VIEW (extra with characterSlug) binds to its pair-back slot after the canonical", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:view-1} turns to face {ref:char-kira}",
+      wiredCharRefs: [charRef()],
+      extraRefs: [{ id: "view-1", url: "https://r2/kira-side.png", characterSlug: "kira", description: "side profile" }],
+    })
+    expect(out.additionalUrls).toEqual(["https://r2/kira.png", "https://r2/kira-side.png"])
+    expect(out.prompt).toContain("- @image_2 is the same subject as @image_1, side profile.")
+    expect(out.prompt).toContain("@image_2 turns to face @image_1")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("leading flat refs offset the slot (D5 image-refs-first)", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "the {ref:obj} on the table",
+      wiredCharRefs: [],
+      leadingRefUrls: [A],
+      extraRefs: [{ id: "obj", url: B, description: "object" }],
+    })
+    expect(out.additionalUrls).toEqual([A, B])
+    expect(out.prompt).toContain("the @image_2 on the table")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("ids are opaque: `:` and `/` inside an id resolve, and a trailing label still parses", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:https://cdn/pic.png} beside {ref:kira:smile:smile}",
+      wiredCharRefs: [],
+      extraRefs: [
+        { id: "https://cdn/pic.png", url: "https://cdn/pic.png", description: "pic" },
+        { id: "kira:smile", url: "https://r2/kira-smile.png", description: "smile" },
+      ],
+    })
+    expect(out.prompt).toContain("@image_1 beside the smile from @image_2")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("an unknown id degrades to its label, or to nothing — never the raw token", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a {ref:nope:ghost} b {ref:nope2} c",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "x", url: A, description: "d" }],
+    })
+    expect(out.prompt).toContain("a ghost b c")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a known ref the walk never seated degrades to its display name", () => {
+    // A wired character with no url is skipped by the canonical loop — the id
+    // is known (so the name is), but there is no slot to bind.
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:char-kira} waves at {ref:capped-1}",
+      wiredCharRefs: [charRef({ url: "" })],
+      extraRefs: [{ id: "x", url: A, description: "d" }],
+      // The caller's full id → name map (the route builds it from EVERY
+      // connectedReference, including the ones it capped out before the walk).
+      refNamesById: new Map([["capped-1", "Truck"]]),
+    })
+    expect(out.prompt).toContain("Kira waves at Truck")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a duplicate-URL extra never binds past the payload: its {ref:} degrades to its name", () => {
+    // The walk counts every extra with a url while `merged` dedups by URL, so
+    // the second extra's directive is numbered @image_2 although the payload
+    // carries ONE image (pre-existing walk-vs-merged drift). The token is
+    // range-gated against the image count, so it degrades instead of emitting
+    // a phantom binding.
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:x} then {ref:y}",
+      wiredCharRefs: [],
+      extraRefs: [
+        { id: "x", url: A, description: "first" },
+        { id: "y", url: A, description: "second" },
+      ],
+      refNamesById: new Map([["y", "Second"]]),
+    })
+    expect(out.additionalUrls).toEqual([A])
+    expect(out.prompt).toContain("@image_1 then Second")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("resolves BEFORE the referenceOrder reorder, so the binding follows the ref to its final seat", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:y} leads, {ref:x} follows",
+      wiredCharRefs: [],
+      extraRefs: [
+        { id: "x", url: A, description: "ax" },
+        { id: "y", url: B, description: "by" },
+      ],
+      // Extras' tile ids are `wired:<url>` (the reorder contract, unchanged).
+      referenceOrder: [`wired:${B}`, `wired:${A}`],
+    })
+    expect(out.additionalUrls).toEqual([B, A])
+    expect(out.prompt).toContain("@image_1 leads, @image_2 follows")
+    expect(out.prompt).toContain("- @image_1 (reference): by.")
+    expect(out.prompt).toContain("- @image_2 (reference): ax.")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("keeps {image:N} resolved AFTER the reorder (author's N kept) while {ref:} follows the ref", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:y} and {image:2:second}",
+      wiredCharRefs: [],
+      extraRefs: [
+        { id: "x", url: A, description: "ax" },
+        { id: "y", url: B, description: "by" },
+      ],
+      referenceOrder: [`wired:${B}`, `wired:${A}`],
+    })
+    // y moved to seat 1 → {ref:y} rides along; {image:2} keeps the literal 2.
+    expect(out.prompt).toContain("@image_1 and the second from @image_2")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("an @-mentioned character's ref binds to the mention's slot", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "@kira:1 waves, then {ref:char-kira} sits",
+      wiredCharRefs: [charRef()],
+    })
+    expect(out.additionalUrls).toEqual(["https://r2/kira.png"])
+    expect(out.prompt).toContain("Kira waves, then @image_1 sits")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("is independent of hybridRoles — same slot, no legend block", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "drive {ref:car-1} fast",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+      hybridRoles: true,
+    })
+    expect(out.prompt).not.toContain("Use these characters:")
+    expect(out.prompt).toContain("drive @image_1 fast")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a prompt with no {ref: token is untouched — `{ref}` and `ref:` are not tokens", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "circle {image:1:object} {ref} ref: x",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+    })
+    expect(out.prompt).toContain("circle the object from @image_1 {ref} ref: x")
+  })
+
+  it("an empty id drops to nothing and the keyword is case-insensitive", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "x {ref:} {REF:car-1} y",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+    })
+    expect(out.prompt).toContain("x @image_1 y")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("imageRefCount: 0 (no image tokens may bind) degrades a seated ref to its name", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:char-kira} walks",
+      wiredCharRefs: [charRef()],
+      imageRefCount: 0,
+    })
+    expect(out.prompt).toContain("Kira walks")
+    expect(out.prompt).not.toContain("@image_1 walks")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("early-return path (no wired chars, no extras): degrades to name / label / nothing", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:a} and {ref:b:the dog} and {ref:c}",
+      wiredCharRefs: [],
+      leadingRefUrls: [A],
+      refNamesById: new Map([["a", "Alpha"]]),
+    })
+    expect(out.additionalUrls).toEqual([A])
+    expect(out.prompt).toBe("Alpha and the dog and")
+    expectNoRawToken(out.prompt)
+  })
+})
+
+describe("resolveRefIdTokens — malformed and adversarial input", () => {
+  it("a malformed token (brace inside the id, no closing brace) never ships its `{ref:` prefix", () => {
+    const out = resolveRefIdTokens("x {ref:a{b} y {ref:unclosed z", {
+      slotById: new Map([["a", 1]]),
+      nameById: new Map(),
+      imageCount: 1,
+    })
+    expect(out).not.toMatch(/\{ref:/i)
+    // The net is bounded by whitespace/braces: the prose after each run survives.
+    expect(out).toContain(" y ")
+    expect(out).toContain(" z")
+  })
+
+  it("scans a prompt at the hard ceiling with an adversarial shape and still resolves (linear matcher)", () => {
+    // 30k chars of `{ref:` followed by label-class text with no closing brace —
+    // the shape that made a lazy-quantifier matcher quadratic.
+    const adversarial = "{ref:" + ":a".repeat(15000)
+    const out = resolveRefIdTokens(`${adversarial} end {ref:x}`, {
+      slotById: new Map([["x", 1]]),
+      nameById: new Map(),
+      imageCount: 1,
+    })
+    expect(out).not.toMatch(/\{ref:/i)
+    expect(out).toContain("end @image_1")
+  })
+})
+
+describe("resolveRefIdTokens (standalone — the route's no-image-ref early return)", () => {
+  it("binds in-range slots, and degrades label → name → nothing otherwise", () => {
+    const resolved = resolveRefIdTokens("{ref:x:car} {ref:x} {ref:y:dog} {ref:y} {ref:z}", {
+      slotById: new Map([["x", 2], ["y", 4]]),
+      nameById: new Map([["y", "Dog"]]),
+      imageCount: 3,
+    })
+    // y is seated at 4 but only 3 images ship → name; z is unknown → nothing.
+    expect(resolveReferenceTokens(resolved, { image: 3, video: 0, audio: 0 })).toBe(
+      "the car from @image_2 @image_2 dog Dog",
+    )
+  })
+
+  it("returns the prompt untouched when no {ref: token is present", () => {
+    const prompt = "plain {image:1} prose"
+    expect(resolveRefIdTokens(prompt, { slotById: new Map(), nameById: new Map(), imageCount: 0 })).toBe(prompt)
+    expect(resolveRefIdTokens(undefined, { slotById: new Map(), nameById: new Map(), imageCount: 0 })).toBeUndefined()
+  })
+})

package/src/character-fx.ts

@@ -37,9 +37,23 @@ export interface CharacterFx {
   readonly term?: string
 }
 
-export type CharacterFxPosition  = "auto" | "start" | "middle" | "end" | "full"
-export type CharacterFxDuration  = "auto" | "instant" | "short" | "medium" | "long"
-export type CharacterFxIntensity = "auto" | "subtle" | "natural" | "dynamic" | "crazy"
+/**
+ * The three timing scales, each derived from the catalog that defines it (see
+ * `CHARACTER_FX_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 `character-fx-timing-catalogs.test.ts`.
+ */
+export type CharacterFxPosition  = (typeof CHARACTER_FX_POSITIONS)[number]["id"]
+export type CharacterFxDuration  = (typeof CHARACTER_FX_DURATIONS)[number]["id"]
+export type CharacterFxIntensity = (typeof CHARACTER_FX_INTENSITIES)[number]["id"]
 
 export interface CharacterFxTiming {
   position?:  CharacterFxPosition
@@ -266,27 +280,96 @@ export const CHARACTER_FX_IDS: ReadonlyArray<string> = CHARACTER_FX.map((c) => c
 // Graph-aware composer — target input handle + timing fields + multi-pick
 // ---------------------------------------------------------------------------
 
-const POSITION_CLAUSES: Record<Exclude<CharacterFxPosition, "auto">, string> = {
-  start:  "the effect occurs at the opening of the clip",
-  middle: "the effect occurs in the middle of the clip",
-  end:    "the effect occurs at the end of the clip",
-  full:   "the effect persists for the entire clip",
+/**
+ * The character-fx node's three timing parameters, as catalogs.
+ *
+ * Graded scales in the standard option shape, so a consumer that can only send
+ * ids (Studio, the SDK, MCP) can offer Position / Duration / Intensity 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.
+ *
+ * These are NOT the transition node's scales, even though the ids match. The
+ * wording is deliberately different — a transition OCCURS and SPANS the clip,
+ * an effect MANIFESTS and PERSISTS — and the three intensity clauses coincide
+ * by accident, not by shared definition. Keep the two catalogs separate; do
+ * not fold one into the other.
+ *
+ * `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 CharacterFxTimingOption {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  readonly promptHint: string
+  readonly term?: string
 }
 
-const DURATION_CLAUSES: Record<Exclude<CharacterFxDuration, "auto">, string> = {
-  instant: "manifesting instantaneously",
-  short:   "manifesting over approximately 1 second",
-  medium:  "manifesting over approximately 2 seconds",
-  long:    "manifesting over approximately 3 seconds",
-}
+export const CHARACTER_FX_POSITIONS = [
+  { id: "auto",   label: "Auto",   description: "Let the model place the effect",    promptHint: "", term: "" },
+  { id: "start",  label: "Start",  description: "Occurs at the opening of the clip", promptHint: "the effect occurs at the opening of the clip", term: "at the opening of the clip" },
+  { id: "middle", label: "Middle", description: "Occurs in the middle of the clip",  promptHint: "the effect occurs in the middle of the clip", term: "mid-clip" },
+  { id: "end",    label: "End",    description: "Occurs at the end of the clip",     promptHint: "the effect occurs at the end of the clip", term: "at the end of the clip" },
+  { id: "full",   label: "Full",   description: "Persists for the entire clip",      promptHint: "the effect persists for the entire clip", term: "persisting for the whole clip" },
+] as const satisfies ReadonlyArray<CharacterFxTimingOption>
+
+export const CHARACTER_FX_DURATIONS = [
+  { id: "auto",    label: "Auto",         description: "Let the model time the effect",          promptHint: "", term: "" },
+  { id: "instant", label: "Instant",      description: "Manifests instantaneously",              promptHint: "manifesting instantaneously", term: "manifesting instantly" },
+  { id: "short",   label: "Short (~1s)",  description: "Manifests over approximately 1 second",  promptHint: "manifesting over approximately 1 second", term: "manifesting over about 1 second" },
+  { id: "medium",  label: "Medium (~2s)", description: "Manifests over approximately 2 seconds", promptHint: "manifesting over approximately 2 seconds", term: "manifesting over about 2 seconds" },
+  { id: "long",    label: "Long (~3s)",   description: "Manifests over approximately 3 seconds", promptHint: "manifesting over approximately 3 seconds", term: "manifesting over about 3 seconds" },
+] as const satisfies ReadonlyArray<CharacterFxTimingOption>
 
-const INTENSITY_CLAUSES: Record<Exclude<CharacterFxIntensity, "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",
+export const CHARACTER_FX_INTENSITIES = [
+  { id: "auto",    label: "Auto",    description: "Let the model judge the effect's energy", promptHint: "", term: "" },
+  { id: "subtle",  label: "Subtle",  description: "Restrained, minimal flourish",            promptHint: "with subtle restrained energy and minimal flourish", term: "subtly" },
+  { id: "natural", label: "Natural", description: "Unhurried, unforced timing",             promptHint: "with natural unhurried timing", term: "at a natural pace" },
+  { id: "dynamic", label: "Dynamic", description: "Assertive, energetic",                   promptHint: "with dynamic energy and assertive flourish", term: "energetically" },
+  { id: "crazy",   label: "Crazy",   description: "Extreme, wild, distorted",               promptHint: "with extreme exaggerated energy, wild flourishes, and dramatic distortion", term: "wildly exaggerated" },
+] as const satisfies ReadonlyArray<CharacterFxTimingOption>
+
+/**
+ * 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.
+ *
+ * Deliberately a private twin of the helper in `transitions.ts` rather than a
+ * shared import: the two nodes' timing catalogs must stay independent.
+ */
+function clausesOf<T extends CharacterFxTimingOption>(
+  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(CHARACTER_FX_POSITIONS)
+const DURATION_CLAUSES  = clausesOf(CHARACTER_FX_DURATIONS)
+const INTENSITY_CLAUSES = clausesOf(CHARACTER_FX_INTENSITIES)
+
+/**
+ * Widening guard. `as const` on the three arrays above is load-bearing: drop
+ * it and every id widens to `string`, the derived unions stop constraining
+ * anything, and the clause records degrade to `Record<string, string>` — the
+ * totality guarantee is gone with no runtime symptom. This assignment stops
+ * compiling the moment that happens (tsup's DTS build runs the type checker).
+ */
+type NarrowIds<T> = string extends T ? never : true
+const _timingIdsStayNarrow: [
+  NarrowIds<CharacterFxPosition>,
+  NarrowIds<CharacterFxDuration>,
+  NarrowIds<CharacterFxIntensity>,
+] = [true, true, true]
+void _timingIdsStayNarrow
+
 /**
  * Compose a character-fx prompt-hint sentence from an effect id (or array
  * of 1-2 ids for multi-pick) plus target-ref display names (from upstream

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