@nodaro/prompts 1.26.0 → 1.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.26.0",
+  "version": "1.27.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.13.0"
+    "@nodaro/shared": "^3.14.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

package/src/__tests__/picker-art-images.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Picker pictures over the API: every option that has a picture gets exactly
+ * one absolute `imageUrl`, built from the installation's base URL (or, for
+ * the rendered look previews, the Nodaro CDN — Cloud only); every option
+ * without one gets none; the Person / Styling topics carry their pictures;
+ * and the directory's `imageCount` agrees with what the detail call returns.
+ */
+import { describe, it, expect } from "vitest"
+import {
+  LOOK_PREVIEW_SETS,
+  PERSON_DIMENSION_SECTIONS,
+  PERSON_FIELD_BY_DIMENSION,
+  STYLING_DIMENSION_ORDER,
+  STYLING_DIMENSION_SECTIONS,
+  STYLING_FIELD_BY_DIMENSION,
+  characterArtPath,
+  getRegisteredPickerCatalogs,
+  lookPreviewStillUrl,
+  pickerOptionImageUrl,
+  projectPickerCatalog,
+  soundArtPath,
+  summarizePickerCatalogs,
+  type PickerCatalog,
+  type PickerImageOptions,
+} from "../index.js"
+import type { ProjectedCatalogOption } from "@nodaro/shared"
+
+const CLOUD: PickerImageOptions = { baseUrl: "https://app.nodaro.ai", lookPreviews: true }
+const COMMUNITY: PickerImageOptions = { baseUrl: "http://localhost:3000", lookPreviews: false }
+
+/** Every projected option of a catalog with the dimension field it belongs to. */
+function projectedOptions(c: PickerCatalog, images?: PickerImageOptions) {
+  const p = projectPickerCatalog(c, { images })
+  return [
+    ...(p.options ?? []).map((option) => ({ field: c.valueField, option })),
+    ...(p.dimensions ?? []).flatMap((d) => d.options.map((option) => ({ field: d.field as string | undefined, option }))),
+  ] as ReadonlyArray<{ field: string | undefined; option: ProjectedCatalogOption }>
+}
+
+/** The picture an option should get, from the art maps directly (independent of the projection). */
+function expectedUrl(c: PickerCatalog, field: string | undefined, id: string, images: PickerImageOptions): string | undefined {
+  const own = characterArtPath(c.catalogId, id) ?? (field ? soundArtPath(c.catalogId, field, id) : undefined)
+  if (own) return images.baseUrl.replace(/\/+$/, "") + own
+  if (!images.lookPreviews) return undefined
+  const render = (LOOK_PREVIEW_SETS as Readonly<Record<string, Readonly<Record<string, string>>>>)[c.nodeType]?.[id]
+  return render ? lookPreviewStillUrl(render) : undefined
+}
+
+const CATALOGS = getRegisteredPickerCatalogs()
+
+describe("picker option imageUrl", () => {
+  it.each([["Cloud", CLOUD], ["a self-hosted install", COMMUNITY]] as const)(
+    "on %s, every option gets exactly its picture (or none)",
+    (_, images) => {
+      const wrong: string[] = []
+      for (const c of CATALOGS) {
+        for (const { field, option } of projectedOptions(c, images)) {
+          const expected = expectedUrl(c, field, option.id, images)
+          if (option.imageUrl !== expected) wrong.push(`${c.nodeType}.${field}.${option.id}: ${option.imageUrl} ≠ ${expected}`)
+          if (expected === undefined && "imageUrl" in option) wrong.push(`${c.nodeType}.${option.id}: an empty imageUrl key`)
+        }
+      }
+      expect(wrong).toEqual([])
+    },
+  )
+
+  it("self-hosted pictures are absolute on the installation's own host", () => {
+    for (const images of [CLOUD, COMMUNITY]) {
+      const own = CATALOGS.flatMap((c) => projectedOptions(c, images))
+        .map(({ option }) => option.imageUrl)
+        .filter((u): u is string => u !== undefined && !u.startsWith("https://cdn.nodaro.ai/"))
+      expect(own.length).toBeGreaterThan(1000)
+      expect(own.filter((u) => !u.startsWith(`${images.baseUrl}/picker-art/`))).toEqual([])
+      expect(own.filter((u) => !/\.[0-9a-f]{8}\.webp$/.test(u))).toEqual([])
+    }
+  })
+
+  it("a self-hosted install never gets a Nodaro CDN picture; Cloud does, for the look pickers", () => {
+    const hostsOf = (images: PickerImageOptions) =>
+      new Set(
+        CATALOGS.flatMap((c) => projectedOptions(c, images))
+          .map(({ option }) => option.imageUrl)
+          .filter((u): u is string => u !== undefined)
+          .map((u) => new URL(u).host),
+      )
+    expect([...hostsOf(COMMUNITY)]).toEqual(["localhost:3000"])
+    expect([...hostsOf(CLOUD)].sort()).toEqual(["app.nodaro.ai", "cdn.nodaro.ai"])
+    const mood = projectPickerCatalog(CATALOGS.find((c) => c.nodeType === "mood")!, { images: CLOUD })
+    expect(mood.options?.every((o) => o.imageUrl?.startsWith("https://cdn.nodaro.ai/cdn-cgi/image/width=480,"))).toBe(true)
+  })
+
+  it("a camera-motion clip is pictured by a still frame, never the video", () => {
+    const cm = projectPickerCatalog(CATALOGS.find((c) => c.nodeType === "camera-motion")!, { images: CLOUD })
+    const urls = (cm.options ?? []).map((o) => o.imageUrl).filter((u): u is string => u !== undefined)
+    expect(urls.length).toBeGreaterThan(0)
+    expect(urls.every((u) => u.includes("/cdn-cgi/media/mode=frame,") || u.includes("/cdn-cgi/image/"))).toBe(true)
+  })
+
+  it("a trailing slash on the base URL does not double the slash", () => {
+    const withSlash = pickerOptionImageUrl({ nodeType: "person", catalogId: "person" }, "type", "man", { baseUrl: "http://localhost:3000/" })
+    expect(withSlash).toBe(pickerOptionImageUrl({ nodeType: "person", catalogId: "person" }, "type", "man", COMMUNITY))
+    expect(withSlash).toMatch(/^http:\/\/localhost:3000\/picker-art\/character\/person\/man\.[0-9a-f]{8}\.webp$/)
+  })
+
+  it("an unusable base URL yields no picture rather than a broken one", () => {
+    for (const baseUrl of ["", "not a url", "javascript:alert(1)", "ftp://host"]) {
+      expect(pickerOptionImageUrl({ nodeType: "person", catalogId: "person" }, "type", "man", { baseUrl })).toBeUndefined()
+    }
+  })
+
+  it("without picture options, no option carries an imageUrl", () => {
+    const any = CATALOGS.flatMap((c) => projectedOptions(c)).filter(({ option }) => "imageUrl" in option)
+    expect(any).toEqual([])
+  })
+
+  it("imageUrl rides at both detail levels", () => {
+    const person = CATALOGS.find((c) => c.nodeType === "person")!
+    for (const detail of ["compact", "full"] as const) {
+      const man = projectPickerCatalog(person, { detail, images: CLOUD }).dimensions?.[0]?.options.find((o) => o.id === "man")
+      expect(man?.imageUrl).toMatch(/\/picker-art\/character\/person\/man\./)
+    }
+  })
+})
+
+describe("picker catalog sections (Person, Styling)", () => {
+  it("person returns its topics, as fields, each with its round picture", () => {
+    const p = projectPickerCatalog(CATALOGS.find((c) => c.nodeType === "person")!, { images: CLOUD })
+    expect(p.sections?.map((s) => s.label)).toEqual(PERSON_DIMENSION_SECTIONS.map((s) => s.label))
+    expect(p.sections?.[0]).toEqual({
+      label: "Identity",
+      fields: PERSON_DIMENSION_SECTIONS[0].dimensions.map((d) => PERSON_FIELD_BY_DIMENSION[d]),
+      imageUrl: expect.stringMatching(/^https:\/\/app\.nodaro\.ai\/picker-art\/character\/sections\/identity\.[0-9a-f]{8}\.webp$/),
+    })
+  })
+
+  it("styling returns its topics, as fields, each with its round picture", () => {
+    const p = projectPickerCatalog(CATALOGS.find((c) => c.nodeType === "styling")!, { images: COMMUNITY })
+    expect(p.sections?.map((s) => s.label)).toEqual(STYLING_DIMENSION_SECTIONS.map((s) => s.label))
+    for (const [i, section] of (p.sections ?? []).entries()) {
+      expect(section.fields).toEqual(STYLING_DIMENSION_SECTIONS[i].dimensions.map((d) => STYLING_FIELD_BY_DIMENSION[d]))
+      expect(section.imageUrl).toMatch(/^http:\/\/localhost:3000\/picker-art\/character\/sections\//)
+    }
+  })
+
+  it("every topic field is one of the catalog's dimensions", () => {
+    for (const nodeType of ["person", "styling"]) {
+      const p = projectPickerCatalog(CATALOGS.find((c) => c.nodeType === nodeType)!, {})
+      const fields = new Set((p.dimensions ?? []).map((d) => d.field))
+      expect(p.sections?.flatMap((s) => s.fields).filter((f) => !fields.has(f))).toEqual([])
+      expect(p.sections?.every((s) => !("imageUrl" in s))).toBe(true) // no pictures without picture options
+    }
+  })
+
+  it("other catalogs have no sections", () => {
+    const others = CATALOGS.filter((c) => c.nodeType !== "person" && c.nodeType !== "styling")
+    expect(others.filter((c) => projectPickerCatalog(c, { images: CLOUD }).sections !== undefined).map((c) => c.nodeType)).toEqual([])
+  })
+
+  it("STYLING_DIMENSION_SECTIONS lists every styling dimension exactly once", () => {
+    const listed = STYLING_DIMENSION_SECTIONS.flatMap((s) => s.dimensions)
+    expect(new Set(listed).size).toBe(listed.length)
+    expect([...listed].sort()).toEqual([...STYLING_DIMENSION_ORDER].sort())
+  })
+})
+
+describe("picker catalog directory imageCount", () => {
+  it.each([["Cloud", CLOUD], ["a self-hosted install", COMMUNITY]] as const)(
+    "on %s, imageCount is the number of options the detail call pictures",
+    (_, images) => {
+      const summaries = summarizePickerCatalogs({ images })
+      for (const c of CATALOGS) {
+        const pictured = projectedOptions(c, images).filter(({ option }) => option.imageUrl).length
+        expect(summaries.find((s) => s.nodeType === c.nodeType)?.imageCount, c.nodeType).toBe(pictured)
+      }
+    },
+  )
+
+  it("counts no picture without picture options", () => {
+    expect(summarizePickerCatalogs().every((s) => s.imageCount === 0)).toBe(true)
+  })
+
+  it("the character, music and voice pickers are pictured everywhere; the look pickers on Cloud only", () => {
+    const pictured = (images: PickerImageOptions) =>
+      new Set(summarizePickerCatalogs({ images }).filter((s) => s.imageCount > 0).map((s) => s.nodeType))
+    const everywhere = ["person", "styling", "held-prop", "material", "animal", "music-genre", "music-mood", "instrumentation", "voice-character", "voice-delivery"]
+    expect([...pictured(COMMUNITY)].sort()).toEqual([...everywhere].sort())
+    const cloud = pictured(CLOUD)
+    expect(everywhere.every((t) => cloud.has(t))).toBe(true)
+    for (const look of ["style", "mood", "lens", "framing", "lighting", "camera-motion"]) expect(cloud.has(look), look).toBe(true)
+  })
+})

package/src/__tests__/transitions-scope.test.ts

@@ -57,11 +57,8 @@ describe("approved row bodies", () => {
     )
   })
 
-  it("zoom-into-mouth drops only 'the throat'", () => {
-    expect(getTransitionPromptHint("zoom-into-mouth")).toBe(
-      "the camera pushes into the subject's open mouth, the dark interior fills the frame, and the camera passes " +
-        "through into the new scene which materialises as if emerging from inside the body",
-    )
+  it("zoom-into-mouth never mentions 'the throat' (its body is pinned in the F5 block below)", () => {
+    expect(getTransitionPromptHint("zoom-into-mouth")).not.toContain("throat")
   })
 })
 
@@ -123,6 +120,243 @@ describe("F1 bodies — the subject becomes the material and reforms (2026-09-25
   })
 })
 
+describe("F2 + vortex bodies (2026-09-25 A/B: F2 arm B, vortex rework D2)", () => {
+  // sand-storm, paint-splash and aurora-sweep: the F2 drafts, tidied (first letter lower-cased, final
+  // full stop dropped). vortex-swirl: the rework's D2 body, as tested. Each rendered string below is
+  // byte-identical to the clause the winning take was generated from.
+  const F2_BODIES: Record<string, { term: string; body: string }> = {
+    "sand-storm": {
+      term: "sand storm",
+      body:
+        "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",
+    },
+    "paint-splash": {
+      term: "paint splash",
+      body:
+        "vivid splashes of coloured paint fly across the frame in arcing streaks and pile over one another " +
+        "until the whole picture is covered in wet paint. The camera stays where it is and the framing does " +
+        "not change. The paint then gathers toward the centre of the frame and shrinks to nothing, uncovering" +
+        " the second shot from the edges inward. The shot ends on the second shot, clean and fully resolved, " +
+        "with no paint left. The paint lies on the surface of the picture itself, and the second shot appears" +
+        " only where the paint has gone",
+    },
+    "aurora-sweep": {
+      term: "aurora sweep",
+      body:
+        "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",
+    },
+    "vortex-swirl": {
+      term: "vortex swirl",
+      body:
+        "only the first subject twists, winding around its own centre like wrung cloth into a tight narrow " +
+        "column at the same place in the frame, turning faster as it narrows, while the surroundings stay " +
+        "upright and still. the camera is locked on a tripod head planted in one spot, holding the frame " +
+        "level from start to finish. the column then unwinds in the same direction and opens into the shape " +
+        "of the second subject, while the second shot appears around it. the shot ends on the second subject," +
+        " solid and fully resolved, with nothing left turning. the twist stays inside the outline of the " +
+        "subject, and the edges of the frame stay square and still",
+    },
+  }
+
+  it.each(Object.keys(F2_BODIES))("%s renders `term (body)` at the tile-default levers", (id) => {
+    const { term, body } = F2_BODIES[id]!
+    expect(getTransitionPromptHint(id)).toBe(body)
+    expect(composeTransitionHintFromConnections(id, [], [], {}, "full", { scope: "shot" })).toBe(`${term} (${body})`)
+  })
+
+  it.each(Object.keys(F2_BODIES))("%s at middle / short / natural", (id) => {
+    const { term, body } = F2_BODIES[id]!
+    expect(composeTransitionHintFromConnections(id, [], [], { position: "middle", duration: "short", intensity: "natural" })).toBe(
+      `${term} (${body}), the transition occurs in the middle of the clip, lasting approximately 1 second, with natural timing`,
+    )
+  })
+})
+
+describe("F3 bodies (2026-09-25 A/B: F3 arm B)", () => {
+  // sun-glare, lens-crack and lightning-flash: the F3 drafts, tidied (first letter lower-cased, final
+  // full stop dropped). Each rendered string below is byte-identical to the clause the winning take was
+  // generated from.
+  const F3_BODIES: Record<string, { term: string; body: string }> = {
+    "sun-glare": {
+      term: "sun glare",
+      body:
+        "intense warm glare floods the lens from one corner of the frame, blooming and scattering flares unti" +
+        "l the whole picture is washed out to a bright haze. The camera stays where it is and the framing doe" +
+        "s not change. As the glare fades, the second shot emerges through the haze. The shot ends on the sec" +
+        "ond shot, clear and fully resolved, with no glare left. The glare comes from the lens itself, and th" +
+        "e second shot appears only as the haze clears",
+    },
+    "lens-crack": {
+      term: "lens crack",
+      body:
+        "a hairline crack snaps diagonally across the lens and branches into a web of fracture lines that spr" +
+        "eads over the whole picture. The camera stays where it is and the framing does not change. Seen thro" +
+        "ugh the cracks, the first shot gives way to the second shot, and then the fracture lines fade away. " +
+        "The shot ends on the second shot, clear and fully resolved, with no cracks left. The cracks form on " +
+        "the lens itself, while everything behind them stays whole",
+    },
+    "lightning-flash": {
+      term: "lightning strike",
+      body:
+        "a brilliant jagged bolt of lightning cracks across the frame and its flash turns the whole picture w" +
+        "hite. The camera stays where it is and the framing does not change. As the flash dies away, the seco" +
+        "nd shot is revealed in its place. The shot ends on the second shot, fully resolved, with no bolt or " +
+        "flash left. The change happens inside the flash, and the second shot appears only as the white fades",
+    },
+  }
+
+  it.each(Object.keys(F3_BODIES))("%s renders `term (body)` at the tile-default levers", (id) => {
+    const { term, body } = F3_BODIES[id]!
+    expect(getTransitionPromptHint(id)).toBe(body)
+    expect(composeTransitionHintFromConnections(id, [], [], {}, "full", { scope: "shot" })).toBe(`${term} (${body})`)
+  })
+
+  it.each(Object.keys(F3_BODIES))("%s at middle / short / natural", (id) => {
+    const { term, body } = F3_BODIES[id]!
+    expect(composeTransitionHintFromConnections(id, [], [], { position: "middle", duration: "short", intensity: "natural" })).toBe(
+      `${term} (${body}), the transition occurs in the middle of the clip, lasting approximately 1 second, with natural timing`,
+    )
+  })
+})
+
+describe("F4 bodies (2026-09-25 A/B: F4 arm B)", () => {
+  // building-explosion and vehicle-explosion: the F4 drafts, tidied (first letter lower-cased, final
+  // full stop dropped). Each rendered string below is byte-identical to the clause the winning take was
+  // generated from.
+  const F4_BODIES: Record<string, { term: string; body: string }> = {
+    "building-explosion": {
+      term: "building explosion",
+      body:
+        "the largest structure in the frame detonates in a massive fireball, and debris and dust plume outwar" +
+        "d until they fill the whole picture. The camera stays where it is and the framing does not change. A" +
+        "s the dust cloud clears, the second shot is revealed in its place. The shot ends on the second shot," +
+        " clear and fully resolved, with no dust or debris left. The blast comes from that structure itself, " +
+        "and the second shot appears only as the dust clears",
+    },
+    "vehicle-explosion": {
+      term: "vehicle explosion",
+      body:
+        "a vehicle in the frame bursts into a violent explosion of fire and twisted metal, and the fireball b" +
+        "illows toward the lens until orange flame fills the whole picture. The camera stays where it is and " +
+        "the framing does not change. The flame gives way to thick smoke, and as the smoke parts the second s" +
+        "hot is revealed. The shot ends on the second shot, clear and fully resolved, with no fire or smoke l" +
+        "eft. The explosion comes from that vehicle itself, and the second shot appears only as the smoke par" +
+        "ts",
+    },
+  }
+
+  it.each(Object.keys(F4_BODIES))("%s renders `term (body)` at the tile-default levers", (id) => {
+    const { term, body } = F4_BODIES[id]!
+    expect(getTransitionPromptHint(id)).toBe(body)
+    expect(composeTransitionHintFromConnections(id, [], [], {}, "full", { scope: "shot" })).toBe(`${term} (${body})`)
+  })
+
+  it.each(Object.keys(F4_BODIES))("%s at middle / short / natural", (id) => {
+    const { term, body } = F4_BODIES[id]!
+    expect(composeTransitionHintFromConnections(id, [], [], { position: "middle", duration: "short", intensity: "natural" })).toBe(
+      `${term} (${body}), the transition occurs in the middle of the clip, lasting approximately 1 second, with natural timing`,
+    )
+  })
+})
+
+describe("F5 bodies (2026-09-25 A/B: F5 arm B)", () => {
+  // zoom-into-book, pull-out-reveal, zoom-into-mouth, walk-through-door and mask-transition: the F5
+  // drafts, tidied (first letter lower-cased, final full stop dropped). Each rendered string below is
+  // byte-identical to the clause the winning take was generated from.
+  const F5_BODIES: Record<string, { term: string; body: string }> = {
+    "zoom-into-book": {
+      term: "zoom into book",
+      body:
+        "the camera pushes down toward the illustrated page of an open book in the frame until the illustrati" +
+        "on fills the whole picture. The camera travels in one smooth line, without turning or rolling. The d" +
+        "rawn picture comes alive, gaining depth, light and movement, and becomes the second shot. The shot e" +
+        "nds inside the second shot, real and fully resolved, with no paper, ink lines or page edges left. Th" +
+        "e camera heads for the page from the start and goes into its illustration",
+    },
+    "pull-out-reveal": {
+      term: "pull-back reveal",
+      body:
+        "the camera pulls straight back fast, and the whole first shot shrinks until its edges show as the bo" +
+        "rder of a framed picture inside a larger space. The camera travels back in one smooth line, without " +
+        "turning, tilting or rolling. The larger space around the picture is the second shot, and the first s" +
+        "hot stays inside the picture. The shot ends on the second shot, with the first shot visible as a pic" +
+        "ture within it. The first shot's image stays exactly the same as it shrinks, so it reads as the same" +
+        " picture all along",
+    },
+    "zoom-into-mouth": {
+      term: "zoom into mouth",
+      body:
+        "the camera pushes straight into the first subject's open mouth until the dark interior fills the who" +
+        "le picture. The camera travels forward in one smooth line, without turning, tilting or rolling. It p" +
+        "asses through the darkness, and the second shot emerges out of it. The shot ends inside the second s" +
+        "hot, still and fully resolved, with no mouth left in view. The dark interior stays a plain darkness " +
+        "the camera passes through",
+    },
+    "walk-through-door": {
+      term: "walk through doorway",
+      body:
+        "the camera follows the first subject through a doorway in the frame, moving forward at the subject's" +
+        " pace. The camera travels straight forward, without turning, tilting or rolling. On the far side of " +
+        "the doorway the space is the second shot, a different place in different light. The shot ends in the" +
+        " second shot, fully resolved, with the doorway behind the camera. The change of place happens at the" +
+        " doorway itself, the moment the camera passes through it",
+    },
+    "mask-transition": {
+      term: "mask transition",
+      body:
+        "a dark foreground shape sweeps across the lens and fills the frame with black. The camera keeps trav" +
+        "elling forward through the black in one smooth line. It emerges from the darkness into the second sh" +
+        "ot. The shot ends in the second shot, fully resolved, with no dark shape left. The dark shape passes" +
+        " close to the lens and is gone once the second shot appears",
+    },
+  }
+
+  it.each(Object.keys(F5_BODIES))("%s renders `term (body)` at the tile-default levers", (id) => {
+    const { term, body } = F5_BODIES[id]!
+    expect(getTransitionPromptHint(id)).toBe(body)
+    expect(composeTransitionHintFromConnections(id, [], [], {}, "full", { scope: "shot" })).toBe(`${term} (${body})`)
+  })
+
+  it.each(Object.keys(F5_BODIES))("%s at middle / short / natural", (id) => {
+    const { term, body } = F5_BODIES[id]!
+    expect(composeTransitionHintFromConnections(id, [], [], { position: "middle", duration: "short", intensity: "natural" })).toBe(
+      `${term} (${body}), the transition occurs in the middle of the clip, lasting approximately 1 second, with natural timing`,
+    )
+  })
+})
+
+describe("shockwave body (2026-09-25 rework: shockwave3 E1)", () => {
+  // The E1 draft as tested: a flash bursts into a bright opaque ring that races past every edge, the ring
+  // the one hard border between the shots. The rendered string at the tile default is byte-identical to
+  // the clause the winning take was generated from.
+  const TERM = "shockwave"
+  const BODY =
+    "a flash at the exact centre of the frame bursts into a sharp, bright ring that races past every edge" +
+    " in a moment, trailing a smear of motion blur behind its rim and warping the picture as it goes. The" +
+    " camera stays where it is and the picture stays level. The second shot shows only inside the ring an" +
+    "d the first only outside it, with the bright ring as the one hard border and no blending anywhere"
+
+  it("renders `term (body)` at the tile-default levers", () => {
+    expect(getTransitionPromptHint("shockwave")).toBe(BODY)
+    expect(composeTransitionHintFromConnections("shockwave", [], [], {}, "full", { scope: "shot" })).toBe(`${TERM} (${BODY})`)
+  })
+
+  it("at middle / short / natural", () => {
+    expect(composeTransitionHintFromConnections("shockwave", [], [], { position: "middle", duration: "short", intensity: "natural" })).toBe(
+      `${TERM} (${BODY}), the transition occurs in the middle of the clip, lasting approximately 1 second, with natural timing`,
+    )
+  })
+})
+
 describe("L1 — a cut spans nothing, so `full` adds no clause", () => {
   it.each(INSTANT_IDS)("%s + full renders no position clause", (id) => {
     const out = composeTransitionHintFromConnections(id, [], [], { position: "full", duration: "short", intensity: "natural" })

package/src/catalog-sections.ts

@@ -0,0 +1,24 @@
+import { PERSON_DIMENSION_SECTIONS, PERSON_FIELD_BY_DIMENSION } from "./person.js"
+import { STYLING_DIMENSION_SECTIONS, STYLING_FIELD_BY_DIMENSION } from "./styling.js"
+
+/** One of the topics the editor groups a catalog's settings under, as node-data fields. */
+export interface CatalogTopic {
+  readonly label: string
+  readonly fields: ReadonlyArray<string>
+}
+
+/**
+ * The editor's topics for a catalog (Person, Styling), in order, with their
+ * settings as node-data fields — or undefined for every other catalog. Kept
+ * out of the picker-catalogs funnel on purpose: the topic lists are layout
+ * metadata, not catalog entries.
+ */
+export function catalogTopics(catalogId: string): ReadonlyArray<CatalogTopic> | undefined {
+  if (catalogId === "person") {
+    return PERSON_DIMENSION_SECTIONS.map((s) => ({ label: s.label, fields: s.dimensions.map((d) => PERSON_FIELD_BY_DIMENSION[d] as string) }))
+  }
+  if (catalogId === "styling") {
+    return STYLING_DIMENSION_SECTIONS.map((s) => ({ label: s.label, fields: s.dimensions.map((d) => STYLING_FIELD_BY_DIMENSION[d] as string) }))
+  }
+  return undefined
+}

package/src/index.ts

@@ -99,3 +99,6 @@ export * from "./character-motion-diagnostics.js"
 
 // --- Per-ad creative analysis for the social scraper nodes ---
 export * from "./ad-creative-analysis.js"
+
+// --- Picker art: option pictures + topic icons (editor and API) ---
+export * from "./picker-art/index.js"