@nodaro/prompts 1.27.0 → 1.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.27.0",
+  "version": "1.28.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": "^3.14.0"
+    "@nodaro/shared": "^3.15.0"
   },
   "devDependencies": {
     "tsup": "^8.5.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)
+  })
+})