@nodaro/prompts 1.10.0 → 1.11.0

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

@@ -0,0 +1,370 @@
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt } from "../prompt-builder.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+/**
+ * P3 — named-image mentions `@<name-slug>:<index>[:<role>]`.
+ *
+ * The image analog of `location-convergence-image.test.ts`. `referenceFormat`
+ * is passed EXPLICITLY on every hybrid case: `packages/prompts` is env-free
+ * (`content-free-contract.test.ts`), so `NODE_ENV=test` only steers the
+ * *callers*, never this package.
+ */
+
+const town: ConnectedReference = {
+  id: "n1", defaultName: "Town", source: "wired-image", url: "https://cdn/town.png",
+}
+const plaza: ConnectedReference = {
+  id: "n2", defaultName: "Plaza", source: "wired-image", url: "https://cdn/plaza.png",
+}
+const kira: ConnectedReference = {
+  id: "c1", defaultName: "Kira", source: "wired-character",
+  url: "https://cdn/kira.png", characterSlug: "kira",
+}
+const library: ConnectedReference = {
+  id: "l1", defaultName: "Old Library", source: "wired-location",
+  url: "https://cdn/library.png", locationSlug: "old-library",
+}
+
+describe("named-image mentions resolve on the image hybrid path", () => {
+  it("bare @town:3 → the reference's bare binding, token consumed, URL attached once", () => {
+    const out = buildImagePrompt({
+      prompt: "a wide shot of @town:3 at dusk",
+      connectedReferences: [town],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    // `wired-image`'s default role is "" (DEFAULT_LABEL_BY_SOURCE) →
+    // `roleToPhrase("", binding)` returns the BARE binding.
+    expect(out.prompt).toContain("reference image A")
+    expect(out.prompt).not.toContain("@town")
+    expect(out.referenceImageUrls).toEqual(["https://cdn/town.png"])
+  })
+
+  it("@town:3:background → 'the background from reference image A'", () => {
+    const out = buildImagePrompt({
+      prompt: "a wide shot of @town:3:background at dusk",
+      connectedReferences: [town],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the background from reference image A")
+    expect(out.prompt).not.toContain("@town")
+  })
+
+  it("a CUSTOM role passes through verbatim → 'the signage from reference image A'", () => {
+    const out = buildImagePrompt({
+      prompt: "a wide shot of @town:3:signage at dusk",
+      connectedReferences: [town],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the signage from reference image A")
+  })
+
+  it("the node's own defaultRole is the fallback when the token carries none", () => {
+    const out = buildImagePrompt({
+      prompt: "a wide shot of @town:3 at dusk",
+      connectedReferences: [{ ...town, defaultRole: "texture" } as ConnectedReference],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the texture from reference image A")
+  })
+
+  it("mixed character + location + image: A = character, B = location, C = image", () => {
+    const out = buildImagePrompt({
+      prompt: "@kira:1 walks past @old-library:2 toward @town:3:background",
+      connectedReferences: [kira, library, town],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    // Mention URLs merge in pass order: characters, then locations, then images.
+    expect(out.referenceImageUrls).toEqual([
+      "https://cdn/kira.png",
+      "https://cdn/library.png",
+      "https://cdn/town.png",
+    ])
+    // The letters are the assertion; the location pass's own default role
+    // wording belongs to `location-convergence-image.test.ts`, not here.
+    expect(out.prompt).toContain("from reference image A")
+    expect(out.prompt).toContain("from reference image B")
+    expect(out.prompt).toContain("the background from reference image C")
+    expect(out.prompt).not.toContain("@town")
+    expect(out.prompt).not.toContain("@kira")
+    expect(out.prompt).not.toContain("@old-library")
+  })
+
+  it("PRECEDENCE: a character and an image sharing a name resolve as the CHARACTER", () => {
+    const townCharacter: ConnectedReference = {
+      id: "c2", defaultName: "Town", source: "wired-character",
+      url: "https://cdn/town-character.png", characterSlug: "town",
+    }
+    const out = buildImagePrompt({
+      prompt: "@town:1 stands in the square",
+      connectedReferences: [townCharacter, town],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    // The character pass splices the token out first, so the image pass finds
+    // nothing to bind and the image ref keeps its plain auto-attach slot.
+    expect(out.prompt).toContain("the person from reference image A")
+    expect(out.referenceImageUrls?.[0]).toBe("https://cdn/town-character.png")
+  })
+
+  it("DUPLICATE SLUGS bind FIRST-WINS", () => {
+    const first: ConnectedReference = {
+      id: "u1", defaultName: "Upload Image", source: "wired-image", url: "https://cdn/first.png",
+    }
+    const second: ConnectedReference = {
+      id: "u2", defaultName: "Upload Image", source: "wired-image", url: "https://cdn/second.png",
+    }
+    const out = buildImagePrompt({
+      prompt: "a shot of @upload-image:1",
+      connectedReferences: [first, second],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    // The mention re-seats the FIRST ref, so it takes slot A; the unmentioned
+    // second ref still auto-attaches after it.
+    expect(out.referenceImageUrls).toEqual(["https://cdn/first.png", "https://cdn/second.png"])
+    expect(out.prompt).toContain("reference image A")
+  })
+
+  it("~lock forces an identity-lock line; ~nolock suppresses a ref-level one", () => {
+    const locked = buildImagePrompt({
+      prompt: "a shot of @town:1~lock",
+      connectedReferences: [{
+        ...town,
+        identityLock: { enabled: false, text: "Keep {ref} pixel-exact." },
+      } as ConnectedReference],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(locked.prompt).toContain("Keep reference image A pixel-exact.")
+
+    const unlocked = buildImagePrompt({
+      prompt: "a shot of @town:1~nolock",
+      connectedReferences: [{
+        ...town,
+        identityLock: { enabled: true, text: "Keep {ref} pixel-exact." },
+      } as ConnectedReference],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(unlocked.prompt).not.toContain("pixel-exact")
+  })
+
+  it("a `manual` reference is mentionable too", () => {
+    const out = buildImagePrompt({
+      prompt: "a shot of @moodboard:1:style",
+      connectedReferences: [{
+        id: "m1", defaultName: "Moodboard", source: "manual", url: "https://cdn/mood.png",
+      } as ConnectedReference],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the style from reference image A")
+  })
+
+  it("{image:N} and @town:3 coexist — each renders exactly once", () => {
+    const out = buildImagePrompt({
+      prompt: "put {image:1} beside @plaza:2:background",
+      connectedReferences: [town, plaza],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).not.toContain("{image:")
+    expect(out.prompt).not.toContain("@plaza")
+    // Both URLs attach, each exactly once (the mention does NOT filter its ref
+    // out of `connectedReferences`, and the New-path merge dedups by URL).
+    expect(out.referenceImageUrls?.filter((u) => u === "https://cdn/town.png")).toHaveLength(1)
+    expect(out.referenceImageUrls?.filter((u) => u === "https://cdn/plaza.png")).toHaveLength(1)
+    const backgroundPhrases = out.prompt.match(/the background from reference image/g) ?? []
+    expect(backgroundPhrases).toHaveLength(1)
+  })
+})
+
+/**
+ * THE GATE-ARM GUARD (program plan §6, Leg C: "must exist or the leg silently
+ * no-ops"). An IMAGE-ONLY reference list — no wired character, no location, no
+ * extras — is the commonest studio payload, and it is exactly the case that
+ * reaches Phase 0 ONLY through the `hasImageMentionTokens` arm added to the
+ * `prompt-builder.ts` gate. Delete that arm and this test is the one that fails.
+ */
+describe("Phase-0 gate arm: image-only references", () => {
+  it("image-only refs + one mention → resolves (no character, no location, no extras)", () => {
+    const out = buildImagePrompt({
+      prompt: "a wide shot of @town:1:background at dusk",
+      connectedReferences: [town],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the background from reference image A")
+    expect(out.prompt).not.toContain("@town")
+  })
+})
+
+/**
+ * THE BYTE-PARITY GUARD (program plan §6, Leg C, the second mandatory test).
+ *
+ * The expected values below are FIXTURES CAPTURED FROM THE PRE-CHANGE TREE (the
+ * branch point's `prompt-builder.ts`), not re-derived from the function under
+ * test — a self-comparison would pin nothing. The gate is TOKEN presence, so a
+ * mention-free graph never enters Phase 0 and its output is unchanged BY
+ * CONSTRUCTION; these fixtures are what make that claim falsifiable.
+ */
+describe("mention-free graphs are byte-identical to the pre-change tree", () => {
+  it("image-only, no mention", () => {
+    const out = buildImagePrompt({
+      prompt: "a wide shot of a quiet town square",
+      connectedReferences: [town],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toBe("A wide shot of a quiet town square")
+    expect(out.referenceImageUrls).toEqual(["https://cdn/town.png"])
+  })
+
+  it("two images, no mention", () => {
+    const out = buildImagePrompt({
+      prompt: "a wide shot of a quiet town square",
+      connectedReferences: [town, plaza],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toBe("A wide shot of a quiet town square")
+    expect(out.referenceImageUrls).toEqual(["https://cdn/town.png", "https://cdn/plaza.png"])
+  })
+
+  it("character mention + an unmentioned image", () => {
+    const out = buildImagePrompt({
+      prompt: "@kira:1 walks through the square",
+      connectedReferences: [kira, town],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toBe("the person from reference image A walks through the square")
+    expect(out.referenceImageUrls).toEqual(["https://cdn/kira.png", "https://cdn/town.png"])
+  })
+
+  it("a ref whose name slugs to a GRAMMAR-INVALID slug never arms the gate", () => {
+    // "3D Render" → "3d-render": non-empty, but a leading digit is unparseable,
+    // so `knownImageSlugsFromRefs` drops it and no token can ever match it.
+    const out = buildImagePrompt({
+      prompt: "a shot of @3d-render:1",
+      connectedReferences: [{
+        id: "r1", defaultName: "3D Render", source: "wired-image", url: "https://cdn/r.png",
+      } as ConnectedReference],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("@3d-render:1")
+  })
+
+  it("an isExtraRef media ref is NOT mentionable (it renders through the extras path)", () => {
+    const out = buildImagePrompt({
+      prompt: "a shot of @town:1:background",
+      connectedReferences: [{ ...town, isExtraRef: true } as ConnectedReference],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("@town:1:background")
+    expect(out.prompt).not.toContain("the background from reference image")
+  })
+})
+
+/**
+ * CROSS-GRAMMAR: a LOCATION `bucket/variant` token must never be claimed — not
+ * even in truncated form — by the image pass. The image pass is the only one of
+ * the three that SPLICES its match, so a truncated claim does not merely fail
+ * to resolve, it corrupts the model-facing prompt with a dangling `/variant`.
+ */
+describe("a location bucket/variant token is never claimed by the image pass", () => {
+  const oldLibraryImage: ConnectedReference = {
+    id: "n3", defaultName: "Old Library", source: "wired-image",
+    url: "https://cdn/old-library-photo.png",
+  }
+
+  it("images-only graph: the whole token stays literal, no `/rain` left dangling", () => {
+    const out = buildImagePrompt({
+      prompt: "a shot of @old-library:1:weather/rain",
+      connectedReferences: [oldLibraryImage],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("@old-library:1:weather/rain")
+    // The corruption this pins shut: the truncated claim spliced
+    // `@old-library:1:weather` and left `/rain` welded to the binding phrase.
+    expect(out.prompt).not.toContain("reference image A/rain")
+    expect(out.prompt).not.toContain("/rain\n")
+  })
+
+  it("4-part location token (variant + mode) is left alone too", () => {
+    const out = buildImagePrompt({
+      prompt: "a shot of @old-library:1:weather/rain:style",
+      connectedReferences: [oldLibraryImage],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("@old-library:1:weather/rain:style")
+  })
+
+  it("PRECEDENCE: a shared name + an unresolvable variant does not demote the location to slot B", () => {
+    // The location pass leaves the token alone (the node carries no
+    // `weather/rain` variant); the image pass must not then mangle it, bind the
+    // upload to slot A and push the user's actual location image to slot B.
+    const out = buildImagePrompt({
+      prompt: "a shot of @old-library:1:weather/rain",
+      connectedReferences: [library, oldLibraryImage],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("@old-library:1:weather/rain")
+    expect(out.referenceImageUrls[0]).toBe("https://cdn/library.png")
+  })
+
+  it("a slash BETWEEN two image mentions still resolves both", () => {
+    const out = buildImagePrompt({
+      prompt: "@town:1/@plaza:2",
+      connectedReferences: [town, plaza],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).not.toContain("@town")
+    expect(out.prompt).not.toContain("@plaza")
+    expect(out.referenceImageUrls).toEqual([
+      "https://cdn/town.png",
+      "https://cdn/plaza.png",
+    ])
+  })
+})
+
+/**
+ * LEGACY (the kill-switch path). `IMAGE_REFERENCE_FORMAT=legacy` reverts the
+ * whole leg: there is no legacy image resolver, so a token stays literal text
+ * and the reference attaches exactly as it does today.
+ */
+describe("LEGACY reference format: image mentions stay literal", () => {
+  it("@town:3 is left verbatim and the URL still attaches", () => {
+    const out = buildImagePrompt({
+      prompt: "a wide shot of @town:3 at dusk",
+      connectedReferences: [town],
+      provider: "nano-banana-pro",
+      // no referenceFormat → legacy (the prod default)
+    })
+    expect(out.prompt).toContain("@town:3")
+    expect(out.prompt).not.toContain("reference image A")
+    expect(out.referenceImageUrls).toContain("https://cdn/town.png")
+  })
+
+  it("@town:3:background is left verbatim too", () => {
+    const out = buildImagePrompt({
+      prompt: "a wide shot of @town:3:background at dusk",
+      connectedReferences: [town],
+      provider: "nano-banana-pro",
+    })
+    expect(out.prompt).toContain("@town:3:background")
+    expect(out.prompt).not.toContain("the background from reference image")
+  })
+})

package/src/__tests__/read-node-direction.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect } from "vitest"
+import { readDirectionFields, readStructuredFields } from "../read-node-direction.js"
+import {
+  DIRECTION_ARRAY_CEILING,
+  DIRECTION_KEYS,
+  renderDirectionHints,
+} from "../direction-registry.js"
+
+/**
+ * The narrow readers are the ONLY thing standing between untrusted persisted
+ * node JSONB (`workflows.nodes` — import, MCP write, node preset, a
+ * Studio-emitted graph) and the prompt text a model sees. These cases pin the
+ * VALUE SHAPE contract; the accepted KEY SET is not pinned here on purpose —
+ * it is derived from `DIRECTION_FIELDS`, whose order + membership are pinned by
+ * `direction-registry.test.ts`. A hand list here would be exactly the
+ * "remember to update the list" the registry walk removes.
+ */
+describe("readDirectionFields", () => {
+  it("rejects non-object roots", () => {
+    expect(readDirectionFields(undefined)).toBeUndefined()
+    expect(readDirectionFields(null)).toBeUndefined()
+    expect(readDirectionFields("shotSize")).toBeUndefined()
+    expect(readDirectionFields(42)).toBeUndefined()
+    expect(readDirectionFields([])).toBeUndefined()
+    expect(readDirectionFields([{ shotSize: "medium-shot" }])).toBeUndefined()
+  })
+
+  it("returns undefined, never {}, when nothing survives", () => {
+    // Load-bearing: `{}` is a DEFINED direction, which would flip the call
+    // sites' `...(x !== undefined ? { x } : {})` spread on and take the join
+    // branch instead of the exact no-op branch.
+    expect(readDirectionFields({})).toBeUndefined()
+    expect(readDirectionFields({ shotSize: "" })).toBeUndefined()
+    expect(readDirectionFields({ mood: [] })).toBeUndefined()
+    expect(readDirectionFields({ mood: ["", 5, null] })).toBeUndefined()
+    expect(readDirectionFields({ nothing: "here" })).toBeUndefined()
+  })
+
+  it("keeps a registry key and drops everything unrecognised", () => {
+    expect(readDirectionFields({ shotSize: "medium-shot", bogus: "x" })).toEqual({
+      shotSize: "medium-shot",
+    })
+  })
+
+  it("accepts an array on any key and filters junk entries out of it", () => {
+    expect(readDirectionFields({ mood: ["serene", "", 5, null, "tense"] })).toEqual({
+      mood: ["serene", "tense"],
+    })
+    // An array on a single-pick key is legal at the reader; the per-dimension
+    // cap is the renderer's slice, never a drop here.
+    expect(readDirectionFields({ style: ["anime", "cinematic"] })).toEqual({
+      style: ["anime", "cinematic"],
+    })
+  })
+
+  it("drops non-string / over-length ids", () => {
+    expect(readDirectionFields({ shotSize: 123, style: "anime" })).toEqual({ style: "anime" })
+    expect(readDirectionFields({ shotSize: { id: "medium-shot" } })).toBeUndefined()
+    const overLong = "x".repeat(101)
+    expect(readDirectionFields({ shotSize: overLong })).toBeUndefined()
+    expect(readDirectionFields({ shotSize: "x".repeat(100) })).toEqual({
+      shotSize: "x".repeat(100),
+    })
+    expect(readDirectionFields({ mood: [overLong, "serene"] })).toEqual({ mood: ["serene"] })
+  })
+
+  it("caps an array at the wire ceiling, filtering junk BEFORE the cap", () => {
+    // Cardinality is bounded, not just per-id length: node data is validated
+    // only as `z.record(z.string(), z.unknown())` on write, so an unbounded
+    // array would otherwise reach `renderDirectionHints`' includes-dedupe.
+    const many = Array.from({ length: DIRECTION_ARRAY_CEILING + 20 }, (_, i) => `id-${i}`)
+    expect(readDirectionFields({ mood: many })).toEqual({
+      mood: many.slice(0, DIRECTION_ARRAY_CEILING),
+    })
+    // Junk entries must not consume the budget: 8 unusable entries in front of
+    // the real ids still leaves a full ceiling of real ids.
+    const junk = [...Array.from({ length: DIRECTION_ARRAY_CEILING }, () => ""), ...many]
+    expect(readDirectionFields({ mood: junk })).toEqual({
+      mood: many.slice(0, DIRECTION_ARRAY_CEILING),
+    })
+  })
+
+  it("bounds the work a stored blob can force on the renderer", () => {
+    // Pre-fix this pair was quadratic in the stored array's length (the dedupe
+    // scan ran over the FULL array before the per-row slice), so a node any
+    // authenticated user can persist blocked the event loop for seconds in the
+    // orchestrator and in the user's tab. No timing assertion — the default
+    // vitest timeout is the guard.
+    const huge = Array.from({ length: 200_000 }, (_, i) => `id-${i}`)
+    const direction = readDirectionFields({ mood: huge, lightingStyle: huge })
+    expect(direction?.mood).toHaveLength(DIRECTION_ARRAY_CEILING)
+    expect(() => renderDirectionHints(direction, { surface: "image" })).not.toThrow()
+  })
+
+  it("honors every registry key by construction (a new dimension needs no edit here)", () => {
+    const everyKey = Object.fromEntries(DIRECTION_KEYS.map((k) => [k, "some-id"]))
+    expect(Object.keys(readDirectionFields(everyKey) ?? {}).sort()).toEqual(
+      [...DIRECTION_KEYS].sort(),
+    )
+  })
+})
+
+describe("readStructuredFields", () => {
+  it("rejects non-object roots and returns undefined when nothing survives", () => {
+    expect(readStructuredFields(undefined)).toBeUndefined()
+    expect(readStructuredFields(null)).toBeUndefined()
+    expect(readStructuredFields("person")).toBeUndefined()
+    expect(readStructuredFields([])).toBeUndefined()
+    expect(readStructuredFields({})).toBeUndefined()
+    expect(readStructuredFields({ person: "hello" })).toBeUndefined()
+    expect(readStructuredFields({ person: {}, styling: [] })).toBeUndefined()
+    expect(readStructuredFields({ nothing: "here" })).toBeUndefined()
+  })
+
+  it("drops junk field values instead of rendering them verbatim", () => {
+    // `renderStructuredFields` never throws on junk but DOES render it —
+    // `person: { age: "drop table" }` would become "Subject: drop table years
+    // old." inside `jobs.input_data.prompt`. The field table is what blocks it.
+    expect(readStructuredFields({ person: { age: "drop table" } })).toBeUndefined()
+    expect(readStructuredFields({ person: { age: Number.NaN } })).toBeUndefined()
+    expect(readStructuredFields({ person: { gender: "robot" } })).toBeUndefined()
+    expect(readStructuredFields({ person: { hair: 7 } })).toBeUndefined()
+    expect(readStructuredFields({ person: { hair: "x".repeat(201) } })).toBeUndefined()
+    expect(readStructuredFields({ person: { age: 34, bogus: "x" } })).toEqual({
+      person: { age: 34 },
+    })
+  })
+
+  it("round-trips every group plus the mood shorthand", () => {
+    const full = {
+      person: {
+        age: 34,
+        gender: "woman",
+        hair: "auburn",
+        eyes: "green",
+        expression: "wry",
+        profession: "archivist",
+        warriorType: "ranger",
+      },
+      styling: { mood: "brooding", lighting: "soft", aesthetic: "noir", colorLook: "teal" },
+      setting: { era: "1970s", atmosphere: "humid", backdrop: "a rain-slick street" },
+      camera: { framing: "medium", motion: "slow push", format: "35mm" },
+      lens: { focalLength: "85mm", aperture: "1.4" },
+      mood: "brooding",
+    }
+    expect(readStructuredFields(full)).toEqual(full)
+  })
+
+  it("keeps the surviving fields of a partially-junk group", () => {
+    expect(
+      readStructuredFields({ person: { age: 34, gender: "robot" }, styling: "nope" }),
+    ).toEqual({ person: { age: 34 } })
+  })
+})

package/src/assemble-image-input.ts

@@ -16,13 +16,17 @@
  * This wrapper collapses them into one.
  *
  * THE NO-OP CONTRACT (load-bearing — the platform-caller parity relies on it):
- * the two platform callers (`execute-node` / `payload-builder`) compose their
- * prompt from the canvas graph themselves and pass NO cinematic `direction`
- * ids and NO `structured` fields. In that case `composePromptText` MUST return
- * the caller's `userPrompt` byte-for-byte unchanged, so the wrapper degenerates
- * to exactly the `buildImagePrompt(...)` call those sites make today. Studio
- * (and the MCP route) supply `direction` / `structured` and get the id-hint
- * composition on top.
+ * a node that carries NO stored `direction` / `structured` (every workflow
+ * authored before the canvas honored them) still reaches here with both absent,
+ * and `composePromptText` MUST return the caller's `userPrompt` byte-for-byte
+ * unchanged, so the wrapper degenerates to exactly the `buildImagePrompt(...)`
+ * call those sites made before. The platform callers (`execute-node` /
+ * `payload-builder`) compose their prompt from the canvas GRAPH themselves and
+ * ALSO forward a node's STORED `direction` / `structured` when it carries them
+ * (`readDirectionFields` / `readStructuredFields`); those nodes get the id-hint
+ * composition on top, ADDITIVE to the graph-wired cinematography hints the
+ * caller already folded into `userPrompt`. Studio and the MCP route supply the
+ * same two levers directly.
  *
  * THE EMPTY-CHECK FLAG (also load-bearing for parity): `execute-node` rejects a
  * truly-empty assembled prompt (its "type one, mention a character, or connect
@@ -35,31 +39,28 @@ import {
   buildImagePrompt,
   type BuildImagePromptResult,
 } 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 {
   renderStructuredFields,
   type StructuredPromptFields,
 } from "./prompt-builder-structured-fields.js"
+import {
+  renderDirectionHints,
+  IMAGE_HINT_MODE_DEFAULT,
+  type DirectionFields,
+} from "./direction-registry.js"
+import { joinPromptHints } from "./prompt-hint-join.js"
 import type { CharacterDef, ConnectedReference, IdentityMeta } from "@nodaro/shared"
 
 /**
- * Flat cinematic-direction ids the Studio framing UI (and the MCP route)
- * expose — all optional. Promoted here from Studio's `assembly.ts` so the
- * id → hint composition lives in one place. The platform callers pass none of
- * these (they fold their hints from the graph into `userPrompt` themselves).
+ * Flat cinematic-direction ids the Studio framing UI, the MCP route and the
+ * canvas node data expose — all optional. The dimensions, their canonical fold
+ * ORDER and their per-catalog rendering live in `direction-registry.ts`; this
+ * re-export keeps the import path stable for existing consumers. The platform
+ * callers fold their GRAPH-WIRED hints into `userPrompt` themselves and pass
+ * these only when the node carries them as stored data (Studio-emitted graphs,
+ * spec D3).
  */
-export interface DirectionFields {
-  /** Shot Type — the FRAMINGS shot-size/coverage/composition/vantage dimensions. */
-  framingId?: string
-  /** Angle — the FRAMINGS angle dimension (separate pill, so it can coexist with Shot Type). */
-  framingAngleId?: string
-  lightingId?: string
-  lensId?: string
-  cameraFormatId?: string
-}
+export type { DirectionFields }
 
 /**
  * Input to `assembleImageInput`. A faithful SUPERSET of what the two platform
@@ -80,8 +81,9 @@ export interface AssembleImageInput {
   connectedReferences?: ConnectedReference[]
   /**
    * Flat cinematic-direction ids → folded into the prompt as hints. Studio /
-   * MCP-route use; the platform callers pass none (so `composePromptText` is a
-   * no-op for them and the result is byte-identical to today).
+   * MCP-route use, and the platform callers' narrow-read of a node's STORED
+   * `data.direction`; absent on a node that carries none (so `composePromptText`
+   * is a no-op for it and the result is byte-identical to today).
    */
   direction?: DirectionFields
   /** Path-1 structured fields → composed fragment appended to the prompt. */
@@ -142,17 +144,23 @@ export interface AssembleImageInput {
 
 /**
  * Compose the cinematic-direction hints + structured-field fragment with the
- * user's prompt. Each `get*PromptHint` returns "" on a miss, and
- * `renderStructuredFields` returns "" when nothing is populated.
+ * user's prompt. `renderDirectionHints` folds the `direction` ids in the
+ * registry's canonical table order (unknown keys and unknown ids contribute
+ * nothing), and `renderStructuredFields` returns "" when nothing is populated —
+ * so the structured fragment always lands LAST.
  *
  * EXACT NO-OP CONTRACT: when there are no cinematic/structured hint pieces (the
- * platform-caller case — execute-node / payload-builder never pass `direction`/
- * `structured`), the user's prompt is returned **verbatim, untrimmed**. This is
- * load-bearing for parity: the old platform path passed the prompt straight to
- * `buildImagePrompt`, which never trims, so trimming here would change the
- * assembled prompt (and the recorded `jobs.input_data`) byte-for-byte. We only
- * trim the user prompt when joining it WITH hints, so it reads cleanly
- * ("prompt. hint", not "prompt . hint"). Never mutates inputs.
+ * platform-caller case for a node that carries no stored `direction`/
+ * `structured` — every workflow authored before the canvas honored them), the
+ * user's prompt is returned **verbatim, untrimmed** by `joinPromptHints`. This
+ * is load-bearing for parity: the old platform path passed the prompt straight
+ * to `buildImagePrompt`, which never trims, so trimming here would change the
+ * assembled prompt (and the recorded `jobs.input_data`) byte-for-byte. Never
+ * mutates inputs.
+ *
+ * A node that DOES carry `direction`/`structured` takes the join branch and is
+ * therefore trimmed + `". "`-joined — intended, and asserted at the caller
+ * level by the payload-builder before/after test.
  */
 function composePromptText(
   userPrompt: string,
@@ -160,19 +168,10 @@ function composePromptText(
   structured: StructuredPromptFields | undefined,
 ): string {
   const hints = [
-    getFramingPromptHint(direction?.framingId),
-    getFramingPromptHint(direction?.framingAngleId),
-    getLightingPromptHint(direction?.lightingId),
-    getLensPromptHint(direction?.lensId),
-    getCameraFormatPromptHint(direction?.cameraFormatId),
+    ...renderDirectionHints(direction, { surface: "image", mode: IMAGE_HINT_MODE_DEFAULT }),
     structured ? renderStructuredFields(structured) : "",
   ].filter((p) => p.length > 0)
-  // No hints → verbatim (exact no-op = platform parity). With hints → trim the
-  // user prompt so the ". " join is clean. The trailing filter drops a blank
-  // user prompt so the join never starts with ". " (parity-critical — don't
-  // remove it as "redundant": `hints` is pre-filtered but `userPrompt` is not).
-  if (hints.length === 0) return userPrompt
-  return [userPrompt.trim(), ...hints].filter((p) => p.length > 0).join(". ")
+  return joinPromptHints(userPrompt, hints)
 }
 
 /**