@nodaro/shared 1.4.1

package/src/reference-sheet/__tests__/panel-plan.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest"
+import { planSheetPanels } from "../panel-plan.js"
+import { DEFAULT_SECTIONS } from "../catalog.js"
+import type { SheetFlavour } from "../types.js"
+
+const flavour = (sections?: SheetFlavour["sections"]): SheetFlavour => ({
+  outputFormat: "still", withText: true, showLabels: true, aspect: "landscape", background: "grey", sections,
+})
+
+describe("planSheetPanels", () => {
+  it("turnaround default = 4 head angles for a character", () => {
+    const panels = planSheetPanels("character", DEFAULT_SECTIONS.character.turnaround, flavour())
+    expect(panels).toHaveLength(4)
+    expect(panels.map((p) => p.variant)).toEqual(["front", "3/4 left", "left profile", "right profile"])
+    expect(panels.every((p) => p.board === "headAngles")).toBe(true)
+  })
+  it("structural sections (header/palette/notes) yield no panels", () => {
+    const panels = planSheetPanels("character", [{ kind: "header" }, { kind: "palette" }, { kind: "notes" }], flavour())
+    expect(panels).toHaveLength(0)
+  })
+  it("custom entries become custom panels carrying their prompt", () => {
+    const panels = planSheetPanels("character", [
+      { kind: "expression-board", entries: [
+        { kind: "custom", label: "Tired & Sweaty", prompt: "exhausted, sweaty, heavy eyes" },
+        { kind: "preset", variant: "smile" },
+      ] },
+    ], flavour())
+    expect(panels).toHaveLength(2)
+    const custom = panels.find((p) => p.custom)!
+    expect(custom.variant).toBe("Tired & Sweaty")
+    expect(custom.prompt).toBe("exhausted, sweaty, heavy eyes")
+    expect(panels.find((p) => !p.custom)!.variant).toBe("smile")
+  })
+  it("panelCount clamps to available variants (seasons has only 4)", () => {
+    const panels = planSheetPanels("location",
+      [{ kind: "environment-board", board: "seasons", panelCount: 9 }], flavour())
+    expect(panels).toHaveLength(4)
+    expect(panels.map((p) => p.variant)).toEqual(["spring", "summer", "autumn", "winter"])
+  })
+  it("clamps a non-positive panelCount to zero panels (never a negative slice)", () => {
+    expect(planSheetPanels("character", [{ kind: "expression-board", panelCount: -3 }], flavour())).toHaveLength(0)
+    expect(planSheetPanels("character", [{ kind: "expression-board", panelCount: 0 }], flavour())).toHaveLength(0)
+  })
+  it("throws when a board section has no resolvable board", () => {
+    expect(() => planSheetPanels("location", [{ kind: "environment-board" }], flavour()))
+      .toThrow(/environment-board/)
+  })
+  it("throws when total panels exceed MAX_PANELS_PER_SHEET", () => {
+    // Spread 30 custom panels across 3 distinct boards (10 each) so no single
+    // board trips MAX_CUSTOM_ENTRIES_PER_BOARD (12) — the sheet-total cap (24)
+    // is what must fire here.
+    const ten = (p: string) =>
+      Array.from({ length: 10 }, (_, i) => ({ kind: "custom" as const, label: `${p}${i}`, prompt: "x" }))
+    expect(() => planSheetPanels("character", [
+      { kind: "expression-board", entries: ten("e") },
+      { kind: "pose-board", entries: ten("p") },
+      { kind: "detail-board", entries: ten("d") },
+    ], flavour()))
+      .toThrow(/too many panels|MAX_PANELS/i)
+  })
+})

package/src/reference-sheet/__tests__/panel-prompts.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from "vitest"
+import { buildPanelPrompt } from "../panel-prompts.js"
+
+describe("buildPanelPrompt", () => {
+  it("builds a detail close-up prompt for a character eye variant", () => {
+    const p = buildPanelPrompt("character", "detail", "eyes", "Kaia")
+    expect(p.toLowerCase()).toContain("close-up")
+    expect(p).toContain("eyes")
+  })
+  it("builds a wardrobe prompt for a character outfit variant", () => {
+    const p = buildPanelPrompt("character", "wardrobe", "sporty", "Kaia")
+    expect(p.toLowerCase()).toContain("outfit")
+  })
+  it("returns a generic prompt for unknown board (custom passthrough)", () => {
+    expect(buildPanelPrompt("character", "detail", "left ear", "Kaia")).toContain("left ear")
+  })
+})

package/src/reference-sheet/__tests__/plan-generation.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest"
+import { planSheetGeneration, resolveSheetSections } from "../plan-generation.js"
+import { BOARD_TO_ASSET_TYPE, DEFAULT_SECTIONS } from "../catalog.js"
+import { SHEET_TYPES } from "../types.js"
+import type { SheetFlavour, EntityKind, SheetType } from "../types.js"
+const fl: SheetFlavour = { outputFormat: "still", withText: true, showLabels: true, aspect: "landscape", background: "grey" }
+
+describe("BOARD_TO_ASSET_TYPE", () => {
+  it("maps standard boards to their assetType and detail/wardrobe to custom", () => {
+    expect(BOARD_TO_ASSET_TYPE.character.headAngles).toBe("headAngles")
+    expect(BOARD_TO_ASSET_TYPE.character.detail).toBe("custom")
+    expect(BOARD_TO_ASSET_TYPE.character.wardrobe).toBe("custom")
+    expect(BOARD_TO_ASSET_TYPE.object.materials).toBe("materials")
+    expect(BOARD_TO_ASSET_TYPE.location.timeOfDay).toBe("timeOfDay")
+  })
+})
+
+describe("planSheetGeneration", () => {
+  it("splits present vs missing and builds generate requests for missing", () => {
+    const buckets = { angles: [{ name: "front", url: "u/front" }] } // head-turnaround maps to 'angles' column
+    const r = planSheetGeneration("character",
+      [{ kind: "head-turnaround", entries: [{ kind: "preset", variant: "front" }, { kind: "preset", variant: "3/4 left" }] }],
+      fl, buckets, "Kaia")
+    expect(r.presentUrls).toEqual(["u/front"])
+    expect(r.missing).toHaveLength(1)
+    expect(r.missing[0]).toMatchObject({ assetType: "headAngles", variant: "3/4 left", attachToColumn: "angles", attachName: "3/4 left" })
+    expect(r.missing[0].userPrompt).toBeUndefined() // standard board, no custom prompt
+  })
+  it("detail board missing panels use assetType 'custom' + a built userPrompt", () => {
+    const r = planSheetGeneration("character", [{ kind: "detail-board", entries: [{ kind: "preset", variant: "eyes" }] }], fl, {}, "Kaia")
+    expect(r.missing[0]).toMatchObject({ assetType: "custom", attachToColumn: "detail_closeups", variant: "eyes" })
+    expect(r.missing[0].userPrompt).toContain("eyes")
+  })
+  it("custom entries carry their own prompt", () => {
+    const r = planSheetGeneration("character", [{ kind: "expression-board", entries: [{ kind: "custom", label: "Tired", prompt: "exhausted" }] }], fl, {}, "Kaia")
+    expect(r.missing[0]).toMatchObject({ assetType: "expressions", attachToColumn: "expressions", variant: "Tired", userPrompt: "exhausted" })
+  })
+})
+
+describe("resolveSheetSections", () => {
+  it("falls back to the default stack for (entityKind, type) when no sections are passed", () => {
+    // The canvas node / workflow / API callers send only `type`. Without this
+    // fallback the worker composes with zero bands → a blank sheet (the bug).
+    const r = resolveSheetSections("character", "full-reference")
+    expect(r.length).toBeGreaterThan(0)
+    expect(r.map((s) => s.kind)).toEqual(DEFAULT_SECTIONS.character["full-reference"].map((s) => s.kind))
+  })
+  it("uses the explicit section stack when provided (Studio tab path)", () => {
+    const r = resolveSheetSections("object", "full-reference", [{ kind: "header" }, { kind: "palette" }])
+    expect(r.map((s) => s.kind)).toEqual(["header", "palette"])
+  })
+  it("treats an empty sections array as 'not provided' and falls back to the default", () => {
+    expect(resolveSheetSections("location", "turnaround", []).length).toBeGreaterThan(0)
+  })
+  it("returns a fresh clone — mutating the result never mutates DEFAULT_SECTIONS", () => {
+    const before = DEFAULT_SECTIONS.character.turnaround.length
+    const r = resolveSheetSections("character", "turnaround")
+    r.push({ kind: "notes" })
+    ;(r[0] as { subtitle?: string }).subtitle = "mutated"
+    expect(DEFAULT_SECTIONS.character.turnaround.length).toBe(before)
+    expect(DEFAULT_SECTIONS.character.turnaround[0]).not.toHaveProperty("subtitle")
+  })
+  it("INVARIANT: every (entityKind, type) yields a non-empty default stack", () => {
+    // Root-cause guard: a type with no default stack would make a node sheet
+    // compose zero bands (blank). If a future edit empties one, this fails loudly.
+    for (const kind of Object.keys(DEFAULT_SECTIONS) as EntityKind[]) {
+      for (const type of SHEET_TYPES as readonly SheetType[]) {
+        expect(resolveSheetSections(kind, type).length, `${kind}/${type}`).toBeGreaterThan(0)
+      }
+    }
+  })
+})

package/src/reference-sheet/__tests__/presets.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest"
+import { SHEET_PRESETS, PRESET_LABELS, ALA_CARTE_BOARDS, presetEntries } from "../presets.js"
+import { planSheetPanels } from "../panel-plan.js"
+import { BOARD_VARIANTS } from "../catalog.js"
+import type { SheetFlavour } from "../types.js"
+
+const fl: SheetFlavour = { outputFormat: "still", withText: true, showLabels: true, aspect: "landscape", background: "grey" }
+const byId = (id: string) => SHEET_PRESETS.find((p) => p.id === id)!
+
+describe("presetEntries", () => {
+  it("maps a variant list to ordered preset entries", () => {
+    expect(presetEntries(["front", "back"])).toEqual([
+      { kind: "preset", variant: "front" },
+      { kind: "preset", variant: "back" },
+    ])
+  })
+})
+
+describe("SHEET_PRESETS", () => {
+  it("studio-main = 7 curated head+body panels in order", () => {
+    const panels = planSheetPanels("character", byId("studio-main").baseSections, fl)
+    expect(panels.map((p) => p.variant)).toEqual([
+      "front", "left profile", "right profile", "back", // head
+      "front", "left profile", "back",                  // body
+    ])
+  })
+  it("studio-extended = 15 panels", () => {
+    expect(planSheetPanels("character", byId("studio-extended").baseSections, fl)).toHaveLength(15)
+  })
+  it("every preset variant exists in its board catalog", () => {
+    for (const p of SHEET_PRESETS) {
+      for (const s of p.baseSections) {
+        const board = s.kind === "head-turnaround" ? "headAngles" : "bodyAngles"
+        for (const e of s.entries ?? []) {
+          if (e.kind === "preset") expect(BOARD_VARIANTS.character[board]).toContain(e.variant)
+        }
+      }
+    }
+  })
+  it("each preset has a carrier type + a label", () => {
+    expect(byId("studio-main").type).toBe("turnaround")
+    expect(byId("studio-extended").type).toBe("full-reference")
+    expect(PRESET_LABELS["studio-main"]).toBe("Studio · Main")
+    expect(PRESET_LABELS["studio-extended"]).toBe("Studio · Extended")
+  })
+})
+
+describe("ALA_CARTE_BOARDS", () => {
+  it("are appendable sections in the expected order", () => {
+    expect(ALA_CARTE_BOARDS.map((b) => b.id)).toEqual(["expressions", "poses", "wardrobe", "detail", "palette"])
+    expect(ALA_CARTE_BOARDS[0].section.kind).toBe("expression-board")
+    expect(ALA_CARTE_BOARDS.find((b) => b.id === "palette")!.panelCount).toBe(0)
+  })
+})

package/src/reference-sheet/__tests__/types.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest"
+import {
+  SHEET_TYPES, SHEET_SKINS, SHEET_ASPECTS, OUTPUT_FORMATS, SECTION_KINDS,
+} from "../types.js"
+
+describe("reference-sheet literal axes", () => {
+  it("exposes the four types", () => {
+    expect(SHEET_TYPES).toEqual(["turnaround", "variation-board", "detail", "full-reference"])
+  })
+  it("exposes the four skins", () => {
+    expect(SHEET_SKINS).toEqual(["studio", "cinematic", "blueprint", "illustrated"])
+  })
+  it("exposes aspects and output formats", () => {
+    expect(SHEET_ASPECTS).toEqual(["landscape", "square", "story"])
+    expect(OUTPUT_FORMATS).toEqual(["still", "motion"])
+  })
+  it("section kinds include the board, structural, and turnaround kinds", () => {
+    for (const k of ["header", "head-turnaround", "body-turnaround", "turnaround", "coverage",
+      "expression-board", "pose-board", "material-board", "variation-board", "environment-board",
+      "detail-board", "wardrobe-board", "palette", "scale", "notes"]) {
+      expect(SECTION_KINDS).toContain(k)
+    }
+  })
+})

package/src/reference-sheet/catalog.ts

@@ -0,0 +1,144 @@
+import {
+  CHARACTER_ASSET_VARIANTS, OBJECT_ASSET_VARIANTS, LOCATION_ASSET_VARIANTS,
+} from "../entity-asset-types.js"
+import type { EntityKind, SectionKind, SheetType, SheetSection } from "./types.js"
+
+/** Starter presets for the NEW close-up bucket (per entity). Custom entries override. */
+export const DETAIL_VARIANTS: Record<EntityKind, readonly string[]> = {
+  character: ["eyes", "hands", "hair detail"],
+  object: ["texture", "material detail", "key part"],
+  location: ["architectural detail", "material detail", "focal element"],
+}
+
+/** Starter presets for the NEW wardrobe bucket (character only). Custom entries override. */
+export const WARDROBE_VARIANTS = ["base look", "alternate look", "sporty"] as const
+
+/** Logical board → ordered canonical variants, per entity. Character/object/location
+ *  pull from the SoT lists; detail/wardrobe are the new buckets. */
+export const BOARD_VARIANTS: Record<EntityKind, Record<string, readonly string[]>> = {
+  character: {
+    headAngles: CHARACTER_ASSET_VARIANTS.headAngles,
+    bodyAngles: CHARACTER_ASSET_VARIANTS.bodyAngles,
+    expressions: CHARACTER_ASSET_VARIANTS.expressions,
+    poses: CHARACTER_ASSET_VARIANTS.poses,
+    lighting: CHARACTER_ASSET_VARIANTS.lighting,
+    detail: DETAIL_VARIANTS.character,
+    wardrobe: WARDROBE_VARIANTS,
+  },
+  object: {
+    angles: OBJECT_ASSET_VARIANTS.angles,
+    materials: OBJECT_ASSET_VARIANTS.materials,
+    variations: OBJECT_ASSET_VARIANTS.variations,
+    detail: DETAIL_VARIANTS.object,
+  },
+  location: {
+    angles: LOCATION_ASSET_VARIANTS.angles,
+    timeOfDay: LOCATION_ASSET_VARIANTS.timeOfDay,
+    weather: LOCATION_ASSET_VARIANTS.weather,
+    seasons: LOCATION_ASSET_VARIANTS.seasons,
+    lighting: LOCATION_ASSET_VARIANTS.lighting,
+    detail: DETAIL_VARIANTS.location,
+  },
+}
+
+/** Section kinds that NEVER produce panels (chrome/text bands). The single
+ *  source of truth for "structural" — the planner uses this to decide whether a
+ *  section with no resolvable board is intentionally panel-less (these) or a
+ *  misconfiguration (e.g. `environment-board` with no explicit `board`, which
+ *  must throw, not silently yield zero panels). */
+export const STRUCTURAL_SECTIONS = new Set<SectionKind>(["header", "palette", "scale", "notes"])
+
+/** Default board for each board-typed section kind. `null` = no default board.
+ *  For the four structural kinds (`STRUCTURAL_SECTIONS`) that means "no panels".
+ *  For `environment-board` it means "ambiguous (3 buckets) — the section MUST
+ *  carry an explicit `board`" (the planner throws if it doesn't). */
+export const SECTION_BOARD: Record<SectionKind, string | null> = {
+  header: null, palette: null, scale: null, notes: null,
+  "head-turnaround": "headAngles",
+  "body-turnaround": "bodyAngles",
+  turnaround: "angles",
+  coverage: "angles",
+  "expression-board": "expressions",
+  "pose-board": "poses",
+  "material-board": "materials",
+  "variation-board": "variations",
+  "environment-board": null, // requires explicit section.board (timeOfDay|weather|seasons)
+  "detail-board": "detail",
+  "wardrobe-board": "wardrobe",
+}
+
+/** Sections each entity supports (catalog gate for the config picker, Plan 06). */
+export const ENTITY_SECTIONS: Record<EntityKind, readonly SectionKind[]> = {
+  character: ["header", "head-turnaround", "body-turnaround", "expression-board", "pose-board",
+    "detail-board", "wardrobe-board", "palette", "scale", "notes"],
+  object: ["header", "turnaround", "material-board", "variation-board", "detail-board",
+    "palette", "scale", "notes"],
+  location: ["header", "coverage", "environment-board", "detail-board", "palette", "scale", "notes"],
+}
+
+const sec = (kind: SectionKind, extra: Partial<SheetSection> = {}): SheetSection => ({ kind, ...extra })
+
+/** Preset section stacks per (entity, type). `full-reference` is the rich poster
+ *  (YUVAL order for character); other types are single-board presets. */
+export const DEFAULT_SECTIONS: Record<EntityKind, Record<SheetType, readonly SheetSection[]>> = {
+  character: {
+    turnaround: [sec("header"), sec("head-turnaround")],
+    "variation-board": [sec("header"), sec("expression-board")],
+    detail: [sec("header"), sec("detail-board")],
+    "full-reference": [
+      sec("header"), sec("head-turnaround"), sec("expression-board"), sec("body-turnaround"),
+      sec("pose-board"), sec("detail-board"), sec("wardrobe-board"), sec("palette"), sec("notes"),
+    ],
+  },
+  object: {
+    turnaround: [sec("header"), sec("turnaround")],
+    "variation-board": [sec("header"), sec("material-board")],
+    detail: [sec("header"), sec("detail-board")],
+    "full-reference": [
+      sec("header"), sec("turnaround"), sec("material-board"), sec("variation-board"),
+      sec("detail-board"), sec("palette"), sec("notes"),
+    ],
+  },
+  location: {
+    turnaround: [sec("header"), sec("coverage")],
+    "variation-board": [sec("header"), sec("environment-board", { board: "timeOfDay" })],
+    detail: [sec("header"), sec("detail-board")],
+    "full-reference": [
+      sec("header"), sec("coverage"),
+      sec("environment-board", { board: "timeOfDay" }),
+      sec("environment-board", { board: "weather" }),
+      sec("detail-board"), sec("palette"), sec("notes"),
+    ],
+  },
+}
+
+/** Default number of panels drawn from a board when the section doesn't specify. */
+export const DEFAULT_PANEL_COUNT = 4
+
+/** Logical board key → real entity DB column (headAngles→angles,
+ *  lighting→lighting_variations, timeOfDay→time_of_day, etc.). The worker uses
+ *  this to find a panel's asset in the entity's JSONB buckets. */
+export const BOARD_TO_COLUMN: Record<EntityKind, Record<string, string>> = {
+  character: { headAngles: "angles", bodyAngles: "body_angles", expressions: "expressions", poses: "poses", lighting: "lighting_variations", detail: "detail_closeups", wardrobe: "outfit_variations" },
+  object: { angles: "angles", materials: "materials", variations: "variations", detail: "detail_closeups" },
+  location: { angles: "angles", timeOfDay: "time_of_day", weather: "weather", seasons: "seasons", lighting: "lighting", detail: "detail_closeups" },
+}
+
+/** Flat per-entity DB column holding motion clips ({name,url} videos). Unlike
+ *  still panels (per-board columns via BOARD_TO_COLUMN), all of an entity's motion
+ *  clips live in ONE column, looked up by name===variant. Used by the motion
+ *  reference sheet to find the clip for each planned panel. */
+export const MOTION_COLUMN: Record<EntityKind, string> = {
+  character: "motions",
+  object: "motion_clips",
+  location: "atmosphere_motions",
+}
+
+/** Logical board → the `generate-*-asset` `assetType` to use. Standard boards map
+ *  to their own assetType; detail/wardrobe have no dedicated assetType so they go
+ *  through `custom` (with a built userPrompt). */
+export const BOARD_TO_ASSET_TYPE: Record<EntityKind, Record<string, string>> = {
+  character: { headAngles: "headAngles", bodyAngles: "bodyAngles", expressions: "expressions", poses: "poses", lighting: "lighting", detail: "custom", wardrobe: "custom" },
+  object: { angles: "angles", materials: "materials", variations: "variations", detail: "custom" },
+  location: { angles: "angles", timeOfDay: "timeOfDay", weather: "weather", seasons: "seasons", lighting: "lighting", detail: "custom" },
+}

package/src/reference-sheet/cost.ts

@@ -0,0 +1,37 @@
+import { planSheetGeneration, type PanelGenRequest } from "./plan-generation.js"
+import type { EntityKind, SheetSection, SheetFlavour } from "./types.js"
+
+export interface SheetCostEstimate {
+  present: number
+  missing: PanelGenRequest[]
+  prepareCost: number
+  assemblyCost: number
+  total: number
+  /** True when the plan exceeds MAX_PANELS_PER_SHEET (planSheetPanels throws). */
+  overflow: boolean
+}
+
+/**
+ * Pure cost estimate for a sheet plan. Wraps `planSheetGeneration` so a
+ * MAX_PANELS overflow (which throws in the planner) becomes `overflow:true`
+ * instead of crashing the caller's render. `perPanelCost`/`assemblyCost` are
+ * injected by the UI (constants from the adapter) so the shared layer stays
+ * pricing-agnostic.
+ */
+export function estimateSheetCost(
+  entityKind: EntityKind,
+  sections: readonly SheetSection[],
+  flavour: SheetFlavour,
+  buckets: Record<string, ReadonlyArray<{ name?: string; url?: string }> | undefined>,
+  name: string,
+  perPanelCost: number,
+  assemblyCost: number,
+): SheetCostEstimate {
+  try {
+    const { presentUrls, missing } = planSheetGeneration(entityKind, sections, flavour, buckets, name)
+    const prepareCost = missing.length * perPanelCost
+    return { present: presentUrls.length, missing, prepareCost, assemblyCost, total: prepareCost + assemblyCost, overflow: false }
+  } catch {
+    return { present: 0, missing: [], prepareCost: 0, assemblyCost, total: assemblyCost, overflow: true }
+  }
+}

package/src/reference-sheet/credit-id.ts

@@ -0,0 +1,7 @@
+import type { OutputFormat } from "./types.js"
+/** The credit identifier for a sheet by output format (single source of truth —
+ *  mirrors resolveCinematicCreditId). Used by the route guard, the orchestrator
+ *  payload-builder, and the node's credit display. */
+export function referenceSheetCreditId(flavour: { outputFormat?: OutputFormat | string } | undefined): string {
+  return flavour?.outputFormat === "motion" ? "reference-sheet:assembly-motion" : "reference-sheet:assembly"
+}

package/src/reference-sheet/index.ts

@@ -0,0 +1,8 @@
+export * from "./types.js"
+export * from "./catalog.js"
+export * from "./panel-plan.js"
+export * from "./panel-prompts.js"
+export * from "./plan-generation.js"
+export * from "./credit-id.js"
+export * from "./presets.js"
+export * from "./cost.js"

package/src/reference-sheet/panel-plan.ts

@@ -0,0 +1,65 @@
+import type { EntityKind, PanelRequest, SheetFlavour, SheetSection } from "./types.js"
+import { MAX_PANELS_PER_SHEET, MAX_CUSTOM_ENTRIES_PER_BOARD } from "./types.js"
+import { BOARD_VARIANTS, SECTION_BOARD, STRUCTURAL_SECTIONS, DEFAULT_PANEL_COUNT } from "./catalog.js"
+
+/** Resolve the logical board for a section, or null for structural sections.
+ *  A non-structural board section that can't resolve a board (e.g.
+ *  `environment-board` with no explicit `section.board`, or a board not valid
+ *  for this entity) throws — turning misconfiguration into a free rejection
+ *  instead of silently emitting zero panels. */
+function resolveBoard(entityKind: EntityKind, section: SheetSection): string | null {
+  if (STRUCTURAL_SECTIONS.has(section.kind)) return null
+  const board = section.board ?? SECTION_BOARD[section.kind]
+  if (!board || !BOARD_VARIANTS[entityKind][board]) {
+    throw new Error(
+      `Section "${section.kind}" has no resolvable board for ${entityKind} (board=${board ?? "?"}) — ` +
+        `board sections like environment-board require an explicit section.board valid for the entity`,
+    )
+  }
+  return board
+}
+
+/**
+ * Pure: given an entity kind, an ordered section list, and the flavour, return the
+ * ordered panels the sheet needs. Reuse-vs-generate and pricing happen later
+ * (Plan 04) — this only says WHAT panels must exist. Throws on bad config so the
+ * route can 400 before any paid work.
+ */
+export function planSheetPanels(
+  entityKind: EntityKind,
+  sections: readonly SheetSection[],
+  _flavour: SheetFlavour,
+): PanelRequest[] {
+  const panels: PanelRequest[] = []
+  for (const section of sections) {
+    const board = resolveBoard(entityKind, section)
+    if (board === null) continue // structural section, no panels
+
+    const customs = (section.entries ?? []).filter((e) => e.kind === "custom")
+    if (customs.length > MAX_CUSTOM_ENTRIES_PER_BOARD) {
+      throw new Error(`Too many custom entries on ${section.kind} (${customs.length} > ${MAX_CUSTOM_ENTRIES_PER_BOARD})`)
+    }
+
+    if (section.entries && section.entries.length > 0) {
+      for (const e of section.entries) {
+        if (e.kind === "custom") {
+          panels.push({ section: section.kind, board, variant: e.label, label: e.label, custom: true, prompt: e.prompt })
+        } else {
+          panels.push({ section: section.kind, board, variant: e.variant, label: e.variant, custom: false })
+        }
+      }
+    } else {
+      const available = BOARD_VARIANTS[entityKind][board]
+      // Clamp both ends: a negative panelCount must not become a negative slice
+      // bound (which would silently drop panels from the end of the board).
+      const count = Math.max(0, Math.min(section.panelCount ?? DEFAULT_PANEL_COUNT, available.length))
+      for (const variant of available.slice(0, count)) {
+        panels.push({ section: section.kind, board, variant, label: variant, custom: false })
+      }
+    }
+  }
+  if (panels.length > MAX_PANELS_PER_SHEET) {
+    throw new Error(`Sheet plan has too many panels (${panels.length} > MAX_PANELS_PER_SHEET=${MAX_PANELS_PER_SHEET})`)
+  }
+  return panels
+}

package/src/reference-sheet/panel-prompts.ts

@@ -0,0 +1,14 @@
+import type { EntityKind } from "./types.js"
+
+/** Build the `userPrompt` for a detail/wardrobe panel generated via the
+ *  `custom` assetType (these boards have no dedicated backend assetType). */
+export function buildPanelPrompt(entityKind: EntityKind, board: string, variant: string, name: string): string {
+  if (board === "detail") {
+    return `Extreme close-up macro detail of ${name}'s ${variant}, sharp focus on the ${variant}, neutral background, no text.`
+  }
+  if (board === "wardrobe") {
+    return `Full-body view of ${name} wearing the "${variant}" outfit, consistent character, neutral studio background, no text.`
+  }
+  // Generic passthrough for any other custom board.
+  return `${name}, ${variant}. Consistent character, neutral background, no text.`
+}

package/src/reference-sheet/plan-generation.ts

@@ -0,0 +1,79 @@
+import { planSheetPanels } from "./panel-plan.js"
+import { BOARD_TO_COLUMN, BOARD_TO_ASSET_TYPE, DEFAULT_SECTIONS } from "./catalog.js"
+import { buildPanelPrompt } from "./panel-prompts.js"
+import type { EntityKind, SheetSection, SheetFlavour, SheetType } from "./types.js"
+
+/**
+ * The section stack to actually compose for a sheet. The Studio "Sheet" tab
+ * sends an explicit, user-chosen stack in `flavour.sections`; the canvas node,
+ * workflow runs, and API/MCP callers send only `type`, so fall back to the
+ * default stack for (entityKind, type). Always returns a fresh, mutable clone so
+ * neither the caller nor the shared `DEFAULT_SECTIONS` constant is mutated.
+ *
+ * Single source of truth for "type → sections" — without this fallback a node
+ * sheet composes with zero bands (a blank image). Every (entityKind, type) has a
+ * non-empty default stack (guarded by the catalog invariant test).
+ */
+export function resolveSheetSections(
+  entityKind: EntityKind,
+  type: SheetType,
+  sections?: readonly SheetSection[],
+): SheetSection[] {
+  const base = sections?.length ? sections : (DEFAULT_SECTIONS[entityKind][type] ?? [])
+  return base.map((s) => ({ ...s }))
+}
+
+/** A `generate-*-asset` request for one missing panel. */
+export interface PanelGenRequest {
+  assetType: string        // e.g. "headAngles" | "expressions" | "custom"
+  variant: string          // preset variant or custom label (also the attachName)
+  attachToColumn: string   // DB column (snake_case) the worker appends to
+  attachName: string       // == variant
+  userPrompt?: string      // present for custom assetType / custom entries
+}
+
+export interface SheetGenerationPlan {
+  presentUrls: string[]
+  missing: PanelGenRequest[]
+}
+
+/** Find the bucket item whose `name` equals `variant` and which carries a
+ *  non-empty `url` (single source of truth — the same predicate the still + motion
+ *  panel resolvers use to locate a planned panel in an entity's buckets). */
+export function matchVariant(
+  items: ReadonlyArray<{ name?: string; url?: string }>,
+  variant: string,
+): { name?: string; url?: string } | undefined {
+  return items.find((it) => it?.name === variant && typeof it?.url === "string" && it.url.length > 0)
+}
+
+/** Pure: given the entity's current buckets (keyed by DB column), split the
+ *  planned panels into already-present URLs and the generate-requests needed for
+ *  the rest. The surface fires each request, awaits, then calls the compose API. */
+export function planSheetGeneration(
+  entityKind: EntityKind,
+  sections: readonly SheetSection[],
+  flavour: SheetFlavour,
+  bucketsByColumn: Record<string, ReadonlyArray<{ name?: string; url?: string }> | undefined>,
+  name: string,
+): SheetGenerationPlan {
+  const plan = planSheetPanels(entityKind, sections, flavour)
+  const presentUrls: string[] = []
+  const missing: PanelGenRequest[] = []
+  for (const p of plan) {
+    const column = BOARD_TO_COLUMN[entityKind][p.board]
+    const items = (column ? bucketsByColumn[column] : undefined) ?? []
+    const match = matchVariant(items, p.variant)
+    if (match?.url) {
+      presentUrls.push(match.url)
+      continue
+    }
+    const assetType = BOARD_TO_ASSET_TYPE[entityKind][p.board] ?? "custom"
+    const userPrompt =
+      p.custom ? p.prompt :
+      assetType === "custom" ? buildPanelPrompt(entityKind, p.board, p.variant, name) :
+      undefined
+    missing.push({ assetType, variant: p.variant, attachToColumn: column, attachName: p.variant, userPrompt })
+  }
+  return { presentUrls, missing }
+}