@nodaro/shared 1.4.1

package/src/progress-curve.ts

@@ -0,0 +1,99 @@
+/**
+ * Non-linear progress calculation using quadratic ease-out curve.
+ * Returns 0–99 during execution, never reaching 100 (that's set on completion).
+ *
+ * Formula: progress = 99 * (1 - (1 - t)^exponent)
+ * where t = clamp(elapsedMs / estimatedMs, 0, 1)
+ */
+export function calculateProgress(
+  elapsedMs: number,
+  estimatedMs: number,
+  exponent: number = 2,
+): number {
+  if (estimatedMs <= 0) return 0
+  const t = Math.min(Math.max(elapsedMs / estimatedMs, 0), 1)
+  return Math.round(99 * (1 - Math.pow(1 - t, exponent)))
+}
+
+/** Category-based fallback durations (ms) when no historical data exists. */
+export const CATEGORY_DURATION_DEFAULTS: Record<string, number> = {
+  image: 30_000,
+  video: 120_000,
+  "audio-tts": 15_000,
+  music: 60_000,
+  llm: 8_000,
+  upscale: 30_000,
+  inline: 500,
+}
+
+/**
+ * Compute weighted progress segments for a multi-node flow.
+ * Each node gets a proportional slice of 0–99% based on its estimated duration.
+ *
+ * Returns array of { nodeId, startPct, endPct, estimatedMs } in execution order.
+ */
+export interface ProgressSegment {
+  nodeId: string
+  startPct: number
+  endPct: number
+  estimatedMs: number
+}
+
+export function buildProgressSegments(
+  nodeEstimates: { nodeId: string; estimatedMs: number }[],
+): ProgressSegment[] {
+  const totalMs = nodeEstimates.reduce((sum, n) => sum + n.estimatedMs, 0)
+  if (totalMs <= 0) return []
+
+  const segments: ProgressSegment[] = []
+  let cursor = 0
+
+  for (let i = 0; i < nodeEstimates.length; i++) {
+    const { nodeId, estimatedMs } = nodeEstimates[i]
+    const sliceWidth = (estimatedMs / totalMs) * 99
+    const isLast = i === nodeEstimates.length - 1
+    segments.push({
+      nodeId,
+      startPct: cursor,
+      // Last segment always stretches to exactly 99
+      endPct: isLast ? 99 : cursor + sliceWidth,
+      estimatedMs,
+    })
+    cursor += sliceWidth
+  }
+
+  return segments
+}
+
+/**
+ * Calculate combined progress for a multi-node flow given current node states.
+ */
+export function calculateCombinedProgress(
+  segments: ProgressSegment[],
+  nodeStatuses: Record<string, {
+    status: "pending" | "running" | "completed" | "failed" | "skipped"
+    startedAt?: string
+  }>,
+  now: number = Date.now(),
+): number {
+  let progress = 0
+
+  for (const seg of segments) {
+    const state = nodeStatuses[seg.nodeId]
+    if (!state) continue
+
+    const sliceWidth = seg.endPct - seg.startPct
+
+    if (state.status === "completed" || state.status === "skipped") {
+      progress += sliceWidth
+    } else if (state.status === "running" && state.startedAt) {
+      const elapsed = now - new Date(state.startedAt).getTime()
+      const nodeProgress = calculateProgress(elapsed, seg.estimatedMs)
+      // Map node's 0–99% to this segment's slice
+      progress += (nodeProgress / 99) * sliceWidth
+    }
+    // pending/failed contribute 0
+  }
+
+  return Math.round(Math.min(progress, 99))
+}

package/src/provider-directive-defaults.ts

@@ -0,0 +1,69 @@
+import type { ShotSpec } from "./scene-node-types.js"
+
+/**
+ * Provider-specific directive defaults. Architecture spec §5.14.
+ *
+ * Each video model can have side-effects the user usually wants (Seedance baking in
+ * ambient music, VEO supporting loop seeds, etc.). The engine applies these defaults
+ * at provider-call time, allowing them to be overridden by the Scene Director's
+ * `shot_intent` field (provider-neutral) which we map below.
+ *
+ * Keys are canonical provider identifiers (matching VIDEO_MODEL_CAPS in
+ * model-constants.ts). Non-canonical keys would silently break downstream
+ * route validation + payload building.
+ */
+export const PROVIDER_DIRECTIVE_DEFAULTS = {
+  seedance: { multishot: true, disable_internal_music: true, allow_sfx: true },
+  "seedance-2": { multishot: true, disable_internal_music: true, allow_sfx: true },
+  veo3: { reference_count: "auto" as const },
+  "veo3.1": { reference_count: "auto" as const },
+  kling: { reference_count: "auto" as const },
+  "kling-3-omni": { reference_count: "auto" as const },
+  "kling-turbo": { reference_count: "auto" as const },
+  hailuo: {} as Record<string, never>,
+  "hailuo-2.3-pro": {} as Record<string, never>,
+  "hailuo-standard": {} as Record<string, never>,
+  minimax: {} as Record<string, never>,
+  "bytedance-lite": {} as Record<string, never>,
+} as const
+
+/**
+ * Maps a Scene Director's provider-neutral shot_intent to provider-specific directives.
+ * Architecture spec §5.14 mapping table.
+ *
+ * Unknown providers fall through to an empty object — the directive degrades to a text
+ * hint in the motion_prompt (Scene Director includes it there as a fallback when
+ * `needs_music_suppression: true`).
+ */
+export function mapShotIntentToProviderDirectives(
+  provider: string,
+  shotIntent: ShotSpec["shot_intent"],
+): Record<string, unknown> {
+  const directives: Record<string, unknown> = {
+    ...(PROVIDER_DIRECTIVE_DEFAULTS[provider as keyof typeof PROVIDER_DIRECTIVE_DEFAULTS] ?? {}),
+  }
+
+  if (shotIntent.needs_multishot_reference) {
+    if (provider.startsWith("seedance")) {
+      directives.multishot = true
+    }
+    // VEO + Kling: accepts reference_images array — engine attaches the refs separately.
+    // Hailuo: only 1 ref — silently ignored at engine layer.
+  }
+
+  if (shotIntent.is_loopable) {
+    if (provider.startsWith("veo")) {
+      directives.loop_seed = "stable"
+    }
+    // Other providers: no native loop_seed → degrade to motion_prompt frame-matching hint.
+  }
+
+  if (shotIntent.needs_music_suppression) {
+    if (provider.startsWith("seedance")) {
+      directives.disable_internal_music = true
+    }
+    // VEO / Kling / Hailuo don't bake in music; no directive needed.
+  }
+
+  return directives
+}

package/src/reduce-strategy-registry.ts

@@ -0,0 +1,121 @@
+import { z, type ZodType, type ZodTypeDef } from "zod"
+// Reuse the canonical `OutputType` from presentation-utils so a single union
+// is the source of truth across the package. Re-exporting it here would
+// collide with the explicit named re-export in `index.ts`.
+import type { OutputType } from "./presentation-utils.js"
+
+// `ZodType<Output, Def, Input>` with `Input = any` lets us accept schemas
+// like `z.object({ x: z.string().default("") })` where the parsed output is
+// `{ x: string }` but the input is `{ x?: string }`. Pinning Input to TConfig
+// would force input === output and reject `.default()` schemas.
+export type ReduceStrategy<TConfig = unknown> = {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly configSchema: ZodType<TConfig, ZodTypeDef, any>
+  readonly defaultConfig: TConfig
+  readonly outputType: OutputType
+  readonly creditCostKey: string
+}
+
+const PICK_BEST_LLM_STRATEGY = {
+  id: "pick-best-llm",
+  label: "Pick best (LLM judge)",
+  description: "Sonnet picks the best item against your criteria.",
+  configSchema: z.object({
+    // Default to the sensible "best quality" criteria when omitted (matches
+    // defaultConfig) so a reduce({strategyId:"pick-best-llm"}) call with no
+    // criteria degrades gracefully instead of erroring. An explicit "" still
+    // rejects via min(1).
+    criteria: z.string().min(1, "criteria cannot be empty").default("Pick the highest-quality result."),
+    inputKind: z.enum(["text", "image-url"]).default("text"),
+  }),
+  defaultConfig: { criteria: "Pick the highest-quality result.", inputKind: "text" as const },
+  outputType: "text" as OutputType,
+  creditCostKey: "reduce:pick-best-llm",
+} as const satisfies ReduceStrategy<{ criteria: string; inputKind: "text" | "image-url" }>
+
+const CONCAT_STRATEGY = {
+  id: "concat",
+  label: "Concatenate",
+  description: "Join all survivors with a separator.",
+  configSchema: z.object({ separator: z.string().default("\n\n") }),
+  defaultConfig: { separator: "\n\n" },
+  outputType: "text" as OutputType,
+  creditCostKey: "reduce:concat",
+} as const satisfies ReduceStrategy<{ separator: string }>
+
+const FIRST_NON_EMPTY_STRATEGY = {
+  id: "first-non-empty",
+  label: "First non-empty",
+  description: "Return the first survivor (empty strings filtered).",
+  configSchema: z.object({}),
+  defaultConfig: {},
+  outputType: "text" as OutputType,
+  creditCostKey: "reduce:first-non-empty",
+} as const satisfies ReduceStrategy<Record<string, never>>
+
+const COUNT_STRATEGY = {
+  id: "count",
+  label: "Count",
+  description: "Return how many survivors came through.",
+  configSchema: z.object({}),
+  defaultConfig: {},
+  outputType: "data" as OutputType,
+  creditCostKey: "reduce:count",
+} as const satisfies ReduceStrategy<Record<string, never>>
+
+const VOTE_STRATEGY = {
+  id: "vote",
+  label: "Majority vote",
+  description: "Return the most common survivor (ties → first).",
+  configSchema: z.object({ caseSensitive: z.boolean().default(false) }),
+  defaultConfig: { caseSensitive: false },
+  outputType: "text" as OutputType,
+  creditCostKey: "reduce:vote",
+} as const satisfies ReduceStrategy<{ caseSensitive: boolean }>
+
+const MERGE_JSON_STRATEGY = {
+  id: "merge-json",
+  label: "Merge JSON",
+  description: "Parse each survivor as JSON and merge into one object.",
+  configSchema: z.object({ strategy: z.enum(["deep", "shallow"]).default("deep") }),
+  defaultConfig: { strategy: "deep" as const },
+  outputType: "data" as OutputType,
+  creditCostKey: "reduce:merge-json",
+} as const satisfies ReduceStrategy<{ strategy: "deep" | "shallow" }>
+
+/**
+ * Result-meta shape returned by every reduce strategy. Shared between the
+ * backend route, the SDK client, and the frontend node so all three layers
+ * agree on field names. `selectedIndex` + `reasoning` are set by the
+ * `pick-best-llm` and `vote` strategies (the former also fills `reasoning`);
+ * `summary` is always populated.
+ */
+export type ReduceMeta = {
+  readonly selectedIndex?: number
+  readonly reasoning?: string
+  readonly summary: string
+}
+
+export const REDUCE_STRATEGIES = [
+  PICK_BEST_LLM_STRATEGY,
+  CONCAT_STRATEGY,
+  FIRST_NON_EMPTY_STRATEGY,
+  COUNT_STRATEGY,
+  VOTE_STRATEGY,
+  MERGE_JSON_STRATEGY,
+] as const
+
+export const REDUCE_STRATEGY_IDS = REDUCE_STRATEGIES.map((s) => s.id) as readonly ReduceStrategyId[]
+
+export type ReduceStrategyId = typeof REDUCE_STRATEGIES[number]["id"]
+
+const BY_ID = new Map<string, ReduceStrategy>(REDUCE_STRATEGIES.map((s) => [s.id, s]))
+
+export function getStrategy(id: ReduceStrategyId): ReduceStrategy {
+  const s = BY_ID.get(id)
+  if (!s) throw new Error(`unknown reduce strategy: ${id}`)
+  return s
+}

package/src/reference-board-templates.ts

@@ -0,0 +1,81 @@
+/** Gen providers for the board: strict subset of IMAGE_GEN_PROVIDERS that
+ *  renders legible in-image text + accepts reference conditioning. */
+export const REFERENCE_BOARD_PROVIDERS = ["nano-banana-pro", "gpt-image-2"] as const
+export type ReferenceBoardProvider = (typeof REFERENCE_BOARD_PROVIDERS)[number]
+
+export type BoardEntityKind = "character" | "location" | "object"
+
+export interface BoardTemplate {
+  /** "<entityKind>/<slug>" */
+  readonly id: string
+  readonly entityKind: BoardEntityKind
+  readonly label: string
+  readonly build: (ctx: BoardPromptContext) => string
+}
+
+/** Optional metadata the resolver supplies from a connected entity. All
+ *  optional — the prompt degrades gracefully (omits labels) when absent. */
+export interface BoardPromptContext {
+  readonly name?: string
+  readonly description?: string
+}
+
+// ── Shared clauses (the three guide tricks) ──────────────────────────────
+const ANTI_RIGID =
+  "Editorial reference-board layout, dark near-black background, thin yellow neon accent light, " +
+  "faint film-grain overlay, production-grade design UI. Organized but not rigidly locked: panels may " +
+  "shift position from generation to generation while staying readable, balanced and premium. Works " +
+  "cleanly in different aspect ratios without depending on a fixed left-column structure. All on-image labels in ENGLISH."
+const PALETTE = "A COLOR PALETTE panel: 6 swatches with HEX codes derived from the dominant tones."
+const CAPTION = (kind: string) =>
+  `Bottom caption: "Use this ${kind} board as a visual reference for consistent depiction across all generations." ` +
+  `Bottom-right tags: STYLE · Modern · Realistic · Cinematic. Style: photorealistic, no illustration. 8K, fine grain, cinematic color grading.`
+
+const subj = (ctx: BoardPromptContext, fallback: string) =>
+  ctx.description?.trim() ? ctx.description.trim() : fallback
+
+// ── Character ────────────────────────────────────────────────────────────
+const characterFullBoard = (ctx: BoardPromptContext): string =>
+  `Create a single high-resolution, densely packed character reference sheet titled "CHARACTER BOARD" ` +
+  `using the attached photo as the single source of truth for face, hair, eyes, skin tone and body proportions ` +
+  `of ${subj(ctx, "the attached person")}. The same person appears in every panel — same age, same features. ${ANTI_RIGID} ` +
+  `Include a large hero portrait + metadata block: NAME · AGE · HEIGHT · BUILD · HAIR · EYES · FEATURES · OUTFIT · CHARACTER · MOOD. ` +
+  `Six panels: VIEWS (front · 3/4 · side · back) · EXPRESSIONS (5 headshots) · DETAILS (face/eyes, hand, outfit macro) · ` +
+  `OUTFIT FLAT-LAYS (5 isolated product shots) · LIGHTING/MOOD (4 lighting setups) · ${PALETTE} ${CAPTION("character")}`
+
+// ── Location ─────────────────────────────────────────────────────────────
+const locationFullBoard = (ctx: BoardPromptContext): string =>
+  `Create a single high-resolution, densely packed location reference sheet titled "LOCATION BOARD" ` +
+  `using the attached photo as the single source of truth for architecture, atmosphere, lighting, materials and color ` +
+  `of ${subj(ctx, "the attached location")}. The space is identical across every panel — same place, materials, era. ${ANTI_RIGID} ` +
+  `Include a hero establishing shot + metadata block: NAME · TYPE · ERA · SCALE · ARCHITECTURE · MATERIALS · ATMOSPHERE · DEFAULT TIME · DEFAULT WEATHER · PURPOSE. ` +
+  `Six panels: VIEWS (wide · mid · tight · alt · overhead) · TIME OF DAY (dawn · noon · dusk · night) · DETAILS (material, architectural) · ` +
+  `SET DRESSING / PROPS (5 studies) · WEATHER/MOOD (clear · overcast · rain · fog) · ${PALETTE} ${CAPTION("location")}`
+
+// ── Object ───────────────────────────────────────────────────────────────
+const objectFullBoard = (ctx: BoardPromptContext): string =>
+  `Create a single high-resolution, densely packed object reference sheet titled "OBJECT BOARD" ` +
+  `using the attached photo as the single source of truth for shape, materials, finish and proportions ` +
+  `of ${subj(ctx, "the attached object")}. The object is identical across every panel. ${ANTI_RIGID} ` +
+  `Include a hero shot + metadata block: NAME · TYPE · SCALE · MATERIALS · FINISH · KEY FEATURES · FUNCTION · MOOD. ` +
+  `Six panels: VIEWS (front · 3/4 · side · back · top) · MATERIALS (close studies) · DETAILS (key part macros) · ` +
+  `VARIATIONS (color/finish options) · LIGHTING/MOOD (4 setups) · ${PALETTE} ${CAPTION("object")}`
+
+const t = (entityKind: BoardEntityKind, slug: string, label: string, build: BoardTemplate["build"]): BoardTemplate =>
+  ({ id: `${entityKind}/${slug}`, entityKind, label, build })
+
+export const REFERENCE_BOARD_TEMPLATES: readonly BoardTemplate[] = [
+  t("character", "full-board", "Full Board — hero + 6 panels + palette", characterFullBoard),
+  t("location", "full-board", "Full Board — hero + 6 panels + palette", locationFullBoard),
+  t("object", "full-board", "Full Board — hero + 6 panels + palette", objectFullBoard),
+]
+
+export function listBoardTemplates(kind: BoardEntityKind): BoardTemplate[] {
+  return REFERENCE_BOARD_TEMPLATES.filter((x) => x.entityKind === kind)
+}
+
+export function buildBoardPrompt(templateId: string, ctx: BoardPromptContext): string {
+  const tpl = REFERENCE_BOARD_TEMPLATES.find((x) => x.id === templateId)
+  if (!tpl) throw new Error(`Unknown reference-board template: ${templateId}`)
+  return tpl.build(ctx)
+}

package/src/reference-roles.ts

@@ -0,0 +1,153 @@
+// packages/shared/src/reference-roles.ts
+import { DEFAULT_LABEL_BY_SOURCE, type ReferenceSource } from "./types.js"
+
+/**
+ * Per-source ORDERED preset role ids (most-useful first) for the editor's role
+ * menu. The single source of truth for the curated vocabulary — every menu and
+ * the resolver read from here. `Custom…` (free-form) is added by the UI, not
+ * listed here. Each list MUST contain the source's `DEFAULT_LABEL_BY_SOURCE`
+ * value (guarded by reference-roles.test.ts).
+ */
+export const REFERENCE_ROLE_PRESETS: Record<ReferenceSource, readonly string[]> = {
+  "wired-character": ["person", "face", "clothes", "hair", "pose", "expression", "style"],
+  "wired-face": ["face", "person", "expression", "style"],
+  "wired-location": ["background", "atmosphere", "as-is", "empty background", "layout", "lighting", "style"],
+  "wired-object": ["object", "shape", "material", "color", "texture", "style"],
+  "wired-creature": ["creature", "anatomy", "markings", "pose", "color", "style"],
+  "wired-image": ["object", "person", "face", "clothes", "background", "style", "pose", "texture"],
+  "manual": ["object", "person", "face", "clothes", "background", "style", "pose", "texture"],
+}
+
+/** Canonical default role for a source — the value the editor pre-fills and the
+ *  resolver falls back to. Aliased to `DEFAULT_LABEL_BY_SOURCE` so the two never
+ *  drift. */
+export function defaultRoleForSource(source: ReferenceSource): string {
+  return DEFAULT_LABEL_BY_SOURCE[source]
+}
+
+/**
+ * Render the inline reference phrase. `binding` is the caller-formatted slot
+ * string: `"reference image A"` (image, lettered) or `"@image_3"` (video).
+ * Most roles are nouns and slot into the default template; the two non-noun
+ * specials get a hand-tuned phrasing so the prompt reads naturally.
+ */
+export function roleToPhrase(role: string, binding: string): string {
+  const r = role.trim()
+  if (!r) return binding
+  switch (r) {
+    case "as-is":
+      return `${binding}, used as-is`
+    case "empty background":
+      return `the background from ${binding} (without its foreground objects)`
+    default:
+      return `the ${r} from ${binding}`
+  }
+}
+
+/**
+ * Map a location role SLUG — as it appears in a `@location:N:<slug>` mention
+ * token (lowercase, dash-joined, no spaces) — back to its canonical phrase key
+ * so `roleToPhrase` matches the non-noun specials. Only the multi-word
+ * `wired-location` presets need remapping (`empty-background` → `empty
+ * background`); single-token roles and `as-is` (whose phrase key keeps the
+ * hyphen) and free-form custom slugs pass through unchanged.
+ *
+ * Data-driven from `REFERENCE_ROLE_PRESETS["wired-location"]` (the single source
+ * of truth for the location vocabulary): a preset whose space→dash slug equals
+ * `slug` maps back to the preset's phrase form, so a future multi-word preset is
+ * handled with no extra wiring. Mention tokens are slug-form (the grammar
+ * segment is `[a-z][a-z0-9-]*`), so the role is stored verbatim on the token and
+ * normalized HERE at the consumption points — the location mention resolver
+ * (before `roleToPhrase`) and the location role pill (display label). The
+ * character side never needs this: character role slugs are single tokens that
+ * already equal their phrase key.
+ */
+export function normalizeRoleSlug(slug: string): string {
+  const s = slug.trim()
+  if (!s) return s
+  for (const preset of REFERENCE_ROLE_PRESETS["wired-location"]) {
+    if (preset.toLowerCase().replace(/\s+/g, "-") === s) return preset
+  }
+  return s
+}
+
+/**
+ * Role for a FIRST-SIGHT character extra-ref in HYBRID assembly. The `segment`
+ * is the role when it is a curated preset for `source`; otherwise the source
+ * default. This mirrors the segment→role preset gate the mention-hybrid paths
+ * use, minus their custom-role-survival relaxation (an extra has no parsed
+ * `usageMode == null` signal to tell a role from a variant pick).
+ *
+ * Shared by BOTH the image (`renderExtraRefsHybrid` in `prompt-builder.ts`) and
+ * video (`resolveVideoReferenceCore` extras first-sight in
+ * `video-reference-resolver.ts`) resolvers — and, as of the Reference Roles
+ * deferred-follow-up, they share the HELPER **and** its INPUT, so they are
+ * fully converged:
+ *   - image passes the COALESCED `defaultUsageMode`
+ *     (`usageMode` → char-node default → "identical", folded by
+ *     `expandExtraRefsToConnectedReferences`).
+ *   - video passes its COALESCED `effectiveMode`
+ *     (`ex.usageMode` → char-node default (`lookupCharacterBySlug`) →
+ *     "identical") — the identical resolution chain, already computed for the
+ *     legacy directive path.
+ * Both are always defined for a real character extra, so no `variantSlug`
+ * fallback is needed on either side. A character whose node default is
+ * Face/Pose/Style now resolves an un-overridden extra to that default on BOTH
+ * image and video (and consistently with the video legacy path). The single
+ * source of truth for the coalescing is the per-ref override → char-node
+ * default → "identical" chain, applied at both call sites.
+ */
+export function firstSightExtraRole(
+  segment: string | null | undefined,
+  source: ReferenceSource,
+): string {
+  const s = (segment ?? "").trim()
+  return s && REFERENCE_ROLE_PRESETS[source].includes(s) ? s : defaultRoleForSource(source)
+}
+
+/**
+ * The effective default role for a wired entity, given the node's explicit
+ * hybrid `defaultRole` and its legacy `defaultUsageMode`. Single source of truth
+ * for the node-default precedence, read at every hybrid resolver site (image +
+ * video × extras / canonical / mention):
+ *
+ *   1. `defaultRole` (the hybrid dropdown pick) — used VERBATIM when non-blank,
+ *      so a Custom role like `earrings` survives (mirrors the pill's Custom
+ *      relaxation) and beats any legacy `defaultUsageMode`.
+ *   2. else `firstSightExtraRole(defaultUsageMode, source)` — the back-compat
+ *      mapping (`face`/`pose`/`style` pass through; every other usage mode, and
+ *      an absent one, collapse to the source default, e.g. `"person"`).
+ *
+ * A per-mention token role (the pill / autocomplete) still wins over this at the
+ * mention call sites; this is only the NODE-level fallback.
+ */
+export function resolveDefaultRole(
+  defaultRole: string | null | undefined,
+  defaultUsageMode: string | null | undefined,
+  source: ReferenceSource,
+): string {
+  const explicit = defaultRole?.trim()
+  if (explicit) return explicit
+  return firstSightExtraRole(defaultUsageMode, source)
+}
+
+/**
+ * Sanitize a free-form Custom role into a character-variant-slug-safe token.
+ * Hoisted to shared (was `config-panels/prompt-editor/character-ref-roles.ts`)
+ * so BOTH the mention pill and the character node's role dropdown share one
+ * source of truth. Grammar is `[a-z][a-z0-9-]*` (the `variantSlug` token slot):
+ * lower-case, dash-join whitespace, drop out-of-grammar chars, force a leading
+ * letter, cap at 32, collapse dash runs, drop a trailing dash — keeping the
+ * emitted role re-parseable and matching `characterMentionSlug`'s slugification.
+ */
+export function sanitizeRole(raw: string): string {
+  return raw
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/^[^a-z]+/, "") // grammar requires a leading [a-z]
+    .slice(0, 32)
+    .replace(/-+/g, "-") // collapse dash runs (matches characterMentionSlug)
+    .replace(/-$/, "") // drop a trailing dash (incl. one left by the 32-cap)
+}

package/src/reference-sheet/__tests__/board-to-column.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest"
+import { BOARD_TO_COLUMN, BOARD_VARIANTS } from "../catalog.js"
+import type { EntityKind } from "../types.js"
+
+const ENTITIES: EntityKind[] = ["character", "object", "location"]
+describe("BOARD_TO_COLUMN", () => {
+  it("maps character boards to DB columns", () => {
+    expect(BOARD_TO_COLUMN.character.headAngles).toBe("angles")
+    expect(BOARD_TO_COLUMN.character.bodyAngles).toBe("body_angles")
+    expect(BOARD_TO_COLUMN.character.detail).toBe("detail_closeups")
+    expect(BOARD_TO_COLUMN.character.wardrobe).toBe("outfit_variations")
+  })
+  it("maps location camelCase boards to snake_case columns", () => {
+    expect(BOARD_TO_COLUMN.location.timeOfDay).toBe("time_of_day")
+    expect(BOARD_TO_COLUMN.location.detail).toBe("detail_closeups")
+  })
+  it("every board in BOARD_VARIANTS has a column (no orphan)", () => {
+    for (const e of ENTITIES) for (const b of Object.keys(BOARD_VARIANTS[e])) expect(BOARD_TO_COLUMN[e][b], `${e}/${b}`).toBeDefined()
+  })
+})

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

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "vitest"
+import {
+  ENTITY_SECTIONS, BOARD_VARIANTS, SECTION_BOARD, DEFAULT_SECTIONS, DETAIL_VARIANTS, WARDROBE_VARIANTS,
+} from "../catalog.js"
+import { SECTION_KINDS, SHEET_TYPES, type EntityKind } from "../types.js"
+import { CHARACTER_ASSET_VARIANTS, OBJECT_ASSET_VARIANTS, LOCATION_ASSET_VARIANTS } from "../../entity-asset-types.js"
+
+const ENTITIES: EntityKind[] = ["character", "object", "location"]
+
+describe("catalog invariants", () => {
+  it("every entity's available sections are valid SectionKinds", () => {
+    for (const e of ENTITIES) for (const s of ENTITY_SECTIONS[e]) expect(SECTION_KINDS).toContain(s)
+  })
+  it("character board variants come from the canonical CHARACTER_ASSET_VARIANTS", () => {
+    expect(BOARD_VARIANTS.character.headAngles).toEqual(CHARACTER_ASSET_VARIANTS.headAngles)
+    expect(BOARD_VARIANTS.character.bodyAngles).toEqual(CHARACTER_ASSET_VARIANTS.bodyAngles)
+    expect(BOARD_VARIANTS.character.expressions).toEqual(CHARACTER_ASSET_VARIANTS.expressions)
+    expect(BOARD_VARIANTS.character.poses).toEqual(CHARACTER_ASSET_VARIANTS.poses)
+  })
+  it("object & location board variants come from the hoisted lists", () => {
+    expect(BOARD_VARIANTS.object.angles).toEqual(OBJECT_ASSET_VARIANTS.angles)
+    expect(BOARD_VARIANTS.object.materials).toEqual(OBJECT_ASSET_VARIANTS.materials)
+    expect(BOARD_VARIANTS.location.timeOfDay).toEqual(LOCATION_ASSET_VARIANTS.timeOfDay)
+    expect(BOARD_VARIANTS.location.angles).toEqual(LOCATION_ASSET_VARIANTS.angles)
+  })
+  it("headAngles includes back-of-head, appended after the default-4 slice", () => {
+    const head = CHARACTER_ASSET_VARIANTS.headAngles
+    expect(head).toContain("back")
+    expect(head.indexOf("back")).toBeGreaterThanOrEqual(4) // keeps slice(0,4) stable
+    expect(head.slice(0, 4)).toEqual(["front", "3/4 left", "left profile", "right profile"])
+  })
+  it("new buckets (detail/wardrobe) have starter presets", () => {
+    expect(DETAIL_VARIANTS.character.length).toBeGreaterThan(0)
+    expect(WARDROBE_VARIANTS.length).toBeGreaterThan(0)
+  })
+  it("DEFAULT_SECTIONS exists for every (entity, type) and only references available sections", () => {
+    for (const e of ENTITIES) for (const t of SHEET_TYPES) {
+      const secs = DEFAULT_SECTIONS[e][t]
+      expect(Array.isArray(secs)).toBe(true)
+      for (const s of secs) expect(ENTITY_SECTIONS[e]).toContain(s.kind)
+    }
+  })
+  it("every board-typed section a default uses resolves to a real board with variants", () => {
+    for (const e of ENTITIES) for (const t of SHEET_TYPES) for (const s of DEFAULT_SECTIONS[e][t]) {
+      const board = s.board ?? SECTION_BOARD[s.kind]
+      if (board === null) continue // structural section (header/palette/notes/scale)
+      expect(BOARD_VARIANTS[e][board!], `${e}/${t}/${s.kind} -> ${board}`).toBeDefined()
+    }
+  })
+})

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

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest"
+import { estimateSheetCost } from "../cost.js"
+import { SHEET_PRESETS } from "../presets.js"
+import type { SheetFlavour, SheetSection } from "../types.js"
+
+const fl: SheetFlavour = { outputFormat: "still", withText: true, showLabels: true, aspect: "landscape", background: "grey" }
+const main = SHEET_PRESETS.find((p) => p.id === "studio-main")!
+
+describe("estimateSheetCost", () => {
+  it("all panels missing → prepareCost = missing × perPanel, total += assembly", () => {
+    const e = estimateSheetCost("character", main.baseSections, fl, {}, "Kaia", 1, 4)
+    expect(e.missing).toHaveLength(7)
+    expect(e.present).toBe(0)
+    expect(e.prepareCost).toBe(7)
+    expect(e.total).toBe(11)
+    expect(e.overflow).toBe(false)
+  })
+  it("present panels are not re-charged", () => {
+    const buckets = { angles: [{ name: "front", url: "u/f" }], body_angles: [{ name: "front", url: "u/bf" }] }
+    const e = estimateSheetCost("character", main.baseSections, fl, buckets, "Kaia", 1, 4)
+    expect(e.present).toBe(2)
+    expect(e.prepareCost).toBe(5)
+    expect(e.total).toBe(9)
+  })
+  it("overflow (> MAX_PANELS) returns overflow:true instead of throwing", () => {
+    // 25 explicit entries > MAX_PANELS_PER_SHEET (24) → planSheetPanels throws;
+    // estimateSheetCost must catch it. (panelCount would clamp to the board
+    // length and never overflow, so use entries to force it.)
+    const huge: SheetSection[] = [{
+      kind: "head-turnaround",
+      entries: Array.from({ length: 25 }, (_, i) => ({ kind: "preset" as const, variant: `v${i}` })),
+    }]
+    const e = estimateSheetCost("character", huge, fl, {}, "Kaia", 1, 4)
+    expect(e.overflow).toBe(true)
+    expect(e.missing).toHaveLength(0)
+    expect(e.total).toBe(4) // assembly only
+  })
+})

package/src/reference-sheet/__tests__/no-drift.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from "vitest"
+import { BOARD_VARIANTS, DEFAULT_SECTIONS, SECTION_BOARD } from "../catalog.js"
+import { planSheetPanels } from "../panel-plan.js"
+import { SHEET_TYPES, SECTION_KINDS, type EntityKind, type SheetFlavour } from "../types.js"
+
+const ENTITIES: EntityKind[] = ["character", "object", "location"]
+const fl: SheetFlavour = { outputFormat: "still", withText: true, showLabels: true, aspect: "landscape", background: "grey" }
+
+describe("no-drift: planned preset panels are real board variants", () => {
+  it("every default full-reference plans without throwing and only uses known variants", () => {
+    for (const e of ENTITIES) for (const t of SHEET_TYPES) {
+      const panels = planSheetPanels(e, DEFAULT_SECTIONS[e][t], fl)
+      for (const p of panels) {
+        if (p.custom) continue
+        expect(BOARD_VARIANTS[e][p.board], `${e}/${t} ${p.board}`).toContain(p.variant)
+      }
+    }
+  })
+  it("SECTION_BOARD has an entry for every SectionKind (no kind missing)", () => {
+    // Guards `resolveBoard`: adding a SectionKind without a SECTION_BOARD entry
+    // would make `SECTION_BOARD[kind]` undefined and silently mis-resolve. Iterate
+    // the full SECTION_KINDS list — not just the ones used in defaults — so a new
+    // kind can't slip in unmapped.
+    for (const k of SECTION_KINDS) {
+      expect(SECTION_BOARD, k).toHaveProperty(k)
+    }
+  })
+})