@nodaro/prompts 1.5.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.5.0",
+  "version": "1.7.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",

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

@@ -179,6 +179,26 @@ describe("assembleSunoInput — persona spread", () => {
   })
 })
 
+describe("assembleSunoInput — duration pass-through", () => {
+  it("carries data.duration onto the result verbatim (the provider client gates the send)", () => {
+    const r = assembleSunoInput({
+      node: node({ customMode: true, style: "pop", model: "V5_5", duration: 120 }),
+      graph: emptyGraph,
+      userPrompt: "song",
+    })
+    expect(r.duration).toBe(120)
+  })
+
+  it("no data.duration → undefined", () => {
+    const r = assembleSunoInput({
+      node: node({ model: "V5_5" }),
+      graph: emptyGraph,
+      userPrompt: "song",
+    })
+    expect(r.duration).toBeUndefined()
+  })
+})
+
 describe("assembleSunoInput — || undefined normalization (divergence E)", () => {
   it("empty model/style/title/negativeStyle normalize to undefined", () => {
     const r = assembleSunoInput({

package/src/__tests__/doctrine-roster-completeness.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest"
+import { MODEL_CATALOG } from "@nodaro/shared"
+import { getPromptDoctrine } from "../provider-prompt-doctrine.js"
+
+/**
+ * The badge's truthfulness guarantee (Cine build-brief §7 — never overclaim):
+ * every video GENERATION model is either doctrine-covered or DELIBERATELY
+ * generic. A new video model that is neither fails this test — forcing the
+ * author to write a sourced doctrine or consciously add it to the generic
+ * set with a reason.
+ */
+
+/** Models deliberately left WITHOUT a doctrine, with the reason. */
+const DELIBERATELY_GENERIC: ReadonlyMap<string, string> = new Map([
+  // Older ByteDance engine (pre-Seedance-2 surface: single image, no refs/audio
+  // levers) — mapping the Seedance family doctrine would overclaim.
+  ["bytedance-lite", "older engine, different surface"],
+  ["bytedance-pro", "older engine, different surface"],
+  ["bytedance-pro-fast", "older engine, different surface"],
+  // Hailuo pre-H3 tiers: single-image i2v without the multimodal reference
+  // surface the H3 doctrine teaches.
+  ["hailuo-2.3", "pre-H3 tier without the multimodal surface"],
+  ["hailuo-2.3-pro", "pre-H3 tier without the multimodal surface"],
+  ["hailuo-standard", "pre-H3 tier without the multimodal surface"],
+  // Legacy/simple tiers with no vendor guidance beyond the platform default.
+  ["minimax", "legacy 5s tier, no vendor guide"],
+  ["seedance", "legacy Seedance 1.x, superseded"],
+  ["ltx-2.3-fast", "no vendor prompt guide published"],
+  ["sora2", "roster utility — no first-party guide via KIE"],
+  ["sora2-pro", "roster utility — no first-party guide via KIE"],
+])
+
+/** Utility modes that are driven by inputs, not prose prompting — doctrine
+ *  coverage isn't meaningful for them (spec excludes them from the roster). */
+const UTILITY_ONLY_MODES = new Set(["extend", "motion-transfer", "lip-sync", "video-upscale", "v2v", "video-analysis", "video-audit"])
+
+describe("doctrine roster completeness", () => {
+  const videoGenerationIds = Object.values(MODEL_CATALOG)
+    .filter((m) => m.kind === "video")
+    .filter((m) => m.modes?.some((mode) => (mode === "t2v" || mode === "i2v") && !UTILITY_ONLY_MODES.has(mode)))
+    .map((m) => m.id)
+
+  it("covers every video generation model — or lists it as deliberately generic", () => {
+    const uncovered = videoGenerationIds.filter(
+      (id) => getPromptDoctrine(id) === undefined && !DELIBERATELY_GENERIC.has(id),
+    )
+    expect(
+      uncovered,
+      `New video model(s) with neither a doctrine nor a deliberate-generic entry: ${uncovered.join(", ")}. ` +
+        "Write a sourced doctrine or add to DELIBERATELY_GENERIC with a reason.",
+    ).toEqual([])
+  })
+
+  it("the deliberate-generic set stays honest (no entry that is actually covered)", () => {
+    for (const id of DELIBERATELY_GENERIC.keys()) {
+      expect(getPromptDoctrine(id), `${id} is covered — remove it from DELIBERATELY_GENERIC`).toBeUndefined()
+    }
+  })
+})

package/src/__tests__/location-convergence-image.test.ts

@@ -10,12 +10,16 @@ const library: ConnectedReference = {
 }
 
 describe("location reference converges onto the image hybrid form", () => {
-  it("wired location (canonical) → 'the background from reference image A', no legacy block", () => {
+  // The DEFAULT role for a wired location became "location" (2026-08-05) — a
+  // place, not a backdrop to paste. This assertion previously pinned "the
+  // background from …", the wording measured to produce cut-out composites.
+  // The explicit `:background` token below is unaffected and still renders it.
+  it("wired location (canonical) → 'the location from reference image A', no legacy block", () => {
     const out = buildImagePrompt({
       prompt: "a detective at her desk", connectedReferences: [library],
       provider: "nano-banana-pro", referenceFormat: "hybrid",
     })
-    expect(out.prompt).toContain("the background from reference image A")
+    expect(out.prompt).toContain("the location from reference image A")
     expect(out.prompt).not.toContain("Use these locations:")
     expect(out.referenceImageUrls).toContain("https://cdn/library.png")
   })

package/src/__tests__/picker-analyzer-registry.test.ts

@@ -77,7 +77,17 @@ describe("registry membership (Task 2: person only)", () => {
 describe("registry invariants (all analyzable pickers)", () => {
   it("registers the batch", () => {
     expect(new Set(PICKER_TYPES)).toEqual(
-      new Set(["person", "styling", "framing", "lens", "camera-format"]),
+      new Set([
+        // multi-dim (discriminated)
+        "person", "styling", "framing", "lighting", "temporal", "exposure-settings",
+        "music-genre", "music-mood", "instrumentation", "voice-character", "voice-delivery",
+        // single-value (flat)
+        "lens", "camera-format", "setting", "atmosphere", "style", "mood", "color-look",
+        "photographer", "aesthetic", "era", "photo-genre", "backdrop", "render-quality",
+        "composition-effects", "post-process-effects", "action-fx", "loop-subject",
+        "transition", "character-fx", "pose", "material", "held-prop", "camera-motion",
+        "animal", "vehicle", "weapon", "furniture",
+      ]),
     )
   })
   it.each(PICKER_TYPES)("%s: every dimension enum equals its catalog ids and is non-empty", (t) => {

package/src/__tests__/provider-prompt-doctrine.test.ts

@@ -13,7 +13,7 @@ describe("PROVIDER_PROMPT_DOCTRINES", () => {
       expect(d.providers.length).toBeGreaterThan(0)
       for (const p of d.providers) expect(MODEL_CATALOG[p]).toBeDefined()
       expect(d.tips.length).toBeGreaterThanOrEqual(3)
-      expect(d.tips.length).toBeLessThanOrEqual(6)
+      expect(d.tips.length).toBeLessThanOrEqual(7)
       for (const t of d.tips) expect(t.length).toBeLessThanOrEqual(220)
       expect(d.doctrine.length).toBeGreaterThan(500)
       expect(d.heading.length).toBeGreaterThan(0)
@@ -23,9 +23,11 @@ describe("PROVIDER_PROMPT_DOCTRINES", () => {
   it("resolves by provider id, returns undefined/[] for providers without doctrine", () => {
     expect(getPromptDoctrine("seedance-2")).toBeDefined()
     expect(getPromptDoctrine("seedance-2-fast")).toBeDefined()
-    expect(getPromptDoctrine("veo3.1")).toBeUndefined()
+    // bytedance-lite/pro + hailuo-2.3 are DELIBERATELY uncovered (older engines
+    // whose surfaces differ — mapping the family doctrine would overclaim).
+    expect(getPromptDoctrine("bytedance-lite")).toBeUndefined()
     expect(getPromptTips("seedance-2").length).toBeGreaterThan(0)
-    expect(getPromptTips("veo3.1")).toEqual([])
+    expect(getPromptTips("bytedance-lite")).toEqual([])
   })
 
   it("seedance doctrine encodes the official rules and bans the unstable patterns", () => {

package/src/__tests__/reference-rules.test.ts

@@ -0,0 +1,240 @@
+import { describe, it, expect } from "vitest"
+import {
+  REFERENCE_RULES,
+  REFERENCE_RULES_MULTI_PERSON,
+  SCENE_FRAME_RULE,
+  FILM_STILL_PREFIX,
+  CINEMATIC_LOOK_TAIL,
+  referenceRulesBlock,
+} from "../reference-rules.js"
+import { FACTORY_SNIPPETS } from "../factory-snippets/catalog.js"
+
+/**
+ * These pin the OUTCOME of a measurement, not a preference — 36 draws on
+ * gpt-image-2 against a four-reference brief with wardrobe swapped between two
+ * people (see reference-rules.ts for the arms and the counts). Changing any of
+ * these strings without re-running that comparison is how the two wordings
+ * drifted apart in the first place.
+ */
+describe("REFERENCE_RULES is the short block — the default follows the population", () => {
+  it("keeps the default-deny, the likeness rule and the compose clause", () => {
+    expect(REFERENCE_RULES).toContain("Do not use anything from reference images unless specified explicitly.")
+    expect(REFERENCE_RULES).toContain("All elements taken from reference images must preserve likeness.")
+    expect(REFERENCE_RULES).toContain("Compose them naturally into a single image.")
+  })
+
+  it("carries NO face clauses — they are dead weight on a product or a landscape", () => {
+    // The default lands on every brief. Tal's volume of real jobs says the
+    // short block wins in general; the controlled brief that favoured the face
+    // clauses had two faces swapping a garment, which is what MULTI_PERSON is
+    // for. Both results stand; this is the one that has to be safe everywhere.
+    expect(REFERENCE_RULES).not.toContain("face structure")
+    expect(REFERENCE_RULES).not.toContain("blend faces")
+  })
+
+  it("MULTI_PERSON adds exactly the two face clauses and nothing else", () => {
+    expect(REFERENCE_RULES_MULTI_PERSON).toContain("Do not alter face structure.")
+    expect(REFERENCE_RULES_MULTI_PERSON).toContain("Do not blend faces.")
+    expect(REFERENCE_RULES_MULTI_PERSON).toContain("Compose them naturally into a single image.")
+  })
+
+  it("neither block carries the performance clause — a composite has no scene to perform", () => {
+    // That clause belongs to gvp's scene lane, where a subject acts a beat.
+    // Here it replaced the compose clause and scored 1/4 against 4/4.
+    for (const block of [REFERENCE_RULES, REFERENCE_RULES_MULTI_PERSON]) {
+      expect(block).not.toContain("Expression, gaze and pose follow the scene")
+    }
+  })
+
+  it("does not claim a medium, a genre or a mood", () => {
+    // Every arm that described what the picture IS cost reference fidelity —
+    // "scene start frame of a video" lost the lead's identity in 3 of 3.
+    for (const banned of ["film", "video", "cinematic", "candid", "photo"]) {
+      expect(REFERENCE_RULES.toLowerCase()).not.toContain(banned)
+      expect(REFERENCE_RULES_MULTI_PERSON.toLowerCase()).not.toContain(banned)
+    }
+  })
+})
+
+describe("SCENE_FRAME_RULE is the short negative, and stays short", () => {
+  it("is exactly the sentence that measured free", () => {
+    expect(SCENE_FRAME_RULE).toBe("Nobody looks at the camera.")
+  })
+
+  it("constrains the eyeline and nothing else", () => {
+    // The longer phrasings ("a candid moment, unposed, nobody aware of the
+    // camera") fixed the gaze and lost a face. Length IS the failure mode.
+    expect(SCENE_FRAME_RULE.split(" ")).toHaveLength(5)
+    for (const banned of ["film", "cinematic", "candid", "unposed", "movie"]) {
+      expect(SCENE_FRAME_RULE.toLowerCase()).not.toContain(banned)
+    }
+  })
+})
+
+describe("referenceRulesBlock resolves the two toggles independently", () => {
+  it("defaults to the rules alone — the eyeline is a creative choice, not a rule", () => {
+    expect(referenceRulesBlock()).toBe(REFERENCE_RULES)
+    expect(referenceRulesBlock({})).toBe(REFERENCE_RULES)
+    expect(referenceRulesBlock()).not.toContain(SCENE_FRAME_RULE)
+  })
+
+  it("adds the eyeline rule only when asked", () => {
+    const both = referenceRulesBlock({ sceneFrame: true })
+    expect(both).toContain(REFERENCE_RULES)
+    expect(both).toContain(SCENE_FRAME_RULE)
+    expect(both.indexOf(REFERENCE_RULES)).toBeLessThan(both.indexOf(SCENE_FRAME_RULE))
+  })
+
+  it("returns EMPTY when everything is off, so a caller can prepend blind", () => {
+    expect(referenceRulesBlock({ referenceRules: false })).toBe("")
+    expect(referenceRulesBlock({ referenceRules: false, sceneFrame: false })).toBe("")
+  })
+
+  it("can emit the eyeline rule alone", () => {
+    expect(referenceRulesBlock({ referenceRules: false, sceneFrame: true })).toBe(SCENE_FRAME_RULE)
+  })
+})
+
+describe("the snippet catalog and the injected default cannot drift", () => {
+  const byId = (id: string) => FACTORY_SNIPPETS.find((s) => s.id === id)
+
+  it("Reference Lock IS the default constant, not a hand-kept twin", () => {
+    // The bug this closes: the catalog carried its own wording, written without
+    // knowledge of gvp's, and scored 0/4 where the merged block scored 4/4.
+    expect(byId("reference-lock")?.text).toBe(REFERENCE_RULES)
+  })
+
+  it("Scene Frame IS the constant, and is a SEPARATE entry", () => {
+    expect(byId("scene-frame")?.text).toBe(SCENE_FRAME_RULE)
+    expect(byId("reference-lock")?.text).not.toContain(SCENE_FRAME_RULE)
+  })
+
+  it("both sit in the Reference locks category, for images", () => {
+    for (const id of ["reference-lock", "scene-frame"]) {
+      expect(byId(id)?.category).toBe("Reference locks")
+      expect(byId(id)?.target).toBe("prompt")
+    }
+  })
+})
+
+/**
+ * END TO END through the assembler, because the block is only worth anything
+ * if it arrives AHEAD of the lettered scene it talks about. "Reference image A"
+ * is a hybrid phrase — rules prepended to a legacy assembly would be telling
+ * the model to obey bindings that were never lettered.
+ */
+describe("the block reaches the prompt ahead of the scene it governs", () => {
+  const ref = (id: string, url: string) =>
+    ({ id, defaultName: id, source: "manual" as const, url })
+
+  it("prepends the measured wording, then the lettered scene", async () => {
+    const { buildImagePrompt } = await import("../prompt-builder.js")
+    const { prompt } = buildImagePrompt({
+      provider: "gpt-image-2",
+      prompt: "{image:1:person} wears {image:2:clothes}.",
+      connectedReferences: [ref("a", "https://r2/a.png"), ref("b", "https://r2/b.png")],
+      referenceFormat: "hybrid",
+      referenceLockSnippet: referenceRulesBlock({ sceneFrame: true }),
+    })
+    expect(prompt.startsWith(REFERENCE_RULES)).toBe(true)
+    expect(prompt).toContain(SCENE_FRAME_RULE)
+    // The rules come FIRST; the bindings they govern come after.
+    expect(prompt.indexOf(SCENE_FRAME_RULE)).toBeLessThan(prompt.indexOf("reference image A"))
+    // Line-initial is capitalized by the hybrid scene builder.
+    expect(prompt).toContain("The person from reference image A wears the clothes from reference image B.")
+  })
+
+  it("leaves the prompt untouched when the caller turned both off", async () => {
+    const { buildImagePrompt } = await import("../prompt-builder.js")
+    const snippet = referenceRulesBlock({ referenceRules: false })
+    const { prompt } = buildImagePrompt({
+      provider: "gpt-image-2",
+      prompt: "{image:1:person} sits.",
+      connectedReferences: [ref("a", "https://r2/a.png")],
+      referenceFormat: "hybrid",
+      ...(snippet ? { referenceLockSnippet: snippet } : {}),
+    })
+    expect(prompt).not.toContain("Do not take anything")
+    expect(prompt).not.toContain("Nobody looks at the camera")
+  })
+})
+
+
+/**
+ * THE ONE RULE ALL OF TONIGHT'S ARMS TURNED OUT TO BE: position decides whether
+ * an instruction helps or fights the reference bindings.
+ *
+ *   rules FIRST · framing as a PREFIX · look LAST · never a claim in the middle
+ *
+ * "This image is a scene start frame of a video." is the middle-claim shape and
+ * it cost the lead's identity in 3 of 3 draws. "Film still of" is the prefix
+ * shape and costs nothing. The look tail is the last-position shape and costs
+ * nothing. gvp found the last one independently: "THE MEDIUM GOES LAST".
+ */
+describe("the framing prefix and the look tail keep their shapes", () => {
+  it("the framing snippet is a PREFIX, not a sentence", () => {
+    // A fragment, so it swallows the scene that follows. A full stop here would
+    // make it a standalone claim — the shape that lost the references.
+    expect(FILM_STILL_PREFIX).toBe("Film still of")
+    expect(FILM_STILL_PREFIX.endsWith(".")).toBe(false)
+  })
+
+  it("the look tail names stock, lens, light and palette", () => {
+    for (const part of ["16mm", "lenses", "light", "palette"]) {
+      expect(CINEMATIC_LOOK_TAIL.toLowerCase()).toContain(part)
+    }
+    // It is a tail — no trailing full stop, nothing after it to argue with.
+    expect(CINEMATIC_LOOK_TAIL.endsWith(".")).toBe(false)
+  })
+})
+
+describe("multiPerson swaps in the face clauses without touching anything else", () => {
+  it("is off by default", () => {
+    expect(referenceRulesBlock()).toBe(REFERENCE_RULES)
+    expect(referenceRulesBlock()).not.toContain("blend faces")
+  })
+
+  it("opts into the measured composition block", () => {
+    expect(referenceRulesBlock({ multiPerson: true })).toBe(REFERENCE_RULES_MULTI_PERSON)
+  })
+
+  it("still composes with the eyeline rule", () => {
+    const both = referenceRulesBlock({ multiPerson: true, sceneFrame: true })
+    expect(both).toContain(REFERENCE_RULES_MULTI_PERSON)
+    expect(both).toContain(SCENE_FRAME_RULE)
+  })
+
+  it("stays silent when the rules are off, whatever multiPerson says", () => {
+    expect(referenceRulesBlock({ referenceRules: false, multiPerson: true })).toBe("")
+  })
+})
+
+describe("filmStillPrefix leads with the shot size", () => {
+  it("puts the framing first, then the fixed tail", async () => {
+    const { filmStillPrefix } = await import("../reference-rules.js")
+    expect(filmStillPrefix("Medium wide")).toBe("Medium wide film still of")
+    expect(filmStillPrefix("Extreme wide")).toBe("Extreme wide film still of")
+  })
+
+  it("falls back to the bare prefix when no shot is given", async () => {
+    const { filmStillPrefix } = await import("../reference-rules.js")
+    expect(filmStillPrefix()).toBe(FILM_STILL_PREFIX)
+    expect(filmStillPrefix("   ")).toBe(FILM_STILL_PREFIX)
+  })
+
+  it("claims no genre — a UGC clip and a documentary are film stills too", async () => {
+    const { filmStillPrefix } = await import("../reference-rules.js")
+    // "Cinematic" imposes a register. It is also the exact category of word
+    // every measured arm punished, so it does not belong in a default.
+    for (const shot of [undefined, "Medium wide"]) {
+      expect(filmStillPrefix(shot).toLowerCase()).not.toContain("cinematic")
+    }
+  })
+
+  it("never ends in a full stop — it must swallow the scene, not stand alone", async () => {
+    const { filmStillPrefix } = await import("../reference-rules.js")
+    for (const shot of [undefined, "Extreme wide", "Close-up"]) {
+      expect(filmStillPrefix(shot).endsWith(".")).toBe(false)
+    }
+  })
+})

package/src/__tests__/video-reference-features.test.ts

@@ -34,6 +34,7 @@ describe("video reference-image capability (catalog)", () => {
       "seedance-2",
       "seedance-2-fast",
       "seedance-2-mini",
+      "minimax-h3",
     ]) {
       expect(refModels).toContain(id)
     }

package/src/assemble-suno-input.ts

@@ -84,6 +84,13 @@ export interface AssembleSunoResult {
   customMode: boolean
   instrumental: boolean
   model?: string
+  /**
+   * Requested song length in seconds (KIE: 10–360). Passed through from
+   * `data.duration` unconditionally — the provider client is the single
+   * gate that only sends it when customMode && model V5_5 (KIE ignores it
+   * elsewhere), so the assembler stays a faithful field carrier.
+   */
+  duration?: number
   personaId?: string
   personaModel?: "voice_persona" | "style_persona"
 }
@@ -140,6 +147,7 @@ export function assembleSunoInput(input: AssembleSunoInput): AssembleSunoResult
     styleWeight: data.styleWeight as number | undefined,
     weirdnessConstraint: data.weirdnessConstraint as number | undefined,
     audioWeight: data.audioWeight as number | undefined,
+    duration: data.duration as number | undefined,
     customMode,
     instrumental: (data.instrumental as boolean | undefined) ?? false,
     ...(input.persona ?? {}),

package/src/factory-snippets/catalog.ts

@@ -1,6 +1,7 @@
 /** Factory snippet catalog (v1: image + video; audio/text follow later).
  *  Order within a category = menu order = pill quick-cycle order. */
 import type { FactorySnippet } from "./types.js"
+import { REFERENCE_RULES, SCENE_FRAME_RULE, FILM_STILL_PREFIX, CINEMATIC_LOOK_TAIL } from "../reference-rules.js"
 
 const B = ["image", "video"] as const
 const I = ["image"] as const
@@ -15,7 +16,24 @@ export const FACTORY_SNIPPETS: readonly FactorySnippet[] = [
   { id: "no-beautify", name: "No Beautify", description: "Stop the model 'improving' a face", text: "preserve natural skin texture, age lines, and asymmetries; do not beautify, smooth, slim, or rejuvenate the face", target: "prompt", media: I, category: "Identity & Consistency" },
 
   // ── Reference locks (prompt) — insert at the START of a reference prompt ──
-  { id: "reference-lock", name: "Reference Lock", description: "Default-deny + preserve likeness + compose into one image (full scenes)", text: "Do not use anything from reference images unless specified explicitly. All elements taken from reference images must preserve likeness. Compose them naturally into a single image.", target: "prompt", media: I, category: "Reference locks" },
+  // Text comes from the shared constant, not a hand-written twin. This entry used
+  // to carry its own wording — no face rules, likeness phrased as a passive —
+  // which scored 0/4 on moving a garment between references where the merged
+  // block scored 4/4 (see reference-rules.ts). A snippet is copied into the
+  // prompt at INSERT time, so changing it here only affects future insertions.
+  { id: "reference-lock", name: "Reference Lock", description: "Default-deny + preserve likeness + compose into one image (full scenes)", text: REFERENCE_RULES, target: "prompt", media: I, category: "Reference locks" },
+  // The eyeline suppressor, kept OUT of Reference Lock on purpose: a portrait
+  // or a piece to camera wants the eyeline. 4/4 on a brief where the lock alone
+  // was 0/4, at no measured cost to identity or wardrobe.
+  { id: "scene-frame", name: "Scene Frame", description: "Reads as a frame from a film, not a posed photo — nobody faces the lens", text: SCENE_FRAME_RULE, target: "prompt", media: I, category: "Reference locks" },
+  // A PREFIX, not a sentence — it swallows the scene that follows it, which is
+  // exactly why it costs nothing. The same idea written as a standalone claim
+  // ("This image is a scene start frame of a video.") lost the lead's identity
+  // in 3 of 3 draws. Goes at the very TOP, above the scene.
+  { id: "film-still-of", name: "Film Still Of", description: "Put at the very top, before the scene — lead with the shot size, e.g. \"Medium wide…\"", text: `Medium wide ${FILM_STILL_PREFIX.charAt(0).toLowerCase()}${FILM_STILL_PREFIX.slice(1)}`, target: "prompt", media: I, category: "Reference locks" },
+  // Goes at the very END. An example to edit — a different film wants a
+  // different stock; what generalises is that the look comes LAST.
+  { id: "cinematic-look", name: "Cinematic Look (16mm)", description: "Append at the END — film stock, lens, light and palette", text: CINEMATIC_LOOK_TAIL, target: "prompt", media: I, category: "Reference locks" },
   { id: "reference-extract", name: "Reference Extract", description: "Isolate only the specified elements — no scene, no figure", text: "Take only what is specified from the reference images. Do not take anything else.", target: "prompt", media: I, category: "Reference locks" },
   { id: "ghost-mannequin", name: "Ghost Mannequin", description: "Show worn garments without a wearer (product shot)", text: "Ghost-mannequin product shot: the garment in its natural worn shape, with no person, body, face, or mannequin visible.", target: "prompt", media: I, category: "Reference locks" },
 

package/src/index.ts

@@ -9,6 +9,7 @@
  * only what the public API contract requires.
  */
 export * from "./identity-lock.js"
+export * from "./reference-rules.js"
 export * from "./parameter-prompt-hint.js"
 export * from "./entity-prompts.js"
 export * from "./brand-tokens.js"
@@ -64,3 +65,4 @@ export * from "./factory-presets.js"
 export * from "./style-presets.js"
 export * from "./object-asset-presets.js"
 export * from "./factory-snippets/index.js"
+export * from "./picker-wiring.js"