@nodaro/prompts 1.17.1 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.17.1",
+  "version": "1.18.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.27.0"
+    "@nodaro/shared": "^3.8.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

package/src/__tests__/node-prompt-fields.test.ts

@@ -16,10 +16,10 @@ describe("nodeSupportsPromptAffixes", () => {
     expect(nodeSupportsPromptAffixes("not-a-node")).toBe(false)
     expect(nodeSupportsPromptAffixes(undefined)).toBe(false)
   })
-  it("PROMPT_AFFIX_NODE_TYPES is exactly the registry minus opt-outs (39 types)", () => {
+  it("PROMPT_AFFIX_NODE_TYPES is exactly the registry minus opt-outs (40 types)", () => {
     const expected = Object.entries(NODE_PROMPT_FIELDS).filter(([, s]) => s.affixes !== false).map(([t]) => t)
     expect([...PROMPT_AFFIX_NODE_TYPES].sort()).toEqual(expected.sort())
-    expect(PROMPT_AFFIX_NODE_TYPES.size).toBe(39)
+    expect(PROMPT_AFFIX_NODE_TYPES.size).toBe(40)
   })
   it("getPromptFields still resolves", () => expect(getPromptFields("generate-image")?.prompt).toBe("prompt"))
 })
@@ -28,6 +28,7 @@ describe("promptAffixCoreField — the data key the RUN wraps with pre/post text
   it("most nodes: the editor's primary prompt field", () => {
     expect(promptAffixCoreField("generate-image")).toBe("prompt")
     expect(promptAffixCoreField("llm-chat")).toBe("userInput")
+    expect(promptAffixCoreField("pro-3d-render")).toBe("scenePrompt")
     expect(promptAffixCoreField("generate-3d-scene")).toBe("scenePrompt")
     expect(promptAffixCoreField("edit-3d-scene")).toBe("editPrompt")
     expect(promptAffixCoreField("text-to-speech")).toBe("directText")

package/src/__tests__/scene3d-reference-doctrine.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Scene3D layout-reference doctrine — the wording the 2026-09-10 greybox
+ * experiment's Seedance A/B rerun quotes verbatim, pinned byte-for-byte, plus
+ * the still/clip/cuts variants, the re-run idempotence key and the rule-2
+ * warning builder.
+ */
+import { describe, it, expect } from "vitest"
+import {
+  buildScene3DLayoutScopingLine,
+  buildScene3DUnreferencedFiguresWarning,
+  hasScene3DLayoutScopingLine,
+  renderScene3DLayoutScopingLine,
+  SCENE3D_FIGURE_REFERENCE_RULE,
+  SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE,
+  SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE,
+  SCENE3D_LAYOUT_SCOPING_MARKER,
+  SCENE3D_UNREFERENCED_FIGURES_WARNING_CODE,
+} from "../scene3d-reference-doctrine.js"
+import { renderReferenceCaptionLines } from "../described-references.js"
+
+const CLIP =
+  "LAYOUT reference only — match its subject positions and blocking, its foreground occlusion, its framing, its camera angle, its camera motion and its timing. " +
+  "Ignore its untextured grey clay placeholder look, its flat placeholder colours, its materials, its lighting and its empty background; none of that is the target look. " +
+  "Take the look from the prompt and from the other references"
+
+const STILL =
+  "LAYOUT reference only — match its subject positions and blocking, its foreground occlusion, its framing and its camera angle. " +
+  "Ignore its untextured grey clay placeholder look, its flat placeholder colours, its materials, its lighting and its empty background; none of that is the target look. " +
+  "Take the look from the prompt and from the other references"
+
+describe("SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE — the fixture the A/B rerun quotes", () => {
+  it("is the clip caption: what the reference is for, then what to ignore, plainly", () => {
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE).toBe(CLIP)
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.clip).toBe(CLIP)
+  })
+
+  it("is a caption, not a line: no leading binding, no trailing full stop (the renderer adds both)", () => {
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE.startsWith(SCENE3D_LAYOUT_SCOPING_MARKER)).toBe(true)
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE.endsWith(".")).toBe(false)
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE).not.toContain("@video")
+  })
+
+  it("renders on its seat exactly as the platform's rail-caption renderer renders it", () => {
+    const platform = renderReferenceCaptionLines([SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE], undefined, { video: 1, audio: 0 })
+    expect(platform).toEqual([SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.clipRendered])
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.clipRendered).toBe(`@video_1: ${CLIP}.`)
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.stillRendered).toBe(`@image_1: ${STILL}.`)
+  })
+
+  it("still: drops the motion, timing and cut clauses a single frame cannot carry", () => {
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.still).toBe(STILL)
+    // A still with clip-only facts still reads as a still.
+    expect(buildScene3DLayoutScopingLine({ carries: "still", shots: 4, includesCameraMotion: true })).toBe(STILL)
+  })
+
+  it("clip with several shots names the cut points; one shot is not a cut", () => {
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.clipWithCuts).toContain(
+      "its camera angle, its camera motion, its 4 shots and where they cut and its timing.",
+    )
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.clip).not.toContain("where they cut")
+  })
+
+  it("clip without a camera move keeps timing but claims no motion", () => {
+    const line = buildScene3DLayoutScopingLine({ carries: "clip", includesCameraMotion: false })
+    expect(line).not.toContain("camera motion")
+    expect(line).toContain("its camera angle and its timing.")
+  })
+
+  it("names what to ignore explicitly — every property of the clay look — and never the target look", () => {
+    for (const word of ["grey clay placeholder look", "placeholder colours", "materials", "lighting", "empty background"]) {
+      expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE).toContain(word)
+    }
+    expect(SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE.toLowerCase()).not.toContain("photoreal")
+  })
+
+  it("renderScene3DLayoutScopingLine trims the binding", () => {
+    expect(renderScene3DLayoutScopingLine(" @image_3 ", { carries: "still" }).startsWith("@image_3: LAYOUT")).toBe(true)
+  })
+})
+
+describe("hasScene3DLayoutScopingLine — the re-run idempotence key", () => {
+  it("recognises the platform's rendered line, per binding", () => {
+    const prompt = `A brief.\n${SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE.clipRendered}`
+    expect(hasScene3DLayoutScopingLine(prompt, "@video_1")).toBe(true)
+    expect(hasScene3DLayoutScopingLine(prompt, "@video_2")).toBe(false)
+    expect(hasScene3DLayoutScopingLine(prompt, "@video_10")).toBe(false)
+  })
+
+  it("recognises a hand-typed sentence and an older wording, so a pasted line is not doubled", () => {
+    expect(hasScene3DLayoutScopingLine("@video_1 is a LAYOUT reference only: match its seating.", "@video_1")).toBe(true)
+    expect(hasScene3DLayoutScopingLine("@image_2 is an LAYOUT reference only", "@image_2")).toBe(true)
+    expect(hasScene3DLayoutScopingLine("Two people at a table. @video_1 is a great clip.", "@video_1")).toBe(false)
+  })
+
+  it("is false on nothing", () => {
+    expect(hasScene3DLayoutScopingLine(undefined, "@video_1")).toBe(false)
+    expect(hasScene3DLayoutScopingLine("", "@video_1")).toBe(false)
+  })
+})
+
+describe("buildScene3DUnreferencedFiguresWarning — rule 2 as a warning, never a block", () => {
+  it("warns when figures outnumber character references", () => {
+    const w = buildScene3DUnreferencedFiguresWarning({ figureCount: 6, characterReferenceCount: 1 })
+    expect(w).toBeDefined()
+    expect(w?.code).toBe(SCENE3D_UNREFERENCED_FIGURES_WARNING_CODE)
+    expect(w?.missing).toBe(5)
+    expect(w?.message).toBe(
+      "The layout reference shows 6 figures but 1 character reference is attached. " +
+        "A figure without its own character reference takes the clay look of the layout reference. " +
+        "Attach one character reference per figure (5 more).",
+    )
+  })
+
+  it("states the budget when the image-reference cap is known — a clip rides the video rail", () => {
+    const fits = buildScene3DUnreferencedFiguresWarning({ figureCount: 6, characterReferenceCount: 0, imageReferenceCap: 9 })
+    expect(fits?.message).toContain("this model takes 9 image references, which leaves 3 for a location or style plate.")
+    const tight = buildScene3DUnreferencedFiguresWarning({ figureCount: 8, characterReferenceCount: 0, imageReferenceCap: 9 })
+    expect(tight?.message).toContain("does not fit — reference the figures that matter most first.")
+  })
+
+  it("counts the seat a still layout reference occupies against the same budget", () => {
+    const still = buildScene3DUnreferencedFiguresWarning({
+      figureCount: 6,
+      characterReferenceCount: 0,
+      imageReferenceCap: 9,
+      layoutReferenceImageSeats: 1,
+    })
+    expect(still?.message).toContain("leaves 2 for a location or style plate.")
+  })
+
+  it("stays silent when every figure has a reference, when there are no figures, or when the count is unknown", () => {
+    expect(buildScene3DUnreferencedFiguresWarning({ figureCount: 2, characterReferenceCount: 2 })).toBeUndefined()
+    expect(buildScene3DUnreferencedFiguresWarning({ figureCount: 2, characterReferenceCount: 5 })).toBeUndefined()
+    expect(buildScene3DUnreferencedFiguresWarning({ figureCount: 0, characterReferenceCount: 0 })).toBeUndefined()
+    expect(buildScene3DUnreferencedFiguresWarning({ figureCount: undefined, characterReferenceCount: 0 })).toBeUndefined()
+  })
+
+  it("states the rule in user terms", () => {
+    expect(SCENE3D_FIGURE_REFERENCE_RULE).toContain("its own character reference")
+    expect(SCENE3D_FIGURE_REFERENCE_RULE).toContain("two reference slots free")
+  })
+})

package/src/index.ts

@@ -80,6 +80,7 @@ export * from "./wardrobe.js"
 export * from "./prompt-templates.js"
 export * from "./provider-prompt-doctrine.js"
 export * from "./image-reference-doctrine.js"
+export * from "./scene3d-reference-doctrine.js"
 export * from "./prompt-wizard-categories.js"
 export * from "./resolve-prompt.js"
 export * from "./node-prompt-fields.js"

package/src/node-prompt-fields.ts

@@ -118,6 +118,7 @@ export const NODE_PROMPT_FIELDS: Readonly<Record<string, PromptFieldSpec>> = {
   // ── Composition / FX (compact, no media-result preview → no inline editor) ──
   "image-critic": { prompt: "prompt", promptLabel: "Criteria", media: "image", inline: false },
   "motion-graphics": { prompt: "motionPrompt", promptLabel: "Motion prompt", media: "video", inline: false },
+  "pro-3d-render": { prompt: "scenePrompt", promptLabel: "Scene", media: "text", inline: false },
   "generate-3d-scene": { prompt: "scenePrompt", promptLabel: "Scene", media: "text", inline: false },
   "edit-3d-scene": { prompt: "editPrompt", promptLabel: "Edit instruction", media: "text", inline: false },
   "3d-title": { prompt: "titlePrompt", promptLabel: "Title", media: "text", inline: false },

package/src/prompt-wizard-categories.ts

@@ -165,6 +165,8 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "nano-banana-2-lite": "Fast, low-cost 1K generation for drafts and iteration",
     "gpt-image": "Creative concepts, illustration, variable quality tiers",
     "gpt-image-2": "Latest GPT Image — sharp text, photorealism, 1K/2K/4K resolution",
+    "gpt-image-2-5-flare": "Fast everyday GPT Image 2.5 — higher quality than GPT Image 2 at ~half the latency; default for iteration, social, high volume",
+    "gpt-image-2-5-sunburst": "Precision GPT Image 2.5 — slower, tighter control and detail fidelity; brand-sensitive, packaging, diagrams, final creative",
     "grok": "General purpose, good text understanding",
     "grok-2": "Grok Imagine 2 — expressive, high-contrast, stylized output",
     "imagen4": "Google's latest, strong photorealism and text rendering",
@@ -190,6 +192,8 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "flux-pro-i2i": "Premium Flux transformation",
     "gpt-image-i2i": "Creative reinterpretation of source images",
     "gpt-image-2-i2i": "Latest GPT Image — pixel-level edits with original lighting/texture preservation, up to 4K",
+    "gpt-image-2-5-flare-i2i": "Fast GPT Image 2.5 edits — up to 16 sources; use while iterating",
+    "gpt-image-2-5-sunburst-i2i": "Precision GPT Image 2.5 edits — up to 16 sources, tightest control on demanding retouches; slower",
     "ideogram-edit": "Instruction-based editing with text preservation",
     "ideogram-remix": "Style remixing while preserving structure",
     "ideogram-reframe": "Aspect ratio changes with AI fill",
@@ -213,6 +217,8 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "flux-pro-i2i": "Premium Flux transformation",
     "gpt-image-i2i": "Creative reinterpretation of source images",
     "gpt-image-2-i2i": "Latest GPT Image — pixel-level edits with original lighting/texture preservation, up to 4K",
+    "gpt-image-2-5-flare-i2i": "Fast GPT Image 2.5 edits — up to 16 sources; use while iterating",
+    "gpt-image-2-5-sunburst-i2i": "Precision GPT Image 2.5 edits — up to 16 sources, tightest control on demanding retouches; slower",
     "ideogram-edit": "Instruction-based editing with text preservation",
     "ideogram-remix": "Style remixing while preserving structure",
     "ideogram-reframe": "Aspect ratio changes with AI fill",

package/src/scene3d-reference-doctrine.ts

@@ -0,0 +1,312 @@
+/**
+ * Scene3D layout-reference doctrine — what to tell a video model when a
+ * Scene3D render (the clay MP4 from 3D Render Pro or from Render Video over a
+ * 3D scene, or a still pulled from one) is attached as a reference.
+ *
+ * Two rules, both measured on a real scene (2026-09-10 greybox-to-video
+ * experiment, `seedance-2-mini`, one variable per run):
+ *
+ *   1. NEVER send a layout reference without a scoping line. A reference is a
+ *      style anchor as strongly as it is a composition anchor: unscoped, a
+ *      greybox in gives a greybox out (run A). One sentence naming what the
+ *      reference is FOR and what to IGNORE converts the output (run C).
+ *   2. EVERY figure that must be photoreal needs its own character reference.
+ *      Photoreal treatment is granted PER REFERENCED SUBJECT, not globally: a
+ *      figure with no reference of its own falls back to matching the only
+ *      reference that depicts it — the greybox (runs D → E). One layout
+ *      reference plus one character per figure, with two slots left over for a
+ *      location or style plate, is the budget that converts every figure.
+ *
+ * This module owns the WORDING. It is content, so it lives here (FSL) and not
+ * in `@nodaro/shared`. The platform (`backend/…/scene3d-reference-scoping.ts`)
+ * owns the graph walk that decides WHICH reference is a Scene3D render and what
+ * it carries; it only ever asks this module for the words.
+ *
+ * The scoping line is a RAIL CAPTION. The platform already renders one caption
+ * per video reference as `@video_N: <caption>.` (`renderReferenceCaptionLines`,
+ * the same seat an API caller fills through `referenceVideoCaptions[N]`), so
+ * the text built here carries NO leading binding and NO trailing full stop —
+ * the renderer supplies both. `renderScene3DLayoutScopingLine` reproduces the
+ * rendered form for anything that must quote the line exactly as the model
+ * sees it (the Seedance A/B harness, the docs).
+ *
+ * The line never names the target look ("photoreal", "anime"): that is the
+ * prompt's and the other references' job — rule 2 is what actually buys
+ * photoreal figures.
+ */
+
+/** What a Scene3D layout reference carries: one frame, or the rendered clip. */
+export type Scene3DLayoutReferenceCarrier = "still" | "clip"
+
+export interface Scene3DLayoutScopingSpec {
+  /** One frame (`still`) or the rendered clip (`clip`). */
+  readonly carries: Scene3DLayoutReferenceCarrier
+  /** Shot count in the composition the reference was rendered from, when
+   *  known. More than one shot adds the cut points to what the reference is
+   *  for. Ignored for a still, which is one frame of one shot. */
+  readonly shots?: number
+  /** Whether the clip includes a camera move. A still never does. */
+  readonly includesCameraMotion?: boolean
+}
+
+/**
+ * The phrase every scoping line opens with. It is the idempotence key
+ * (`hasScene3DLayoutScopingLine`) — a re-run over a prompt that already
+ * carries the line for a binding must not add a second one — and it is what an
+ * A/B log greps for. Never reword it without migrating the re-run check.
+ */
+export const SCENE3D_LAYOUT_SCOPING_MARKER = "LAYOUT reference only"
+
+/**
+ * What the reference is FOR — the composition properties that survive a change
+ * of look. Geometry properties, deliberately: the experiment's correction to
+ * the pipeline doc is that what a layout reference must carry is unambiguous
+ * spatial layout, which is a property of geometry, not shading.
+ */
+export const SCENE3D_LAYOUT_SCOPING_FOR = {
+  /** Always: where the subjects are and what is in front of what. */
+  layout: "its subject positions and blocking",
+  occlusion: "its foreground occlusion",
+  framing: "its framing",
+  cameraAngle: "its camera angle",
+  /** Clips only. */
+  cameraMotion: "its camera motion",
+  timing: "its timing",
+  /** Clips with more than one shot. */
+  cuts: (shots: number) => `its ${shots} shots and where they cut`,
+} as const
+
+/**
+ * What to IGNORE — everything the clay render looks like. Named explicitly,
+ * one property at a time, because the model has no other way to know that the
+ * grey slabs are placeholders and not the target set dressing.
+ */
+export const SCENE3D_LAYOUT_SCOPING_IGNORE =
+  "Ignore its untextured grey clay placeholder look, its flat placeholder colours, its materials, its lighting and its empty background; none of that is the target look"
+
+/** Where the look comes from instead. Generic on purpose (see module doc). */
+export const SCENE3D_LAYOUT_SCOPING_LOOK_SOURCE = "Take the look from the prompt and from the other references"
+
+/**
+ * Build the scoping caption for one attached Scene3D reference.
+ *
+ * For a clip with a camera move:
+ *
+ *   `LAYOUT reference only — match its subject positions and blocking, its
+ *   foreground occlusion, its framing, its camera angle, its camera motion and
+ *   its timing. Ignore its untextured grey clay placeholder look, its flat
+ *   placeholder colours, its materials, its lighting and its empty background;
+ *   none of that is the target look. Take the look from the prompt and from
+ *   the other references`
+ *
+ * A still drops the motion, timing and cut clauses: one frame carries none of
+ * them, and claiming otherwise would tell the model to match motion it cannot
+ * see. No trailing full stop — the rail-caption renderer adds it.
+ */
+export function buildScene3DLayoutScopingLine(spec: Scene3DLayoutScopingSpec): string {
+  const matches: string[] = [
+    SCENE3D_LAYOUT_SCOPING_FOR.layout,
+    SCENE3D_LAYOUT_SCOPING_FOR.occlusion,
+    SCENE3D_LAYOUT_SCOPING_FOR.framing,
+    SCENE3D_LAYOUT_SCOPING_FOR.cameraAngle,
+  ]
+  if (spec.carries === "clip") {
+    if (spec.includesCameraMotion) matches.push(SCENE3D_LAYOUT_SCOPING_FOR.cameraMotion)
+    if (typeof spec.shots === "number" && Number.isFinite(spec.shots) && spec.shots > 1) {
+      matches.push(SCENE3D_LAYOUT_SCOPING_FOR.cuts(Math.floor(spec.shots)))
+    }
+    matches.push(SCENE3D_LAYOUT_SCOPING_FOR.timing)
+  }
+  return `${SCENE3D_LAYOUT_SCOPING_MARKER} — match ${joinWithAnd(matches)}. ${SCENE3D_LAYOUT_SCOPING_IGNORE}. ${SCENE3D_LAYOUT_SCOPING_LOOK_SOURCE}`
+}
+
+/** `a, b and c` — the doctrine reads as one sentence, not a list. */
+function joinWithAnd(parts: readonly string[]): string {
+  if (parts.length <= 1) return parts[0] ?? ""
+  return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`
+}
+
+/**
+ * The line exactly as the model sees it once the platform has rendered the
+ * caption onto its seat: `@video_1: <caption>.` — the same shape
+ * `renderReferenceCaptionLines` emits for every rail caption. Use it wherever
+ * the rendered form must be quoted verbatim (the A/B harness, the docs); use
+ * `buildScene3DLayoutScopingLine` for what to SEND.
+ */
+export function renderScene3DLayoutScopingLine(binding: string, spec: Scene3DLayoutScopingSpec): string {
+  return `${binding.trim()}: ${buildScene3DLayoutScopingLine(spec)}.`
+}
+
+/**
+ * True when `prompt` already carries a scoping line for `binding`. The check
+ * is binding + marker, not the whole caption, so a line an author typed by hand
+ * (`@video_1 is a LAYOUT reference only …`) or pasted from the docs still
+ * counts as present — the rule is "one scoping line per reference", never "our
+ * exact bytes". Per binding on purpose: `@video_1` scoped says nothing about
+ * `@video_2`.
+ */
+export function hasScene3DLayoutScopingLine(prompt: string | undefined, binding: string): boolean {
+  if (!prompt) return false
+  const b = binding.trim().replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  return new RegExp(`${b}(?::| is an?)\\s+${SCENE3D_LAYOUT_SCOPING_MARKER}`).test(prompt)
+}
+
+/**
+ * The scoping line the 2026-09-10 experiment's Seedance A/B rerun sends —
+ * the clip form, camera move included — computed from the builder so the
+ * fixture can never drift from what the platform sends. This is the text an
+ * API caller passes as `referenceVideoCaptions[N]` for the Scene3D clip on
+ * `referenceVideoUrls[N]`, and what the canvas attaches for it.
+ */
+export const SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE = buildScene3DLayoutScopingLine({
+  carries: "clip",
+  includesCameraMotion: true,
+})
+
+/**
+ * Every wording the platform can send, plus the rendered form of each on its
+ * usual seat: `clip` on the first video-reference seat, `still` on the first
+ * image-reference seat. `clipWithCuts` is a four-shot composition.
+ */
+export const SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE = {
+  clip: SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE,
+  clipRendered: renderScene3DLayoutScopingLine("@video_1", { carries: "clip", includesCameraMotion: true }),
+  clipWithCuts: buildScene3DLayoutScopingLine({ carries: "clip", shots: 4, includesCameraMotion: true }),
+  still: buildScene3DLayoutScopingLine({ carries: "still" }),
+  stillRendered: renderScene3DLayoutScopingLine("@image_1", { carries: "still" }),
+} as const
+
+/**
+ * A Scene3D layout reference that has already been LOCATED: what it carries,
+ * which seat it landed on, and what that seat is called to the model.
+ *
+ * Finding these is a graph walk, and the graph differs per engine — the
+ * orchestrator holds `SimpleNode`s and run states, the canvas holds React Flow
+ * nodes and their own data. Applying the doctrine to them does NOT differ, and
+ * that is the half that lives here: the two functions below are the whole of
+ * rule 1's application, so a caption cannot mean one thing on a workflow run
+ * and another on the same node's Run button.
+ */
+export interface Scene3DLayoutReferenceSeat {
+  readonly carries: Scene3DLayoutReferenceCarrier
+  /** 0-based seat in the video rail (clip) or the leading image list (still). */
+  readonly index: number
+  /** `@video_N` / `@image_N`, exactly as the model reads the seat. */
+  readonly binding: string
+  readonly spec: Scene3DLayoutScopingSpec
+}
+
+/**
+ * Rule 1 for clips: the rail-caption array, index-aligned with the reference
+ * video list (holes are `""`, which the renderer skips) — the same seat an API
+ * caller fills through `referenceVideoCaptions`.
+ *
+ * `undefined` when there is nothing to add, so a node with no Scene3D
+ * reference keeps its prompt byte-identical. A seat the prompt already scopes
+ * — by hand, or on a re-run over a stored prompt — gets no second line.
+ */
+export function scene3DLayoutVideoCaptions(
+  seats: readonly Scene3DLayoutReferenceSeat[],
+  prompt: string | undefined,
+): string[] | undefined {
+  const clips = seats.filter((r) => r.carries === "clip" && !hasScene3DLayoutScopingLine(prompt, r.binding))
+  if (clips.length === 0) return undefined
+  const captions: string[] = []
+  for (const clip of clips) {
+    while (captions.length <= clip.index) captions.push("")
+    captions[clip.index] = buildScene3DLayoutScopingLine(clip.spec)
+  }
+  return captions
+}
+
+/**
+ * Rule 1 for stills: an image seat has no caption seat, so the line is appended
+ * to the assembled body in the rendered form (`@image_N: <caption>.`) — the
+ * same surface a clip's caption renders to. Same idempotence as the captions.
+ */
+export function appendScene3DStillScopingLines(
+  prompt: string | undefined,
+  seats: readonly Scene3DLayoutReferenceSeat[],
+): string | undefined {
+  const stills = seats.filter((r) => r.carries === "still" && !hasScene3DLayoutScopingLine(prompt, r.binding))
+  if (stills.length === 0) return prompt
+  const lines = stills.map((still) => renderScene3DLayoutScopingLine(still.binding, still.spec))
+  return prompt ? `${prompt}\n${lines.join("\n")}` : lines.join("\n")
+}
+
+// ---------------------------------------------------------------------------
+// Rule 2 — one character reference per figure
+// ---------------------------------------------------------------------------
+
+/** Rule 2 in user terms. Quoted by the docs and by the warning below. */
+export const SCENE3D_FIGURE_REFERENCE_RULE =
+  "Every figure that must look real needs its own character reference; a figure without one takes the clay look of the layout reference. Keep two reference slots free for a location or style plate."
+
+/** Reference slots to keep free beside the figures — a location or style plate. */
+export const SCENE3D_FREE_PLATE_SLOTS = 2
+
+export const SCENE3D_UNREFERENCED_FIGURES_WARNING_CODE = "scene3d_unreferenced_figures"
+
+export interface Scene3DFigureReferenceCheck {
+  /** Figures in the composition — `person` entities in a Scene3D v2 plan.
+   *  `undefined` when the plan cannot say (a v1 plan has no entity roles), in
+   *  which case there is nothing to warn about. */
+  readonly figureCount: number | undefined
+  /** Distinct character references attached to the same generation. */
+  readonly characterReferenceCount: number
+  /** The model's image-reference budget, when known. Lets the message say
+   *  whether one-per-figure plus the free plate slots even fits. */
+  readonly imageReferenceCap?: number
+  /** Image seats the layout reference itself occupies: 0 for a clip (it rides
+   *  the video rail), 1 for a still on an image seat. Default 0. */
+  readonly layoutReferenceImageSeats?: number
+}
+
+export interface Scene3DUnreferencedFiguresWarning {
+  readonly code: typeof SCENE3D_UNREFERENCED_FIGURES_WARNING_CODE
+  readonly message: string
+  readonly figureCount: number
+  readonly characterReferenceCount: number
+  /** Figures still without a reference of their own. */
+  readonly missing: number
+}
+
+/**
+ * Rule 2 as a WARNING, never a block: the run still goes out — the user may
+ * want clay figures, or be drawing a comparison — but they are told, before
+ * they pay to find out, that unreferenced figures will inherit the clay look.
+ * Returns `undefined` when there is nothing to say: no figures, an unknown
+ * count, or every figure already has a reference.
+ */
+export function buildScene3DUnreferencedFiguresWarning(
+  check: Scene3DFigureReferenceCheck,
+): Scene3DUnreferencedFiguresWarning | undefined {
+  const figures = check.figureCount
+  if (figures === undefined || !Number.isFinite(figures) || figures <= 0) return undefined
+  const refs = Math.max(0, Math.floor(check.characterReferenceCount))
+  const missing = Math.floor(figures) - refs
+  if (missing <= 0) return undefined
+  const figureWord = figures === 1 ? "figure" : "figures"
+  const refWord = refs === 1 ? "character reference is" : "character references are"
+  let message =
+    `The layout reference shows ${figures} ${figureWord} but ${refs} ${refWord} attached. ` +
+    `A figure without its own character reference takes the clay look of the layout reference. ` +
+    `Attach one character reference per figure (${missing} more)`
+  const cap = check.imageReferenceCap
+  if (typeof cap === "number" && Number.isFinite(cap) && cap > 0) {
+    const seats = Math.max(0, Math.floor(check.layoutReferenceImageSeats ?? 0))
+    const spare = cap - seats - figures
+    message += spare >= SCENE3D_FREE_PLATE_SLOTS
+      ? `; this model takes ${cap} image references, which leaves ${spare} for a location or style plate.`
+      : `; this model takes ${cap} image references, so one per figure plus ${SCENE3D_FREE_PLATE_SLOTS} free slots for a location or style plate does not fit — reference the figures that matter most first.`
+  } else {
+    message += "."
+  }
+  return {
+    code: SCENE3D_UNREFERENCED_FIGURES_WARNING_CODE,
+    message,
+    figureCount: figures,
+    characterReferenceCount: refs,
+    missing,
+  }
+}