@nodaro/prompts 1.9.0 → 1.11.0

package/package.json

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

package/src/__tests__/assemble-image-input.test.ts

@@ -3,6 +3,10 @@ import { assembleImageInput } from "../assemble-image-input.js"
 import { buildImagePrompt } from "../prompt-builder.js"
 import { getFramingPromptHint } from "../framing.js"
 import { getLightingPromptHint } from "../lighting.js"
+import { getLensPromptHint } from "../lens.js"
+import { getCameraFormatPromptHint } from "../camera-format.js"
+import { getStylePromptHint } from "../style.js"
+import { buildMoodHints } from "../mood.js"
 import type { ConnectedReference } from "@nodaro/shared"
 
 /**
@@ -11,9 +15,9 @@ import type { ConnectedReference } from "@nodaro/shared"
  * `generate-image` assembly through it. These tests pin BOTH layers:
  *   (a) the id-based composition (direction / structured) — ported from
  *       Studio's `assembly.test.ts` as the oracle, and
- *   (b) the BY-CONSTRUCTION PARITY the caller refactor relies on: with no
- *       direction/structured, the wrapper === the old inline `buildImagePrompt`
- *       call + empty-check, byte-for-byte.
+ *   (b) the BY-CONSTRUCTION PARITY the caller refactor relies on: for a node
+ *       that carries no direction/structured, the wrapper === the old inline
+ *       `buildImagePrompt` call + empty-check, byte-for-byte.
  */
 
 // flux-2-max supports reference images (used to assert refs survive the gate).
@@ -93,6 +97,92 @@ describe("assembleImageInput — id-based composition (Studio oracle)", () => {
     })
     expect(result.prompt).toBe("a portrait. Subject: 30 years old, woman, calm expression.")
   })
+
+  // ── The direction registry (the fold moved into `direction-registry.ts`) ──
+
+  it("returns the prompt VERBATIM and UNTRIMMED for a direction that renders nothing", () => {
+    // The no-op branch is what the platform-caller parity contract rests on: an
+    // empty (or all-empty-valued) `direction` must not trip the join, or the
+    // prompt would silently get trimmed.
+    for (const direction of [{}, { style: "" }, { mood: [] }, { style: "__no_such_style__" }]) {
+      const result = assembleImageInput({
+        userPrompt: "  a knight \n",
+        provider: REF_PROVIDER,
+        direction,
+      })
+      expect(result.prompt).toBe("  a knight \n")
+    }
+  })
+
+  it("folds a registry key that predates no legacy field (style) end to end", () => {
+    const result = assembleImageInput({
+      userPrompt: "a knight",
+      provider: REF_PROVIDER,
+      direction: { style: "anime" },
+    })
+    expect(result.prompt).toBe(`a knight. ${getStylePromptHint("anime")}`)
+  })
+
+  it("blends a multi-pick dimension into ONE clause", () => {
+    const blended = buildMoodHints({ mood: ["happy", "joyful"] }, "full")
+    expect(blended).toHaveLength(1)
+    const result = assembleImageInput({
+      userPrompt: "a knight",
+      provider: REF_PROVIDER,
+      direction: { mood: ["happy", "joyful"] },
+    })
+    expect(result.prompt).toBe(`a knight. ${blended[0]}`)
+  })
+
+  it("folds in TABLE order, not the caller's object-literal order", () => {
+    const result = assembleImageInput({
+      userPrompt: "a knight",
+      provider: REF_PROVIDER,
+      direction: { style: "anime", shotSize: "wide-shot" },
+    })
+    expect(result.prompt).toBe(
+      `a knight. ${getFramingPromptHint("wide-shot")}. ${getStylePromptHint("anime")}`,
+    )
+  })
+
+  it("keeps the five pre-registry keys byte-identical to the old inlined fold", () => {
+    const direction = {
+      framingId: "wide-shot",
+      framingAngleId: "low-angle",
+      lightingId: "golden-hour",
+      lensId: "wide-24mm",
+      cameraFormatId: "16mm-film",
+    }
+    const result = assembleImageInput({
+      userPrompt: "a knight",
+      provider: REF_PROVIDER,
+      direction,
+    })
+    // The exact string the pre-registry `composePromptText` produced: the same
+    // five clauses, in the same order, joined with the same ". ".
+    expect(result.prompt).toBe(
+      [
+        "a knight",
+        getFramingPromptHint("wide-shot"),
+        getFramingPromptHint("low-angle"),
+        getLightingPromptHint("golden-hour"),
+        getLensPromptHint("wide-24mm"),
+        getCameraFormatPromptHint("16mm-film"),
+      ].join(". "),
+    )
+  })
+
+  it("keeps the structured fragment LAST, after every direction clause", () => {
+    const result = assembleImageInput({
+      userPrompt: "a portrait",
+      provider: REF_PROVIDER,
+      direction: { style: "anime" },
+      structured: { person: { age: 30, gender: "woman", expression: "calm" } },
+    })
+    expect(result.prompt).toBe(
+      `a portrait. ${getStylePromptHint("anime")}. Subject: 30 years old, woman, calm expression.`,
+    )
+  })
 })
 
 describe("assembleImageInput — empty-prompt throw (opt-in)", () => {

package/src/__tests__/assemble-video-input.test.ts

@@ -0,0 +1,301 @@
+import { describe, it, expect } from "vitest"
+import { composeVideoPromptText } from "../assemble-video-input.js"
+import { directionFieldsForSurface } from "../direction-registry.js"
+import { getStylePromptHint, getStyleTerm } from "../style.js"
+import { getTransitionPromptHint, getTransitionTerm } from "../transitions.js"
+import { getCameraMotionPromptHint, getCameraMotionTerm } from "../camera-motions.js"
+import { getFramingPromptHint } from "../framing.js"
+import { getLightingPromptHint } from "../lighting.js"
+import { buildMoodHints } from "../mood.js"
+import { buildAestheticHints } from "../aesthetic.js"
+import { buildAtmosphereHints } from "../atmosphere.js"
+import { buildPhotographerHints } from "../photographer.js"
+import { renderStructuredFields } from "../prompt-builder-structured-fields.js"
+
+/**
+ * `composeVideoPromptText` is the video route's ONLY prompt-composition step,
+ * so two contracts matter here above everything else:
+ *
+ *  1. THE NO-OP CONTRACT — with no direction the caller's prompt comes back
+ *     verbatim and untrimmed, `undefined` included. This is the local
+ *     restatement of the route-level byte-parity oracle ("backward-compatible:
+ *     no connectedReferences → prompt + flat refs pass through unchanged" in
+ *     `backend/src/routes/__tests__/generate-video.test.ts`), and it is what
+ *     makes this whole leg land dark.
+ *  2. THE VERBOSITY POLICY — look dimensions render their full clause, motion
+ *     dimensions their compact professional term. That split moved from the
+ *     client to the platform, so it is pinned in both directions.
+ *
+ * Real catalog ids throughout: every `get*PromptHint` returns `""` on a miss,
+ * so a made-up id would make most assertions vacuously pass.
+ */
+
+// ── Real ids, one per dimension used below ──────────────────────────────────
+const STYLE = "cinematic" // look
+const TRANSITION = "cross-dissolve" // motion
+const CAMERA_MOTION = "handheld" // motion
+const SHOT_SIZE = "wide-shot" // look, framing catalog
+const TIME_OF_DAY = "dawn" // look, lighting catalog (time-of-day category)
+const LIGHTING_STYLE = "three-point" // look, lighting catalog (style category)
+const PHOTOGRAPHER = "tim-walker" // IMAGE-ONLY dimension
+const NO_SUCH_ID = "__no_such_id__"
+
+describe("composeVideoPromptText — the no-op contract", () => {
+  it("returns a prompt verbatim when no direction is passed", () => {
+    expect(composeVideoPromptText("a knight rides at dusk", undefined)).toBe(
+      "a knight rides at dusk",
+    )
+  })
+
+  it("returns a whitespace-only prompt verbatim and UNTRIMMED", () => {
+    expect(composeVideoPromptText("  \n", undefined)).toBe("  \n")
+  })
+
+  it("preserves `undefined` (the video prompt is optional)", () => {
+    expect(composeVideoPromptText(undefined, undefined)).toBeUndefined()
+  })
+
+  it("treats an empty direction object as no direction", () => {
+    expect(composeVideoPromptText("a knight", {})).toBe("a knight")
+    expect(composeVideoPromptText(undefined, {})).toBeUndefined()
+  })
+})
+
+describe("composeVideoPromptText — the verbosity policy", () => {
+  it("renders a LOOK dimension as its full clause", () => {
+    expect(composeVideoPromptText("a knight", { style: STYLE })).toBe(
+      `a knight. ${getStylePromptHint(STYLE)}`,
+    )
+  })
+
+  it("renders a MOTION dimension as its compact term, not its full hint", () => {
+    const out = composeVideoPromptText("a knight", { transition: TRANSITION })
+    expect(out).toBe(`a knight. ${getTransitionTerm(TRANSITION)}`)
+    expect(out).not.toContain(getTransitionPromptHint(TRANSITION))
+  })
+
+  it("applies both halves of the split policy in ONE fold", () => {
+    const out = composeVideoPromptText("a knight", {
+      style: STYLE,
+      transition: TRANSITION,
+    })
+    expect(out).toContain(getStylePromptHint(STYLE))
+    expect(out).toContain(getTransitionTerm(TRANSITION))
+    expect(out).not.toContain(getTransitionPromptHint(TRANSITION))
+  })
+
+  it("honors a whole-fold `hintMode` override in both directions", () => {
+    // "full" promotes the motion family to its full clause…
+    expect(
+      composeVideoPromptText("a knight", { transition: TRANSITION }, undefined, {
+        hintMode: "full",
+      }),
+    ).toBe(`a knight. ${getTransitionPromptHint(TRANSITION)}`)
+    // …and "compact" demotes the look family to its term.
+    expect(
+      composeVideoPromptText("a knight", { style: STYLE }, undefined, {
+        hintMode: "compact",
+      }),
+    ).toBe(`a knight. ${getStyleTerm(STYLE)}`)
+  })
+})
+
+describe("composeVideoPromptText — ordering", () => {
+  it("puts camera motion first (the order Studio and the orchestrator both emit)", () => {
+    const out = composeVideoPromptText("a knight", {
+      style: STYLE,
+      cameraMotion: CAMERA_MOTION,
+    })!
+    expect(out.indexOf(getCameraMotionTerm(CAMERA_MOTION))).toBeLessThan(
+      out.indexOf(getStylePromptHint(STYLE)),
+    )
+    // Compact motion again — the camera-motion row is `family: "motion"`.
+    expect(out).not.toContain(getCameraMotionPromptHint(CAMERA_MOTION))
+  })
+
+  it("folds in TABLE order, not the caller's object order", () => {
+    // `shotSize` (row 2) precedes `style` (row 22) however the object is written.
+    const out = composeVideoPromptText("a knight", {
+      style: STYLE,
+      shotSize: SHOT_SIZE,
+    })!
+    expect(out.indexOf(getFramingPromptHint(SHOT_SIZE))).toBeLessThan(
+      out.indexOf(getStylePromptHint(STYLE)),
+    )
+  })
+
+  it("appends the structured fragment AFTER every direction hint", () => {
+    const structured = { mood: "wistful" }
+    const fragment = renderStructuredFields(structured)
+    expect(fragment.length).toBeGreaterThan(0)
+    const out = composeVideoPromptText("a knight", { style: STYLE }, structured)!
+    expect(out).toBe(`a knight. ${getStylePromptHint(STYLE)}. ${fragment}`)
+  })
+})
+
+describe("composeVideoPromptText — multi-pick doctrine", () => {
+  it("BLENDS two moods into ONE clause (not a per-id loop)", () => {
+    const blended = buildMoodHints({ mood: ["happy", "serene"] }, "full")
+    expect(blended).toHaveLength(1)
+    expect(composeVideoPromptText("a knight", { mood: ["happy", "serene"] })).toBe(
+      `a knight. ${blended[0]}`,
+    )
+  })
+
+  it("BLENDS two aesthetics into ONE clause", () => {
+    const blended = buildAestheticHints(["y2k", "cottagecore"], "full")
+    expect(blended.length).toBeGreaterThan(0)
+    expect(
+      composeVideoPromptText("a knight", { aesthetic: ["y2k", "cottagecore"] }),
+    ).toBe(`a knight. ${blended}`)
+  })
+
+  it("slices an over-cap array to the dimension's maxPicks (atmosphere = 2)", () => {
+    const out = composeVideoPromptText("a knight", {
+      atmosphere: ["clear", "cloudy", "overcast"],
+    })!
+    const kept = buildAtmosphereHints(["clear", "cloudy"], "full")
+    expect(kept).toHaveLength(2)
+    expect(out).toBe(`a knight. ${kept.join(". ")}`)
+    expect(out).not.toContain(buildAtmosphereHints("overcast", "full")[0])
+  })
+
+  it("accepts an ARRAY on a single-pick key and keeps the first id", () => {
+    // The legacy `V2LookPicker` shape: a single-pick dimension that stored an
+    // array. Must degrade to one hint, never throw and never drop the key.
+    const out = composeVideoPromptText("a knight", { style: [STYLE, "anime"] })
+    expect(out).toBe(`a knight. ${getStylePromptHint(STYLE)}`)
+  })
+})
+
+describe("composeVideoPromptText — tolerance", () => {
+  it("skips an unknown id and leaves the prompt verbatim (no dangling '. ')", () => {
+    expect(composeVideoPromptText("a knight", { style: NO_SUCH_ID })).toBe("a knight")
+  })
+
+  it("skips an IMAGE-ONLY dimension sent to a video run", () => {
+    // `photographer` is accepted on the wire (surface is a render concern, not
+    // a wire concern) and simply contributes nothing here.
+    expect(buildPhotographerHints(PHOTOGRAPHER, "full").length).toBeGreaterThan(0)
+    expect(composeVideoPromptText("a knight", { photographer: PHOTOGRAPHER })).toBe(
+      "a knight",
+    )
+  })
+
+  it("skips an unknown wire key entirely", () => {
+    expect(
+      composeVideoPromptText("a knight", { __not_a_dimension__: "x" } as never),
+    ).toBe("a knight")
+  })
+})
+
+describe("composeVideoPromptText — an empty or absent body", () => {
+  it("returns the hints alone for an empty prompt (never a leading '. ')", () => {
+    expect(composeVideoPromptText("", { style: STYLE })).toBe(getStylePromptHint(STYLE))
+  })
+
+  it("returns the hints alone for an ABSENT prompt", () => {
+    expect(composeVideoPromptText(undefined, { style: STYLE })).toBe(
+      getStylePromptHint(STYLE),
+    )
+  })
+})
+
+describe("composeVideoPromptText — the dedupe invariant", () => {
+  // The five legacy keys address a WHOLE catalog, so they are not aliases of
+  // their canonical counterparts. Overlap is resolved by exact-clause dedupe,
+  // which suppresses a repeated clause without suppressing a different id.
+  it("emits ONE clause when a legacy and a canonical key carry the SAME id", () => {
+    expect(
+      composeVideoPromptText("a knight", { framingId: SHOT_SIZE, shotSize: SHOT_SIZE }),
+    ).toBe(`a knight. ${getFramingPromptHint(SHOT_SIZE)}`)
+  })
+
+  it("emits BOTH clauses for two DIFFERENT ids of one catalog", () => {
+    // The case an alias table would have wrongly collapsed: `lightingId` is
+    // whole-catalog, so a time-of-day pick beside a lighting-style pick is two
+    // legitimate selections.
+    const out = composeVideoPromptText("a knight", {
+      lightingStyle: LIGHTING_STYLE,
+      lightingId: TIME_OF_DAY,
+    })
+    expect(out).toBe(
+      `a knight. ${getLightingPromptHint(LIGHTING_STYLE)}. ${getLightingPromptHint(TIME_OF_DAY)}`,
+    )
+  })
+})
+
+/**
+ * ORDER TOTALITY — every video-surface dimension, folded in one call.
+ *
+ * The fixture is keyed in `directionFieldsForSurface("video")` order and pinned
+ * against it, so adding, removing or reordering a video row fails HERE as well
+ * as in the registry test. Each id was chosen to render a clause distinct from
+ * every other row's, so the dedupe pass cannot mask a mis-ordering.
+ */
+const EVERY_VIDEO_DIMENSION: Record<string, string> = {
+  cameraMotion: "static",
+  shotSize: "extreme-wide-shot",
+  angle: "eye-level",
+  coverage: "single",
+  composition: "rule-of-thirds",
+  vantage: "front-on",
+  pose: "standing-upright",
+  compositionEffect: "bursting-through-frame",
+  cameraFormat: "35mm-film",
+  lens: "ultra-wide-14mm",
+  timeOfDay: "dawn",
+  lightingStyle: "three-point",
+  lightingDirection: "front",
+  lightingRatio: "ratio-1-1",
+  colorTemperature: "temp-2700k",
+  colorLook: "warm",
+  atmosphere: "clear",
+  style: "3d-render",
+  mood: "happy",
+  aesthetic: "y2k",
+  setting: "coffee-shop",
+  era: "1920s-flapper",
+  backdrop: "white-seamless",
+  actionFx: "earthquake-tremor",
+  temporalSpeed: "real-time",
+  temporalFreeze: "full-freeze",
+  temporalDirection: "forward",
+  temporalShutter: "long-exposure",
+  transition: "none",
+  loopSubject: "aurora",
+  framingId: "wide-shot",
+  framingAngleId: "medium-wide-shot",
+  lightingId: "sunrise",
+  lensId: "wide-24mm",
+  cameraFormatId: "16mm-film",
+}
+
+describe("composeVideoPromptText — order totality over every video dimension", () => {
+  it("covers exactly the video surface, in table order", () => {
+    expect(Object.keys(EVERY_VIDEO_DIMENSION)).toEqual(
+      directionFieldsForSurface("video").map((f) => f.key),
+    )
+  })
+
+  it("resolves every fixture id to a real clause", () => {
+    for (const [key, id] of Object.entries(EVERY_VIDEO_DIMENSION)) {
+      expect(composeVideoPromptText("", { [key]: id }), `${key}=${id}`).not.toBe("")
+    }
+  })
+
+  it("folds all 35 dimensions in registry order, one clause each", () => {
+    // Per-dimension renders, composed in isolation through the same public
+    // entry point, then concatenated in table order: the whole fold must equal
+    // exactly that. Any reorder, drop or duplicate shows up as a diff.
+    const expected = Object.entries(EVERY_VIDEO_DIMENSION).map(
+      ([key, id]) => composeVideoPromptText("", { [key]: id })!,
+    )
+    expect(new Set(expected).size, "fixture ids must render distinct clauses").toBe(
+      expected.length,
+    )
+    expect(composeVideoPromptText("a knight", EVERY_VIDEO_DIMENSION)).toBe(
+      ["a knight", ...expected].join(". "),
+    )
+  })
+})

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

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