@nodaro/prompts 1.27.0 → 1.29.0

package/src/__tests__/fixtures/parameter-hint-golden.json

@@ -1931,6 +1931,38 @@
       "ctx": null,
       "expected": "a Crusader knight — chainmail hauberk under a white surcoat with a red cross emblem, conical helm, longsword and kite shield, devout warrior bearing, in their early 20s, around 21 years old, of Norwegian descent, a Shibuya streetwear aesthetic — Tokyo street-fashion vibe, layered post-modern mood, full-figured, full bust, pear-shaped silhouette, a heart-shaped face with a wide forehead and pointed chin, a pointed chin with a narrow jawline, high, defined cheekbones, a lean face with low facial fat and subtle hollowing beneath the cheekbones, double-eyelid eyes with a clearly defined upper crease, droopy eyes with the upper lids sitting low for a soft, sleepy gaze, upturned eyes with the outer corners lifted, positive canthal tilt, close-set eyes set close together, eyes set close beneath the brow with little brow-to-eye distance, hunter eyes, a small button nose with a rounded tip, a slightly upturned nose tip, full plump lips, a wide mouth, with lips pursed, pressed and pushed forward, long straight hair, gray hair, bold defined dark full eyebrows, tan skin, with visible swimwear tan lines on the skin, rare violet eyes with a deep purple iris, gazing off-camera with a contemplative expression, a goatee, with a small face tattoo near the eye or cheekbone"
     },
+    {
+      "key": "person/mixed-heritage",
+      "note": "Two ethnicity picks → one mixed-heritage phrase from the entries' prompt text",
+      "node": {
+        "id": "n1",
+        "type": "person",
+        "data": {
+          "ethnicity": [
+            "slavic",
+            "mediterranean"
+          ]
+        }
+      },
+      "ctx": null,
+      "expected": "of mixed Slavic Eastern European and Mediterranean heritage"
+    },
+    {
+      "key": "person/mixed-heritage-abbrev",
+      "note": "Two ethnicity picks whose short labels are abbreviations (Pacific Isl. / East (any))",
+      "node": {
+        "id": "n1",
+        "type": "person",
+        "data": {
+          "ethnicity": [
+            "pacific-islander",
+            "east-asian"
+          ]
+        }
+      },
+      "ctx": null,
+      "expected": "of mixed Pacific Islander and East Asian heritage"
+    },
     {
       "key": "person/one-dimension",
       "note": "multi-dim: only \"type\" set",
@@ -2922,7 +2954,7 @@
         }
       },
       "ctx": null,
-      "expected": "double exposure (the first and second scenes blend as a translucent double exposure where both images coexist semi-transparently on the frame, the first image then gradually fades out leaving the second image fully resolved)"
+      "expected": "double exposure (the first subject becomes a crisp silhouette filled solid with the second shot, while the rest of the first shot stays untouched around it. The camera stays where it is and the framing does not change. The silhouette holds for a clear beat, both pictures plainly seen at once, then the first shot around it gives way to the second shot. The shot ends on the second shot alone, fully resolved)"
     },
     {
       "key": "transition/id:dream-ripple",

package/src/__tests__/hint-join.test.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect } from "vitest"
-import { joinHintFragments } from "../hint-join.js"
+import { joinHintFragments, joinSentences, appendPromptHints } from "../hint-join.js"
+import { joinPromptHints } from "../prompt-hint-join.js"
+import { composeNegative, resolvePrompt } from "../resolve-prompt.js"
 import { composeCameraMotionHintFromConnections, getCameraMotionPromptHint } from "../camera-motions.js"
 import { getParameterPromptHint } from "../parameter-prompt-hint.js"
 
@@ -56,3 +58,64 @@ describe("sentence-style camera-motion hints compose cleanly", () => {
     )
   })
 })
+
+/**
+ * A prompt typed with a closing period used to come out doubled once a picker
+ * hint was appended: "No text, no logos, no watermark.. butterfly portrait
+ * lighting" (every picker example run in the docs rebuild).
+ */
+describe("joinSentences", () => {
+  it("joins with a period and a space", () => {
+    expect(joinSentences(["a red fox", "soft window light"])).toBe("a red fox. soft window light")
+  })
+
+  it("never doubles a closing period, question or exclamation mark, or ellipsis", () => {
+    expect(joinSentences(["No text, no logos, no watermark.", "butterfly portrait lighting"])).toBe(
+      "No text, no logos, no watermark. butterfly portrait lighting",
+    )
+    expect(joinSentences(["Is it raining?", "wet asphalt"])).toBe("Is it raining? wet asphalt")
+    expect(joinSentences(["Go!", "motion blur"])).toBe("Go! motion blur")
+    expect(joinSentences(["and then…", "a door opens"])).toBe("and then… a door opens")
+    expect(joinSentences(["雨の街。", "neon"])).toBe("雨の街。 neon")
+  })
+
+  it("does not carry trailing space into the join, and drops blank pieces", () => {
+    expect(joinSentences(["a cat.  ", "noir"])).toBe("a cat. noir")
+    expect(joinSentences(["a cat \n", "noir"])).toBe("a cat. noir")
+    expect(joinSentences(["", "  ", undefined, "noir"])).toBe("noir")
+    expect(joinSentences([])).toBe("")
+  })
+})
+
+describe("appendPromptHints", () => {
+  it("joins the hints as clauses, then follows the prompt as a new sentence", () => {
+    expect(appendPromptHints("A studio portrait.", ["butterfly lighting", "85mm lens"])).toBe(
+      "A studio portrait. butterfly lighting, 85mm lens",
+    )
+    expect(appendPromptHints("A studio portrait", ["butterfly lighting"])).toBe("A studio portrait. butterfly lighting")
+  })
+
+  it("gives the hints alone with no prompt, and the prompt back unchanged with no hints", () => {
+    expect(appendPromptHints(undefined, ["butterfly lighting"])).toBe("butterfly lighting")
+    expect(appendPromptHints("", ["butterfly lighting"])).toBe("butterfly lighting")
+    expect(appendPromptHints("A portrait.  ", [])).toBe("A portrait.  ")
+    expect(appendPromptHints("A portrait", ["", "  "])).toBe("A portrait")
+  })
+})
+
+describe("the other prompt joins are sentence-aware too", () => {
+  const M = new Map<string, string>()
+  it("folded direction hints (joinPromptHints)", () => {
+    expect(joinPromptHints("No watermark.", ["golden hour", "shallow depth of field"])).toBe(
+      "No watermark. golden hour. shallow depth of field",
+    )
+    expect(joinPromptHints("  untouched  ", [])).toBe("  untouched  ")
+  })
+  it("a connected prompt appended to the typed one (appendWired)", () => {
+    expect(resolvePrompt({ typed: ["A fox."], wired: "in the snow", refMap: M, appendWired: true })).toBe("A fox. in the snow")
+  })
+  it("a connected negative prompt (composeNegative)", () => {
+    expect(composeNegative("blurry.", "watermark")).toBe("blurry. watermark")
+    expect(composeNegative("blurry", "watermark")).toBe("blurry. watermark")
+  })
+})

package/src/__tests__/motion-hint.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest"
+import { getParameterPromptHint } from "../parameter-prompt-hint.js"
+
+describe("Motion's prompt clause", () => {
+  it.each([
+    ["subtle", /subtle, gentle motion/],
+    ["moderate", /moderate, natural motion/],
+    ["dynamic", /dynamic, energetic motion/],
+  ])("%s", (motion, clause) => {
+    expect(getParameterPromptHint({ id: "m", type: "motion", data: { motion } })).toMatch(clause)
+  })
+
+  it("is the bare term in compact mode", () => {
+    expect(getParameterPromptHint({ id: "m", type: "motion", data: { motion: "dynamic", hintMode: "compact" } })).toBe("dynamic motion")
+  })
+
+  it("is empty for an unknown step", () => {
+    expect(getParameterPromptHint({ id: "m", type: "motion", data: { motion: "wild" } })).toBe("")
+  })
+})

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

@@ -152,6 +152,7 @@ const SAMPLE_DATA_BY_TYPE: Record<string, Record<string, unknown>> = {
   "scene-count": { count: 5 },
   "duration": { seconds: 8 },
   "aspect-ratio": { ratio: "16:9" },
+  "provider": { category: "video", provider: "seedance-2" },
   "music-genre": { genre: firstId(MUSIC_GENRES) },
   "music-mood": { emotion: firstId(MUSIC_EMOTIONS) },
   "instrumentation": { instruments: [firstId(INSTRUMENTS)] },

package/src/__tests__/person-mixed-heritage.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Two ethnicity picks read as one heritage phrase built from each entry's
+ * prompt text — never from its short label, which is picker-grid display copy
+ * ("Mediter.", "Pacific Isl.", "any", a bare "East"). Two picks used to put
+ * those abbreviations into the prompt: "of mixed Slavic and Mediter. heritage".
+ */
+import { describe, it, expect } from "vitest"
+import { buildPersonHints, buildPersonTerms, PEOPLE } from "../person.js"
+
+const hintsFor = (ethnicity: string[]) => buildPersonHints({ ethnicity })
+const termsFor = (ethnicity: string[]) => buildPersonTerms({ ethnicity })
+
+describe("mixed heritage (two ethnicity picks)", () => {
+  it("names both heritages in full", () => {
+    expect(hintsFor(["slavic", "mediterranean"])).toContain(
+      "of mixed Slavic Eastern European and Mediterranean heritage",
+    )
+    expect(hintsFor(["pacific-islander", "east-asian"])).toContain("of mixed Pacific Islander and East Asian heritage")
+  })
+
+  it("never doubles the word heritage", () => {
+    expect(hintsFor(["brazilian", "west-african"])).toContain("of mixed Brazilian and West African heritage")
+  })
+
+  it("reads the same in compact mode", () => {
+    expect(termsFor(["slavic", "mediterranean"])).toContain("of mixed Slavic Eastern European and Mediterranean heritage")
+  })
+
+  it("treats 'mixed' paired with a specific pick as that pick", () => {
+    expect(hintsFor(["mixed", "italian"])).toEqual(hintsFor(["italian"]))
+  })
+
+  it("puts no short-label abbreviation into any two-pick phrase", () => {
+    // The short labels' tell-tales: an abbreviation dot ("Mediter.", "Isl."),
+    // "(any)" / a bare "any", and a region with no noun ("West", "East").
+    const bad = /\.|\(any\)|\bany\b|of mixed (West|East|Central|Southern) and/
+    // Paired with French, so French itself is the one entry left out.
+    const leaks = PEOPLE.filter((p) => p.dimension === "ethnicity" && p.id !== "mixed" && p.id !== "french")
+      .map((p) => `${p.id}: ${hintsFor([p.id, "french"]).find((h) => h.startsWith("of mixed")) ?? "(no phrase)"}`)
+      .filter((line) => bad.test(line.slice(line.indexOf(":") + 1)) || line.endsWith("(no phrase)"))
+    expect(leaks).toEqual([])
+  })
+})

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest"
-import { resolvePrompt, computeNodePrompt, computeLlmChatFields } from "../resolve-prompt.js"
+import { resolvePrompt, computeNodePrompt, computeLlmChatFields, computeScriptTopic } from "../resolve-prompt.js"
 const M = new Map<string, string>()
 const R = new Map([["Hero", "a knight"]])
 describe("resolvePrompt", () => {
@@ -42,3 +42,15 @@ describe("computeLlmChatFields", () => {
       { override: "o", wiredUserInput: "wu", wiredSystemPrompt: "ws", refMap: M }).userInput).toBe("o")
   })
 })
+describe("computeScriptTopic (generate-script)", () => {
+  it("the wired prompt wins over the saved `prompt`, the reverse of computeNodePrompt", () =>
+    expect(computeScriptTopic({ prompt: "saved" }, { wired: "wire", refMap: M })).toBe("wire"))
+  it("a list fan-out item wins over both", () =>
+    expect(computeScriptTopic({ prompt: "saved" }, { override: "row", wired: "wire", refMap: M })).toBe("row"))
+  it("falls back to the saved `prompt` and resolves its {Label}", () =>
+    expect(computeScriptTopic({ prompt: "{Hero}" }, { wired: "  ", refMap: R })).toBe("a knight"))
+  it("wraps the topic with the node's pre/post text", () =>
+    expect(computeScriptTopic({ promptPrefix: "A story:", promptSuffix: "The end." }, { wired: "a knight", refMap: M }))
+      .toBe("A story: a knight The end."))
+  it("nothing -> empty string", () => expect(computeScriptTopic({}, { refMap: M })).toBe(""))
+})

package/src/__tests__/transition-options.test.ts

@@ -0,0 +1,223 @@
+import { afterEach, describe, expect, it } from "vitest"
+import {
+  TRANSITIONS,
+  TRANSITION_OPTION_FIELDS,
+  WIPE_DIRECTION,
+  composeTransitionHintFromConnections,
+  getParameterPromptHint,
+  getPickerCatalog,
+  getTransitionOptions,
+  getTransitionPromptHint,
+  projectPickerCatalog,
+  readTransitionOptionValues,
+  registerCatalogPack,
+  renderTransitionBases,
+  resetCatalogPacks,
+} from "../index.js"
+
+afterEach(() => resetCatalogPacks())
+
+/** The rows with a Style option, in catalog order. */
+const STYLED_ROWS = [
+  "smoke-puff", "sand-storm", "aurora-sweep", "sakura-petals", "garden-bloom", "debris-shower", "white-flash",
+]
+const OPTIONED_ROWS = ["wipe", ...STYLED_ROWS]
+
+const BODY = (phrase: string) =>
+  `linear wipe (a clean ${phrase}, revealing the second shot behind it)`
+
+/** Every wipe direction, as the video prompt reads it — the approved wording. */
+const WIPE_BASES: Readonly<Record<string, string>> = {
+  auto: BODY("straight edge sweeps across the frame"),
+  "left-to-right": BODY("vertical edge sweeps across the frame from left to right"),
+  "right-to-left": BODY("vertical edge sweeps across the frame from right to left"),
+  "top-to-bottom": BODY("horizontal edge sweeps down the frame from top to bottom"),
+  "bottom-to-top": BODY("horizontal edge sweeps up the frame from bottom to top"),
+  "top-left-to-bottom-right": BODY(
+    "diagonal edge sweeps across the frame from the top-left corner to the bottom-right corner",
+  ),
+  "top-right-to-bottom-left": BODY(
+    "diagonal edge sweeps across the frame from the top-right corner to the bottom-left corner",
+  ),
+}
+
+describe("per-row transition options — the catalog", () => {
+  it("the wipe declares the direction; the styled rows share the style field", () => {
+    const withOptions = TRANSITIONS.filter((t) => t.options?.length)
+    expect(withOptions.map((t) => t.id)).toEqual(["wipe", ...STYLED_ROWS])
+    expect(getTransitionOptions("wipe")).toEqual([WIPE_DIRECTION])
+    for (const id of STYLED_ROWS) {
+      expect(getTransitionOptions(id).map((o) => o.field)).toEqual(["style"])
+    }
+    expect(TRANSITION_OPTION_FIELDS).toEqual(["wipeDirection", "style"])
+  })
+
+  it("a field is declared at most once per row", () => {
+    for (const t of TRANSITIONS) {
+      const fields = (t.options ?? []).map((o) => o.field)
+      expect(new Set(fields).size).toBe(fields.length)
+    }
+  })
+
+  it("the direction's choices: auto first, then the six approved directions", () => {
+    expect(WIPE_DIRECTION.choices.map((c) => c.id)).toEqual([
+      "auto",
+      "left-to-right",
+      "right-to-left",
+      "top-to-bottom",
+      "bottom-to-top",
+      "top-left-to-bottom-right",
+      "top-right-to-bottom-left",
+    ])
+    expect(WIPE_DIRECTION.choices[0]!.term).toBe("")
+  })
+
+  it("every template carries exactly one token per option and no other token", () => {
+    for (const t of TRANSITIONS) {
+      if (!t.promptTemplate) {
+        expect(t.options ?? []).toEqual([])
+        continue
+      }
+      const tokens = t.promptTemplate.match(/\{[^}]*\}/g) ?? []
+      expect(tokens.sort()).toEqual((t.options ?? []).map((o) => `{${o.field}}`).sort())
+    }
+  })
+
+  it("no promptHint carries a token — a plain reader always sees a sentence", () => {
+    for (const t of TRANSITIONS) expect(t.promptHint).not.toMatch(/[{}]/)
+  })
+
+  it("the wipe's promptHint IS its template on the auto choice", () => {
+    expect(getTransitionPromptHint("wipe")).toBe(
+      "linear wipe transition: a clean straight edge sweeps across the frame, revealing the second shot behind it",
+    )
+    expect(getTransitionPromptHint("wipe", { wipeDirection: "auto" })).toBe(
+      getTransitionPromptHint("wipe"),
+    )
+  })
+})
+
+describe("per-row transition options — the rendered wipe", () => {
+  it.each(Object.entries(WIPE_BASES))("%s", (direction, base) => {
+    const values = direction === "auto" ? undefined : { wipeDirection: direction }
+    expect(renderTransitionBases(["wipe"], "full", values)).toEqual([base])
+    expect(
+      composeTransitionHintFromConnections("wipe", [], [], undefined, "full", { optionValues: values }),
+    ).toBe(base)
+  })
+
+  it("the direction slots in ahead of the timing levers, in both scopes", () => {
+    const timing = { position: "middle", duration: "short", intensity: "natural" } as const
+    expect(
+      composeTransitionHintFromConnections("wipe", [], [], timing, "full", {
+        optionValues: { wipeDirection: "top-to-bottom" },
+      }),
+    ).toBe(
+      `${WIPE_BASES["top-to-bottom"]}, the transition occurs in the middle of the clip, ` +
+        "lasting approximately 1 second, with natural timing",
+    )
+    expect(
+      composeTransitionHintFromConnections("wipe", [], [], timing, "full", {
+        scope: "shot",
+        optionValues: { wipeDirection: "top-to-bottom" },
+      }),
+    ).toBe(
+      `${WIPE_BASES["top-to-bottom"]}, the transition occurs in the middle of this shot, ` +
+        "lasting approximately 1 second, with natural timing",
+    )
+  })
+
+  it("an unknown direction reads as auto — never a hole in the sentence", () => {
+    expect(renderTransitionBases(["wipe"], "full", { wipeDirection: "sideways" })).toEqual([
+      WIPE_BASES.auto,
+    ])
+  })
+
+  it("a row that declares no option ignores the value", () => {
+    for (const t of TRANSITIONS) {
+      if (t.options?.length) continue
+      expect(renderTransitionBases([t.id], "full", { wipeDirection: "left-to-right" })).toEqual(
+        renderTransitionBases([t.id]),
+      )
+    }
+  })
+
+  it("a two-pick writes the direction into the wipe only", () => {
+    expect(
+      composeTransitionHintFromConnections(["cross-dissolve", "wipe"], [], [], undefined, "full", {
+        optionValues: { wipeDirection: "right-to-left" },
+      }),
+    ).toBe(
+      `${renderTransitionBases(["cross-dissolve"])[0]}, and ${WIPE_BASES["right-to-left"]}`,
+    )
+  })
+
+  it("a catalog pack that REWRITES the wipe keeps its own words", () => {
+    const base = getPickerCatalog("transition")!
+    registerCatalogPack({
+      id: "t-wipe-rewrite",
+      catalogId: "transitions",
+      mode: "replace",
+      catalog: {
+        ...base,
+        options: base.options!.map((o) =>
+          o.id === "wipe" ? { ...o, promptHint: "curated wipe text" } : o,
+        ),
+      },
+    })
+    expect(getTransitionPromptHint("wipe", { wipeDirection: "left-to-right" })).toBe(
+      "curated wipe text",
+    )
+  })
+})
+
+describe("per-row transition options — the node data and the wire catalog", () => {
+  it("readTransitionOptionValues keeps declared, non-empty string fields only", () => {
+    expect(readTransitionOptionValues(undefined)).toBeUndefined()
+    expect(readTransitionOptionValues({ transition: "wipe" })).toBeUndefined()
+    expect(readTransitionOptionValues({ wipeDirection: "" })).toBeUndefined()
+    expect(
+      readTransitionOptionValues({ wipeDirection: "left-to-right", direction: "asc", other: 3 }),
+    ).toEqual({ wipeDirection: "left-to-right" })
+  })
+
+  it("a canvas transition node writes its wipeDirection", () => {
+    const node = (data: Record<string, unknown>) => ({ id: "t", type: "transition", data })
+    expect(getParameterPromptHint(node({ transition: "wipe", wipeDirection: "bottom-to-top" }))).toBe(
+      WIPE_BASES["bottom-to-top"],
+    )
+    expect(getParameterPromptHint(node({ transition: "wipe" }))).toBe(WIPE_BASES.auto)
+  })
+
+  it("the transition catalog publishes the direction as the wipe option's params", () => {
+    const options = getPickerCatalog("transition")!.options!
+    const wipe = options.find((o) => o.id === "wipe")!
+    expect(wipe.params).toEqual([
+      {
+        field: "wipeDirection",
+        label: "Direction",
+        options: WIPE_DIRECTION.choices.map((c) => ({
+          id: c.id,
+          label: c.label,
+          description: c.description,
+          promptHint: c.phrase,
+          term: c.term,
+        })),
+      },
+    ])
+    expect(options.filter((o) => o.params).map((o) => o.id)).toEqual(OPTIONED_ROWS)
+  })
+})
+
+describe("per-row transition options — the wire projection", () => {
+  it.each(["compact", "full"] as const)("the %s projection carries the wipe's params", (detail) => {
+    const projected = projectPickerCatalog(getPickerCatalog("transition")!, { detail })
+    const wipe = projected.options!.find((o) => o.id === "wipe")!
+    expect(wipe.params?.map((d) => d.field)).toEqual(["wipeDirection"])
+    expect(wipe.params![0]!.options.map((o) => o.id)).toEqual(WIPE_DIRECTION.choices.map((c) => c.id))
+    expect(wipe.params![0]!.options[1]!.promptHint).toBe(
+      detail === "full" ? "vertical edge sweeps across the frame from left to right" : undefined,
+    )
+    expect(projected.options!.filter((o) => o.params).map((o) => o.id)).toEqual(OPTIONED_ROWS)
+  })
+})

package/src/__tests__/transition-styles.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, it } from "vitest"
+import {
+  AURORA_SWEEP_STYLE,
+  DEBRIS_SHOWER_STYLE,
+  GARDEN_BLOOM_STYLE,
+  SAND_STORM_STYLE,
+  SAKURA_PETALS_STYLE,
+  SMOKE_PUFF_STYLE,
+  TRANSITIONS,
+  TRANSITION_STYLE_FIELD,
+  WHITE_FLASH_STYLE,
+  composeTransitionHintFromConnections,
+  getParameterPromptHint,
+  getTransitionOptions,
+  getTransitionPromptHint,
+  renderTransitionBases,
+} from "../index.js"
+
+/**
+ * THE STYLE OPTION — a row's alternative looks, each the text a tested take
+ * was generated from. `landed` is the transition clause EXACTLY as it sat in
+ * that take's prompt (the f1ab / f2ab / f3ab A/B rounds and the sandsweep2 redraft, tile-default levers,
+ * `scope: "shot"`); the catalog must render it byte for byte. The one planned
+ * difference is smoke-puff's Full cover: it was tested as an untidied draft
+ * (capital first letter, final full stop), and ships with the approved tidy.
+ */
+const TESTED: ReadonlyArray<{ row: string; style: string; take: string; landed: string }> = [
+  { row: "debris-shower", style: "auto", take: "f2ab 06-B 64f5537b",
+    landed: "debris shower (a dense shower of loose leaves, paper scraps and dust whips across the frame from one side, close to the lens, thick enough to hide the whole picture. The camera stays where it is and the framing does not change. As the last of the debris blows past the far edge, the second shot is revealed behind it. The shot ends on the second shot, clear and fully resolved, with no debris left. The debris passes in front of the picture in one direction, and the second shot appears only once it has passed)" },
+  { row: "debris-shower", style: "debris-shower-light-sweep", take: "f2ab 06-A 399ee116",
+    landed: "debris shower (a shower of debris — leaves, papers, dust — sweeps across the frame in front of the camera, and once the debris clears the scene behind has changed)" },
+  { row: "garden-bloom", style: "auto", take: "f2ab 04-A 583c84ec",
+    landed: "garden bloom (lush flowers and vines rapidly grow and bloom outward from the edges of the frame, the foliage spreads to overtake the entire image, then parts open like curtains to reveal the new scene behind)" },
+  { row: "garden-bloom", style: "garden-bloom-hedge-doors", take: "f2ab 04-B ebe96b89",
+    landed: "garden bloom (vines and flowers grow rapidly inward from the edges of the frame, blooming as they spread, until leaves and blossoms cover the whole picture. The camera stays where it is and the framing does not change. The foliage then splits down the middle and draws apart toward the side edges, opening onto the second shot behind it. The shot ends on the second shot, clear and fully resolved, with no leaves or flowers left. The plants grow over the front of the picture, and the first shot stays unchanged until they cover it completely)" },
+  { row: "sakura-petals", style: "auto", take: "f2ab 03-A 7e31da0d",
+    landed: "cherry blossom petal storm (a dense storm of cherry blossom petals swirls in from one side and fills the frame in soft pink motion, the petals cluster to fully veil the image, then drift past to reveal the new scene)" },
+  { row: "sakura-petals", style: "sakura-petals-side-sweep", take: "f2ab 03-B ae385f2f",
+    landed: "cherry blossom petal storm (a dense storm of pink cherry blossom petals swirls in from one side of the frame, close to the lens, and thickens until the petals veil the whole picture. The camera stays where it is and the framing does not change. The petals keep drifting the same way and thin out, revealing the second shot behind them. The shot ends on the second shot, clear and fully resolved, with no petals left. The petals fly across the front of the picture in one direction, and the first shot stays unchanged until they hide it completely)" },
+  { row: "aurora-sweep", style: "auto", take: "f2ab 07-B ab3dd61e",
+    landed: "aurora sweep (a luminous curtain of green and violet aurora light ripples across the whole frame, and its bright bands veil the first shot. The camera stays where it is and the framing does not change. As the bands fade, the second shot is revealed behind them. The shot ends on the second shot, clear and fully resolved, with no aurora light left. The aurora glows over the front of the picture, and the second shot appears only as it fades)" },
+  { row: "aurora-sweep", style: "aurora-sweep-veil", take: "f2ab 07-A 794058f2",
+    landed: "aurora sweep (a luminous green and violet aurora curtain ripples across the entire frame, the bright bands obscure the first scene, and as the aurora dissipates the second scene resolves in the clear sky)" },
+  { row: "smoke-puff", style: "auto", take: "f1ab 04-A 739d8c22",
+    landed: "smoke puff (the subject vanishes in a soft puff of smoke that billows outward and fills the frame, the smoke then clears to reveal the new subject in the new scene)" },
+  { row: "smoke-puff", style: "smoke-puff-full-cover", take: "f1ab 04-B 3a80fdfa",
+    landed: "smoke puff (The first subject vanishes in a sudden soft puff of smoke that billows outward from where it stood until the smoke fills the frame. The camera stays where it is and the framing does not change. The smoke thins and clears from the centre outward, revealing the second shot with the second subject at the same place in the frame. The shot ends on the second shot, clear and fully resolved, with no smoke left. The smoke comes only from where the first subject was.)" },
+  { row: "sand-storm", style: "auto", take: "f2ab 01-B bc5bf08d",
+    landed: "sand storm (a wall of opaque, swirling ochre sand sweeps in from one side of the frame and surges across it until the whole picture is hidden in dust. The camera stays where it is and the framing does not change. The dust then thins and sinks away toward the lower edge of the frame, revealing the second shot behind it. The shot ends on the second shot, clear and fully resolved, with no dust left. The first shot stays as it is until the sand covers it completely, and the second shot appears only as the dust clears)" },
+  { row: "sand-storm", style: "sand-storm-light-sweep", take: "sandsweep2 R1 64574737",
+    landed: "sand storm (a narrow streak of blown sand races across the frame close to the lens in one direction. The first shot stays clear ahead of the streak and the second shot is already clear behind it. The camera stays where it is and the framing does not change. The shot ends on the second shot, fully resolved, with no sand left)" },
+  { row: "white-flash", style: "auto", take: "f3ab 07-B 4e42fbe4",
+    landed: "white flash (a bright camera-flash bloom fills the whole frame with pure white. The camera stays where it is and the framing does not change. The white holds for a clear beat, then fades down to reveal the second shot. The shot ends on the second shot, fully resolved, with no white haze left. The first shot is gone once the frame is white, and the second shot appears only out of the white)" },
+  { row: "white-flash", style: "white-flash-overexposure", take: "f3ab 07-A f22e5913",
+    landed: "white flash (a bright camera-flash bloom fills the frame with pure white, holds for a fraction of a second, then resolves into the new scene)" },
+]
+
+/** The approved tidy: first letter lower-cased, a final full stop dropped. */
+const tidy = (clause: string): string =>
+  clause.replace(/\((.)/, (_, c: string) => `(${c.toLowerCase()}`).replace(/\.\)$/, ")")
+
+const values = (style: string) => (style === "auto" ? undefined : { style })
+
+const STYLES = {
+  "smoke-puff": SMOKE_PUFF_STYLE,
+  "sand-storm": SAND_STORM_STYLE,
+  "aurora-sweep": AURORA_SWEEP_STYLE,
+  "sakura-petals": SAKURA_PETALS_STYLE,
+  "garden-bloom": GARDEN_BLOOM_STYLE,
+  "debris-shower": DEBRIS_SHOWER_STYLE,
+  "white-flash": WHITE_FLASH_STYLE,
+} as const
+
+describe("transition Style — the rows and their choices", () => {
+  it("seven rows declare a Style, all on the one shared field", () => {
+    const styled = TRANSITIONS.filter((t) => t.options?.some((o) => o.field === TRANSITION_STYLE_FIELD))
+    expect(styled.map((t) => t.id)).toEqual(Object.keys(STYLES))
+    for (const [id, option] of Object.entries(STYLES)) {
+      expect(getTransitionOptions(id)).toEqual([option])
+      expect(TRANSITIONS.find((t) => t.id === id)!.promptTemplate).toBe("{style}")
+    }
+  })
+
+  it("the default look is `auto`, labelled by its own name — never \"Auto\"", () => {
+    const labels = Object.fromEntries(
+      Object.entries(STYLES).map(([id, o]) => [id, o.choices.map((c) => `${c.id}=${c.label}`)]),
+    )
+    expect(labels).toEqual({
+      "smoke-puff": ["auto=Engulf (default)", "smoke-puff-full-cover=Full cover"],
+      "sand-storm": ["auto=Full cover (default)", "sand-storm-light-sweep=Light sweep"],
+      "aurora-sweep": ["auto=Sky glow (default)", "aurora-sweep-veil=Veil"],
+      "sakura-petals": ["auto=Swirling veil (default)", "sakura-petals-side-sweep=Side sweep"],
+      "garden-bloom": ["auto=Grow & part (default)", "garden-bloom-hedge-doors=Hedge doors"],
+      "debris-shower": ["auto=Full cover (default)", "debris-shower-light-sweep=Light sweep"],
+      "white-flash": ["auto=Flash (default)", "white-flash-overexposure=Overexposure"],
+    })
+  })
+
+  it("every choice but auto is prefixed with its row's id, so no id means anything on two rows", () => {
+    const seen = new Set<string>()
+    for (const [id, option] of Object.entries(STYLES)) {
+      for (const c of option.choices.slice(1)) {
+        expect(c.id.startsWith(`${id}-`)).toBe(true)
+        expect(seen.has(c.id)).toBe(false)
+        seen.add(c.id)
+      }
+      for (const c of option.choices) expect(c.term).toBe("")
+    }
+  })
+
+  it("every body is ship-tidy: lower-case first letter, no final full stop, no token", () => {
+    for (const option of Object.values(STYLES)) {
+      for (const c of option.choices) {
+        expect(c.phrase[0]).toBe(c.phrase[0]!.toLowerCase())
+        expect(c.phrase).not.toMatch(/[.\s]$/)
+        expect(c.phrase).not.toMatch(/[{}]/)
+      }
+    }
+  })
+
+  it("a styled row's plain promptHint IS its default look", () => {
+    for (const [id, option] of Object.entries(STYLES)) {
+      expect(getTransitionPromptHint(id)).toBe(option.choices[0]!.phrase)
+    }
+  })
+})
+
+describe("transition Style — the rendered text is the tested text", () => {
+  it("every row × style has a tested take", () => {
+    const covered = TESTED.map((t) => `${t.row}|${t.style}`).sort()
+    const declared = Object.entries(STYLES)
+      .flatMap(([id, o]) => o.choices.map((c) => `${id}|${c.id}`))
+      .sort()
+    expect(covered).toEqual(declared)
+  })
+
+  it.each(TESTED.map((t) => [`${t.row} · ${t.style} (${t.take})`, t] as const))("%s", (_, t) => {
+    const rendered = composeTransitionHintFromConnections(t.row, [], [], {}, "full", {
+      scope: "shot",
+      optionValues: values(t.style),
+    })
+    const planned = t.row === "smoke-puff" && t.style !== "auto" ? tidy(t.landed) : t.landed
+    expect(rendered).toBe(planned)
+  })
+
+  it("smoke-puff's Full cover differs from its take only by the approved tidy", () => {
+    const t = TESTED.find((x) => x.row === "smoke-puff" && x.style !== "auto")!
+    expect(t.landed).not.toBe(tidy(t.landed))
+    expect(t.landed.replace(/\.\)$/, ")").toLowerCase()).toBe(tidy(t.landed).toLowerCase())
+  })
+
+  it("the levers follow the style's body unchanged", () => {
+    for (const t of TESTED) {
+      const base = renderTransitionBases([t.row], "full", values(t.style))[0]!
+      expect(
+        composeTransitionHintFromConnections(
+          t.row, [], [], { position: "middle", duration: "short", intensity: "natural" }, "full",
+          { optionValues: values(t.style) },
+        ),
+      ).toBe(
+        `${base}, the transition occurs in the middle of the clip, lasting approximately 1 second, with natural timing`,
+      )
+    }
+  })
+
+  it("compact renders the same `term (body)` — the row's term leads every style", () => {
+    for (const t of TESTED) {
+      expect(
+        composeTransitionHintFromConnections(t.row, [], [], {}, "compact", { optionValues: values(t.style) }),
+      ).toBe(renderTransitionBases([t.row], "full", values(t.style))[0])
+    }
+  })
+
+  it("another row's style — or none, or auto — reads as the row's default look", () => {
+    const light = { style: "debris-shower-light-sweep" }
+    for (const id of ["garden-bloom", "smoke-puff", "aurora-sweep", "sakura-petals"]) {
+      expect(renderTransitionBases([id], "full", light)).toEqual(renderTransitionBases([id]))
+    }
+    expect(renderTransitionBases(["debris-shower"], "full", { style: "auto" })).toEqual(
+      renderTransitionBases(["debris-shower"]),
+    )
+    expect(renderTransitionBases(["debris-shower"], "full", { style: "light-sweep" })).toEqual(
+      renderTransitionBases(["debris-shower"]),
+    )
+  })
+
+  it("a canvas transition node writes its style", () => {
+    const node = (data: Record<string, unknown>) => ({ id: "t", type: "transition", data })
+    const light = TESTED.find((t) => t.style === "debris-shower-light-sweep")!
+    expect(
+      getParameterPromptHint(node({ transition: "debris-shower", style: "debris-shower-light-sweep" })),
+    ).toBe(light.landed)
+  })
+
+  it("a two-pick writes the style into its own row only", () => {
+    const hedge = { style: "garden-bloom-hedge-doors" }
+    expect(renderTransitionBases(["debris-shower", "garden-bloom"], "full", hedge)).toEqual([
+      renderTransitionBases(["debris-shower"])[0],
+      renderTransitionBases(["garden-bloom"], "full", hedge)[0],
+    ])
+  })
+})