@nodaro/shared 1.4.1

package/src/reference-sheet/presets.ts

@@ -0,0 +1,77 @@
+import type { SheetSection, SheetEntry, SheetType, SheetSkin, SheetAspect, SheetPresetId } from "./types.js"
+
+export type { SheetPresetId }
+
+/** Build ordered preset entries from a variant list (a curated board subset). */
+export const presetEntries = (vs: readonly string[]): SheetEntry[] =>
+  vs.map((variant) => ({ kind: "preset", variant }))
+
+export interface SheetPreset {
+  id: SheetPresetId
+  label: string
+  description: string
+  /** Carrier for the route's required `type` enum; the layout comes from `baseSections`. */
+  type: SheetType
+  baseSections: SheetSection[]
+  skin: SheetSkin
+  aspect: SheetAspect
+}
+
+/**
+ * Studio sheet presets (character only). Each bundles a curated head+body
+ * turnaround (via `entries`) + a default skin/aspect + a carrier `type`. The
+ * à-la-carte boards below layer optional extra bands on top.
+ *
+ * `studio-main` is the clean screenshot format (head: front, profiles, back-of-
+ * head; body: front, side, back). `studio-extended` adds above/below + 3/4
+ * angles for fuller coverage.
+ */
+export const SHEET_PRESETS: readonly SheetPreset[] = [
+  {
+    id: "studio-main",
+    label: "Studio · Main",
+    description: "Clean turnaround for AI video reference — head (front, profiles, back) + body (front, side, back).",
+    type: "turnaround",
+    skin: "studio",
+    aspect: "landscape",
+    baseSections: [
+      { kind: "head-turnaround", entries: presetEntries(["front", "left profile", "right profile", "back"]) },
+      { kind: "body-turnaround", entries: presetEntries(["front", "left profile", "back"]) },
+    ],
+  },
+  {
+    id: "studio-extended",
+    label: "Studio · Extended",
+    description: "Full turnaround — adds above/below and 3/4 angles for maximum coverage.",
+    type: "full-reference",
+    skin: "studio",
+    aspect: "landscape",
+    baseSections: [
+      { kind: "head-turnaround", entries: presetEntries(["front", "3/4 left", "left profile", "right profile", "3/4 right", "above", "below", "back"]) },
+      { kind: "body-turnaround", entries: presetEntries(["front", "3/4 left", "left profile", "right profile", "back", "above", "below"]) },
+    ],
+  },
+]
+
+export const PRESET_LABELS: Record<SheetPresetId, string> = {
+  "studio-main": "Studio · Main",
+  "studio-extended": "Studio · Extended",
+}
+
+export interface AlaCarteBoard {
+  id: string
+  label: string
+  /** UI hint: panels this board adds (the board's default slice). Free boards are 0. */
+  panelCount: number
+  section: SheetSection
+}
+
+/** Optional boards layered on a base preset. No `entries` → the planner uses the
+ *  board's default slice (`min(4, board length)`). Palette is structural (free). */
+export const ALA_CARTE_BOARDS: readonly AlaCarteBoard[] = [
+  { id: "expressions", label: "Expressions", panelCount: 4, section: { kind: "expression-board" } },
+  { id: "poses",       label: "Poses",       panelCount: 4, section: { kind: "pose-board" } },
+  { id: "wardrobe",    label: "Wardrobe",    panelCount: 3, section: { kind: "wardrobe-board" } },
+  { id: "detail",      label: "Detail",      panelCount: 3, section: { kind: "detail-board" } },
+  { id: "palette",     label: "Palette",     panelCount: 0, section: { kind: "palette" } },
+]

package/src/reference-sheet/types.ts

@@ -0,0 +1,92 @@
+export type EntityKind = "character" | "object" | "location"
+
+export const SHEET_TYPES = ["turnaround", "variation-board", "detail", "full-reference"] as const
+export type SheetType = (typeof SHEET_TYPES)[number]
+
+export const SHEET_SKINS = ["studio", "cinematic", "blueprint", "illustrated"] as const
+export type SheetSkin = (typeof SHEET_SKINS)[number]
+
+export const SHEET_ASPECTS = ["landscape", "square", "story"] as const
+export type SheetAspect = (typeof SHEET_ASPECTS)[number]
+
+/** Studio sheet presets (character only). Declared here so SheetFlavour can carry
+ *  it without a cycle (`presets.ts` re-exports it alongside the registry). */
+export type SheetPresetId = "studio-main" | "studio-extended"
+
+export const OUTPUT_FORMATS = ["still", "motion"] as const
+export type OutputFormat = (typeof OUTPUT_FORMATS)[number]
+
+export const SECTION_KINDS = [
+  "header",
+  "head-turnaround", "body-turnaround", "turnaround", "coverage",
+  "expression-board", "pose-board", "material-board", "variation-board", "environment-board",
+  "detail-board", "wardrobe-board",
+  "palette", "scale", "notes",
+] as const
+export type SectionKind = (typeof SECTION_KINDS)[number]
+
+export const SHEET_BACKGROUNDS = ["grey", "white", "transparent", "in-context"] as const
+export type SheetBackground = (typeof SHEET_BACKGROUNDS)[number]
+
+/** A board entry is either a catalog preset (by variant) or a user-authored custom panel. */
+export interface PresetEntry { kind: "preset"; variant: string }
+export interface CustomEntry { kind: "custom"; label: string; prompt: string }
+export type SheetEntry = PresetEntry | CustomEntry
+
+/** One band in the sheet. `board` disambiguates kinds that map to several buckets (environment-board). */
+export interface SheetSection {
+  kind: SectionKind
+  board?: string
+  subtitle?: string
+  panelCount?: number
+  entries?: SheetEntry[]   // omitted => planner fills the default preset set
+}
+
+export interface SheetFlavour {
+  outputFormat: OutputFormat
+  withText: boolean
+  showLabels: boolean
+  aspect: SheetAspect
+  background: SheetBackground
+  sections?: SheetSection[]   // explicit stack for `full-reference`; other types derive defaults
+  presetId?: SheetPresetId    // labels studio preset sheets; inert to pricing/composition
+}
+
+/** A single panel the planner says must exist (reused or generated). */
+export interface PanelRequest {
+  section: SectionKind
+  board: string       // logical board key (maps to a DB column via the backend adapter, Plan 04)
+  variant: string     // preset variant string, or the custom label
+  label: string
+  custom: boolean
+  prompt?: string      // present iff custom
+}
+
+export interface Swatch { hex: string; label: string }
+export interface PanelSource { board: string; variant: string; assetId?: string; url: string }
+export interface SheetTextData {
+  title?: string
+  metadata?: Record<string, string>
+  notes?: string
+  sectionLabels?: Record<string, string>
+}
+
+export interface ReferenceSheet {
+  id: string
+  type: SheetType
+  skin: SheetSkin
+  flavour: SheetFlavour
+  source: "studio" | "node"
+  url: string
+  panelUrls: string[]
+  panelSources: PanelSource[]
+  sectionsSnapshot: SheetSection[]
+  metadataSnapshot: SheetTextData
+  paletteSnapshot: Swatch[]
+  sourceImageUrlAtGen: string
+  createdAt: string
+}
+
+/** Hard ceilings (also re-asserted in the route Zod schema, Plan 04). */
+export const MAX_PANELS_PER_SHEET = 24
+export const MAX_CUSTOM_ENTRIES_PER_BOARD = 12

package/src/repeat-types.ts

@@ -0,0 +1,97 @@
+/** AI generation node types that support repeat-N execution.
+ *  Excludes deterministic nodes, FFmpeg, social, render, and utility nodes. */
+export const REPEATABLE_NODE_TYPES = new Set([
+  "generate-image", "edit-image", "image-to-image",
+  "image-to-video", "video-to-video", "text-to-video",
+  "text-to-speech", "generate-music", "text-to-audio", "text-to-dialogue",
+  "ai-writer", "llm-chat", "generate-script",
+  "suno-generate", "suno-cover", "suno-extend", "suno-lyrics",
+  "lip-sync", "speech-to-video",
+  "motion-transfer", "extend-video",
+  "video-composer", "after-effects", "lottie-overlay", "3d-title", "motion-graphics",
+  "voice-changer", "dubbing", "voice-remix", "voice-design",
+  "component",
+])
+
+/** Sentinel value used as list item for repeat-only execution (no list fan-out input).
+ *  executeNodeForList skips the overridePrompt/overrideMediaUrl when it sees this. */
+export const REPEAT_PLACEHOLDER = "__repeat__"
+
+/** Sentinel prefix for per-iteration provider override.
+ *  An item like `__provider:nano-banana__` tells executeNodeForList to clone the
+ *  node with `data.provider = "nano-banana"` for that iteration and otherwise
+ *  behave like REPEAT_PLACEHOLDER (no prompt/media override). */
+export const PROVIDER_PLACEHOLDER_PREFIX = "__provider:"
+const PROVIDER_PLACEHOLDER_SUFFIX = "__"
+
+export function encodeProviderItem(provider: string): string {
+  return `${PROVIDER_PLACEHOLDER_PREFIX}${provider}${PROVIDER_PLACEHOLDER_SUFFIX}`
+}
+
+export function decodeProviderItem(item: string): string | undefined {
+  if (!item.startsWith(PROVIDER_PLACEHOLDER_PREFIX)) return undefined
+  if (!item.endsWith(PROVIDER_PLACEHOLDER_SUFFIX)) return undefined
+  const inner = item.slice(
+    PROVIDER_PLACEHOLDER_PREFIX.length,
+    item.length - PROVIDER_PLACEHOLDER_SUFFIX.length,
+  )
+  return inner.length > 0 ? inner : undefined
+}
+
+/** Read repeatCount from node data, clamped to 1-20. Returns 1 if unset/invalid. */
+export function getEffectiveRepeatCount(nodeData: Record<string, unknown>): number {
+  const raw = nodeData.repeatCount as number | undefined
+  if (!raw || raw <= 1) return 1
+  return Math.min(Math.max(Math.floor(raw), 1), 20)
+}
+
+/** Read providers array from node data. Returns the array only when it has 2+
+ *  entries; one provider is equivalent to single-provider mode. */
+function getEffectiveProviders(nodeData: Record<string, unknown>): readonly string[] | undefined {
+  const raw = nodeData.providers as readonly unknown[] | undefined
+  if (!raw || raw.length < 2) return undefined
+  const cleaned = raw.filter((p): p is string => typeof p === "string" && p.length > 0)
+  return cleaned.length >= 2 ? cleaned : undefined
+}
+
+/**
+ * Expand list items by repeatCount, or create synthetic repeat / provider items.
+ *
+ * Resolution order:
+ * 1. If an upstream list exists, the list drives expansion (repeatCount multiplies).
+ * 2. Else if `data.providers` has 2+ entries, emit `providers.length × repeatCount`
+ *    items — each provider runs `repeatCount` times consecutively.
+ * 3. Else if repeatCount > 1, emit `repeatCount` synthetic items.
+ * 4. Otherwise return null — single execution, no fan-out.
+ */
+export function expandItemsWithRepeat(
+  listItems: string[] | undefined,
+  nodeType: string,
+  nodeData: Record<string, unknown>,
+): string[] | null {
+  const repeatCount = REPEATABLE_NODE_TYPES.has(nodeType)
+    ? getEffectiveRepeatCount(nodeData)
+    : 1
+
+  if (listItems && listItems.length > 1) {
+    const expanded = repeatCount > 1
+      ? listItems.flatMap(item => Array(repeatCount).fill(item) as string[])
+      : listItems
+    return expanded
+  }
+
+  const providers = getEffectiveProviders(nodeData)
+  if (providers) {
+    // Cross-product: each provider runs `repeatCount` times. Same provider's
+    // iterations are grouped (better for UI progress + caching).
+    return providers.flatMap(p =>
+      Array(Math.max(repeatCount, 1)).fill(encodeProviderItem(p)) as string[],
+    )
+  }
+
+  if (repeatCount > 1) {
+    return Array(repeatCount).fill(REPEAT_PLACEHOLDER) as string[]
+  }
+
+  return null
+}

package/src/resolve-field-mappings.ts

@@ -0,0 +1,119 @@
+import { injectUpstream } from "./inject-upstream.js"
+
+/**
+ * Resolve fieldMappings + {} injection for all text fields on a node.
+ *
+ * Three resolution mechanisms, in precedence order per field:
+ *   1. edge source: a live edge into the field's handle → use that node's
+ *      output. Prefix-agnostic — the caller decides which edges map to which
+ *      field (e.g. FE/BE wrappers match `field-<key>` handles). Wins over both
+ *      fieldMappings and {} injection.
+ *   2. fieldMappings: field mapped to source node → use that node's output
+ *   3. {} injection: manual field contains {} → replace with upstreamText
+ *
+ * Does NOT inject upstream into empty unmapped fields — that stays in
+ * per-node execution code (e.g., d.prompt || inputs.prompt).
+ *
+ * The `getSourceOutput` callback abstracts how source node output is
+ * extracted — frontend reads from live React Flow state, backend reads
+ * from NodeExecutionState.output. Same pattern as ancestor-refs.ts.
+ *
+ * `edgeSourceForField` is optional: when omitted, behaviour is identical to
+ * the prior fieldMappings-only resolver (existing callers stay valid).
+ */
+export function resolveFieldMappings(
+  data: Record<string, unknown>,
+  upstreamText: string | undefined,
+  mappableFieldNames: ReadonlyArray<string>,
+  getSourceOutput: (sourceNodeId: string) => string | undefined,
+  edgeSourceForField?: (field: string) => string | undefined,
+): Record<string, unknown> {
+  const fm = data.fieldMappings as Record<string, { sourceNodeId: string }> | undefined
+  const resolved = { ...data }
+
+  for (const field of mappableFieldNames) {
+    const sourceNodeId = edgeSourceForField?.(field) ?? fm?.[field]?.sourceNodeId
+
+    if (sourceNodeId) {
+      const output = getSourceOutput(sourceNodeId)
+      if (output != null) resolved[field] = output
+    } else {
+      const current = resolved[field]
+      if (typeof current === "string") {
+        const injected = injectUpstream(current, upstreamText)
+        if (injected !== current) resolved[field] = injected
+      }
+    }
+  }
+
+  return resolved
+}
+
+/**
+ * Location buckets that may carry generated/uploaded variants. Mirrors the
+ * full set of attachable buckets in `entity-prompts.ts::LOCATION_ATTACH_COLUMNS`,
+ * but in camelCase (matching the in-memory location object and the
+ * `WorkflowExportLocation` export shape).
+ */
+const LOCATION_BUCKETS = [
+  "timeOfDay",
+  "weather",
+  "seasons",
+  "angles",
+  "lighting",
+  "atmosphereMotions",
+] as const
+
+interface LocationFieldEntry {
+  /** Stable key — `sourceImageUrl` or `<bucket>[<index>]`. */
+  key: string
+  /** Human-readable label — `Main image` or `<bucket> / <variant.name>`. */
+  label: string
+  /** R2 URL of the image. */
+  url: string
+}
+
+/**
+ * Flatten a location's anchor image and every variant bucket into a single
+ * ordered list of `{ key, label, url }` entries. Used by picker UIs and
+ * ref-resolvers that need a stable, position-keyed view of every image
+ * attached to a location.
+ *
+ * Bucket iteration order is fixed (see `LOCATION_BUCKETS`) so frontend and
+ * backend produce identical lists from the same fixture. Missing buckets and
+ * non-array values are treated as empty — the helper never throws.
+ *
+ * Mirrors the future character/object variants of this helper; same shape
+ * (`key`, `label`, `url`) so callers can be polymorphic over entity kind.
+ */
+export function resolveLocationFields(
+  loc: Record<string, unknown>,
+): LocationFieldEntry[] {
+  const out: LocationFieldEntry[] = []
+
+  if (typeof loc.sourceImageUrl === "string" && loc.sourceImageUrl.length > 0) {
+    out.push({
+      key: "sourceImageUrl",
+      label: "Main image",
+      url: loc.sourceImageUrl,
+    })
+  }
+
+  for (const bucket of LOCATION_BUCKETS) {
+    const raw = loc[bucket]
+    if (!Array.isArray(raw)) continue
+    raw.forEach((item, i) => {
+      if (!item || typeof item !== "object") return
+      const variant = item as { name?: unknown; url?: unknown }
+      if (typeof variant.url !== "string" || variant.url.length === 0) return
+      const name = typeof variant.name === "string" ? variant.name : ""
+      out.push({
+        key: `${bucket}[${i}]`,
+        label: `${bucket} / ${name}`,
+        url: variant.url,
+      })
+    })
+  }
+
+  return out
+}

package/src/route-filter.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared BFS utility for computing reachable node IDs along a route.
+ * Used by both frontend (RunTargetSelector stale guard) and backend
+ * (presentation.ts, app-runner.ts, sub-workflow-handler.ts).
+ */
+
+export interface MinimalNode {
+  id: string
+  type?: string
+  data: Record<string, unknown>
+}
+
+export interface MinimalEdge {
+  source: string
+  target: string
+}
+
+/**
+ * BFS in one direction from a start node.
+ */
+function bfs(
+  startId: string,
+  edges: readonly MinimalEdge[],
+  direction: "forward" | "backward",
+): Set<string> {
+  const visited = new Set<string>()
+  const queue = [startId]
+
+  while (queue.length > 0) {
+    const current = queue.shift()!
+    if (visited.has(current)) continue
+    visited.add(current)
+
+    for (const edge of edges) {
+      if (direction === "forward" && edge.source === current && !visited.has(edge.target)) {
+        queue.push(edge.target)
+      } else if (direction === "backward" && edge.target === current && !visited.has(edge.source)) {
+        queue.push(edge.source)
+      }
+    }
+  }
+
+  return visited
+}
+
+/**
+ * Compute the set of node IDs reachable along a route.
+ * 1. Finds the sub-workflow-input node with matching routeId
+ * 2. Finds the sub-workflow-output node with matching routeId
+ * 3. BFS forward from input, BFS backward from output, intersect
+ * Returns empty set if input or output node not found (stale routeId).
+ */
+export function getRouteReachableNodeIds(
+  nodes: readonly MinimalNode[],
+  edges: readonly MinimalEdge[],
+  routeId: string,
+): Set<string> {
+  const inputNode = nodes.find(
+    (n) => n.type === "sub-workflow-input" && (n.data as Record<string, unknown>).routeId === routeId,
+  )
+  const outputNode = nodes.find(
+    (n) => n.type === "sub-workflow-output" && (n.data as Record<string, unknown>).routeId === routeId,
+  )
+
+  if (!inputNode || !outputNode) return new Set()
+
+  const forwardReachable = bfs(inputNode.id, edges, "forward")
+  const backwardReachable = bfs(outputNode.id, edges, "backward")
+
+  const reachable = new Set<string>()
+  for (const id of forwardReachable) {
+    if (backwardReachable.has(id)) reachable.add(id)
+  }
+
+  // Always include input and output
+  reachable.add(inputNode.id)
+  reachable.add(outputNode.id)
+
+  return reachable
+}