@nodaro/shared 1.4.2

package/src/node-preset-extract.ts

@@ -0,0 +1,147 @@
+import { EXECUTION_DATA_KEYS } from "./node-runtime-keys.js"
+import { COMPOSER_PLAN_FIELDS } from "./model-constants.js"
+
+/**
+ * Generated-plan state on composer nodes that a preset must NEITHER capture NOR
+ * carry, and that the dropdown must CLEAR when applying a preset:
+ *
+ *  - every composer node's plan field (`COMPOSER_PLAN_MAP[*].planField` —
+ *    sceneGraph / effectPlan / overlayPlan / titlePlan / motionPlan /
+ *    compositePlan): a large LLM-authored plan blob, regenerated per run.
+ *  - `lottieUrl`: the R2 url of the authored Lottie JSON (motion-graphics'
+ *    `lottie` handle output) — a reapable generated artifact, not config.
+ *
+ * Derived from the single source of truth (COMPOSER_PLAN_MAP) so a new composer
+ * node type is covered by construction — no per-type list to keep in sync.
+ *
+ * Two distinct hazards this closes (see motion-graphics-presets design §2a/§2b):
+ *  1. Apply-time staleness: applying a preset over a node that already generated
+ *     a plan would leave the OLD animation showing under the NEW prompt (the
+ *     plan field is named by no patch, so it persists in the preview and on the
+ *     output handle). The dropdown spreads `{ ...clearPatch, ...preset.data }`
+ *     where clearPatch maps each key here to `undefined`.
+ *  2. Capture pollution: a user-saved preset would otherwise capture the plan
+ *     blob (~tens of KB) + a stale url, re-injecting them on every apply and
+ *     bloating the preset row. These keys are in the capture-exclusion set below.
+ */
+export const PRESET_APPLY_CLEAR_KEYS: readonly string[] = [...COMPOSER_PLAN_FIELDS, "lottieUrl"]
+
+/**
+ * Config fields that are intentionally NOT part of a preset, because they are not portable
+ * configuration — they identify the node on the canvas, wire it into one specific graph, or point
+ * at specific DB entities. Capturing them would make a preset silently wrong when applied to a
+ * different node or workflow. This is the single place that defines that contract, so the system
+ * stays correct-by-construction as new node types are added.
+ *
+ *  Identity:
+ *  - `label`: the node's canvas identity. Presets carry their own name and must not rename the node.
+ *
+ *  Graph wiring (reference specific upstream node / handle / tile ids — meaningless elsewhere):
+ *  - `fieldMappings`: field -> upstream node id.
+ *  - `referenceImageOrder` / `referenceOrder` / `connectedMediaOrder` / `connectedRefImageOrder`:
+ *    orderings keyed by the ids of wired upstream references.
+ *
+ *  Structural identifiers (handle / port / route / channel ids that must stay unique per node and
+ *  that downstream edges target — copying them across nodes orphans edges or duplicates a channel):
+ *  - `routes` / `routeId` / `routeIds`: router routes + sub-workflow/condition route pairing ids.
+ *  - `ports` / `inputPorts` / `outputPorts`: sub-workflow port arrays (each port has a handle id).
+ *  - `channel` / `channelColor`: teleport send/receive pairing channel (auto-assigned per node).
+ *
+ *  DB entity references / per-wiring identity state (tied to specific characters/locations):
+ *  - `characterDefinitionIds`, `suppressedCanonicalCharacterIds`, `suppressedCanonicalLocationIds`.
+ *  - `identityMeta`: per-identity overrides keyed by the wired identity's index/label.
+ *  - `extraRefs`: extra references carrying `characterSlug` + workflow-specific asset urls.
+ *
+ *  Preset meta:
+ *  - `__activePresetId`: which preset is currently loaded onto the node (for the dropdown's
+ *    active-name + dirty `*`). Node-local UI state, never part of a preset's own config.
+ *  - `__promptFinalView`: field keys currently showing the final-prompt view (Edit ⇄ Final
+ *    per-field toggle). Node-local UI state, never part of a preset's own config.
+ *
+ *  NOTE: manual reference image urls (`referenceImageUrl` / `referenceImageUrls`) are deliberately
+ *  KEPT — they are self-contained R2 urls a user set as input, and portable across nodes.
+ *
+ *  Generated composer-plan state (`PRESET_APPLY_CLEAR_KEYS` — every COMPOSER_PLAN_MAP plan field +
+ *  `lottieUrl`): NOT portable config — a per-run LLM-authored plan blob / reapable artifact url.
+ *  Excluded here (preset-scoped, zero blast radius) rather than via EXECUTION_DATA_KEYS, whose
+ *  non-preset consumers (undo-skip in use-workflow-store, auto-execute IGNORE_KEYS) would then
+ *  treat a legitimately-persisted plan as transient runtime state.
+ */
+export const PRESET_EXCLUDED_KEYS: ReadonlySet<string> = new Set([
+  "label",
+  "fieldMappings",
+  "__activePresetId",
+  "__promptFinalView",
+  "referenceImageOrder",
+  "referenceOrder",
+  "connectedMediaOrder",
+  "connectedRefImageOrder",
+  "characterDefinitionIds",
+  "suppressedCanonicalCharacterIds",
+  "suppressedCanonicalLocationIds",
+  "identityMeta",
+  "extraRefs",
+  // structural identifiers
+  "routes",
+  "routeId",
+  "routeIds",
+  "ports",
+  "inputPorts",
+  "outputPorts",
+  "channel",
+  "channelColor",
+  // generated composer-plan state (derived from COMPOSER_PLAN_MAP + lottieUrl)
+  ...PRESET_APPLY_CLEAR_KEYS,
+])
+
+/**
+ * Capture a node's reusable configuration from its `data`: a shallow copy minus runtime/result
+ * state (EXECUTION_DATA_KEYS) and graph/identity fields (PRESET_EXCLUDED_KEYS). Pure; never mutates
+ * the input. Node-type-agnostic — the node type is stored alongside the result by the caller.
+ */
+export function extractPresetData(
+  data: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(data)) {
+    if (EXECUTION_DATA_KEYS.has(key)) continue
+    if (PRESET_EXCLUDED_KEYS.has(key)) continue
+    out[key] = data[key]
+  }
+  return out
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (typeof a !== typeof b) return false
+  if (a === null || b === null) return a === b
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false
+    return a.every((v, i) => deepEqual(v, b[i]))
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const ka = Object.keys(a as object)
+    const kb = Object.keys(b as object)
+    if (ka.length !== kb.length) return false
+    return ka.every((k) =>
+      deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]),
+    )
+  }
+  return false
+}
+
+/**
+ * True iff the node's `data` still matches the preset — i.e. every key the preset defines
+ * deep-equals the node's current value. Compares only preset-defined keys (the node may carry
+ * extra keys the preset doesn't set, e.g. seed, which must NOT count as a mismatch). Used to drive
+ * the dropdown's dirty `*` indicator.
+ */
+export function presetDataMatches(
+  nodeData: Readonly<Record<string, unknown>>,
+  presetData: Readonly<Record<string, unknown>>,
+): boolean {
+  for (const key of Object.keys(presetData)) {
+    if (!deepEqual(nodeData[key], presetData[key])) return false
+  }
+  return true
+}

package/src/node-refs.ts

@@ -0,0 +1,253 @@
+/**
+ * Node reference pattern and resolution for {Node Label} template syntax.
+ * Shared between frontend and backend.
+ */
+
+/** Matches {Node Label} references in text. */
+export const NODE_REF_PATTERN = /\{([^}]+)\}/g
+
+/** Reserved template variable names that should NOT be resolved as node refs */
+export const RESERVED_TEMPLATE_VARS = new Set([
+  "name",
+  "description",
+  "userPrompt",
+  "assetDescriptions",
+  "outputCount",
+])
+
+/**
+ * Split a `{...}` token body into its node name and optional fallback. Splits on the FIRST `||`
+ * (a fallback may itself contain `||`); both sides are trimmed. `fallback` is null when there is
+ * no `||`, preserving the legacy "leave the literal token" behavior.
+ *   "person || man" -> { name: "person", fallback: "man" }
+ *   "person || "    -> { name: "person", fallback: "" }     (resolves to empty when absent)
+ *   "person"        -> { name: "person", fallback: null }   (literal {person} when absent)
+ */
+export function parseNodeRef(raw: string): { name: string; fallback: string | null } {
+  const i = raw.indexOf("||")
+  if (i === -1) return { name: raw.trim(), fallback: null }
+  return { name: raw.slice(0, i).trim(), fallback: raw.slice(i + 2).trim() }
+}
+
+/**
+ * Canonical form of a node-name variable: trimmed + lowercased. Node-name
+ * variables are CASE-INSENSITIVE with lowercase as canonical, so nodes labeled
+ * `TEXt`, `TEXT`, `text` all feed the one `{text}` variable and `{TEXT}` /
+ * `{Text}` / `{text}` in a prompt all resolve to it.
+ *
+ * Reserved template vars (RESERVED_TEMPLATE_VARS, e.g. `userPrompt`) are matched
+ * case-sensitively on the ORIGINAL token BEFORE canonicalization, so `{userPrompt}`
+ * stays a reserved token rather than becoming a `userprompt` node ref.
+ */
+export function canonicalVarName(label: string): string {
+  return label.trim().toLowerCase()
+}
+
+/**
+ * The distinct `{label}` names referenced across the given texts. Mirrors the
+ * canvas-side `referencedRefs`: strips the `|| fallback`, and ignores empty
+ * tokens, image-ref tokens (`{image:N}`), and RESERVED_TEMPLATE_VARS. Used to
+ * SUPPRESS auto-injection of a connected node the author already placed
+ * explicitly via `{label}` (so it isn't injected twice). `matchAll` over the
+ * global pattern does not mutate its lastIndex, so sharing the constant is safe.
+ */
+export function extractReferencedLabels(
+  ...texts: ReadonlyArray<string | undefined | null>
+): Set<string> {
+  const refs = new Set<string>()
+  for (const text of texts) {
+    if (typeof text !== "string" || text.length === 0) continue
+    for (const m of text.matchAll(NODE_REF_PATTERN)) {
+      const { name } = parseNodeRef(m[1] ?? "")
+      if (name === "" || name.startsWith("image:") || RESERVED_TEMPLATE_VARS.has(name)) continue
+      refs.add(canonicalVarName(name)) // case-insensitive: {Foo} suppresses a `foo` node
+    }
+  }
+  return refs
+}
+
+/** Handle → combine-order category for same-label `{label}` merging. Lower wins
+ *  first: prompt (0) → elements (1) → look family (2). Other handles are -1
+ *  (not combinable — they keep the per-engine last-wins/suffix behavior). */
+export const REF_HANDLE_CATEGORY: Readonly<Record<string, number>> = {
+  prompt: 0,
+  elements: 1,
+  look: 2,
+  cinematography: 2,
+  style: 2,
+}
+
+/** Combine-order category for a direct-parent edge's `targetHandle`; -1 when the
+ *  handle isn't one of the combinable prompt/elements/look handles. */
+export function refHandleCategory(targetHandle: string | null | undefined): number {
+  if (targetHandle != null && Object.prototype.hasOwnProperty.call(REF_HANDLE_CATEGORY, targetHandle)) {
+    return REF_HANDLE_CATEGORY[targetHandle]
+  }
+  return -1
+}
+
+/**
+ * Reference-handle id → resolved-input key. The SINGLE SOURCE OF TRUTH for which
+ * `targetHandle` ids carry image / video / audio reference inputs. Shared by the
+ * backend input-resolver (routes the wired URL into the matching
+ * `referenceImageUrls` / `referenceVideoUrls` / `referenceAudioUrls` slot) AND
+ * the positional `{image:N}` / `{video:N}` / `{audio:N}` body-token COUNTS in the
+ * FE preview (`video-prompt-assembly.ts`), FE run (`execute-node.ts`), and BE
+ * payload-builder.
+ *
+ * Two handle families map to the same keys:
+ *   - Legacy / i2v single-name ids (`references` / `reference-videos` /
+ *     `reference-audio`) — kept for un-migrated workflows.
+ *   - Canonical typed-handle ids the modern Generate Video node exposes
+ *     (`imageReferences` / `videoReferences` / `audioReferences`) — share the
+ *     resolved-input keys with the legacy ids so consumer code never forks.
+ */
+export const REFERENCE_HANDLE_MAP: Record<string, "referenceImageUrls" | "referenceVideoUrls" | "referenceAudioUrls"> = {
+  // Legacy / i2v single-name handle ids (kept for un-migrated workflows)
+  "references": "referenceImageUrls",
+  "reference-videos": "referenceVideoUrls",
+  "reference-audio": "referenceAudioUrls",
+  // New canonical typed-handle ids (Generate Video) — share the resolved-input
+  // keys with the legacy ids so payload-builder code doesn't fork.
+  "imageReferences": "referenceImageUrls",
+  "videoReferences": "referenceVideoUrls",
+  "audioReferences": "referenceAudioUrls",
+}
+
+/** The three reference modalities a reference handle can carry. */
+export type ReferenceModality = "image" | "video" | "audio"
+
+/**
+ * The reference MODALITY a `targetHandle` carries, or null when the handle is
+ * not a reference handle. Resolves BOTH the legacy single-name ids and the
+ * canonical Generate Video ids (via REFERENCE_HANDLE_MAP), so positional
+ * `{image:N}` / `{video:N}` / `{audio:N}` token counts cover every handle alias
+ * — without this, the generate-video `imageReferences` handle was silently
+ * uncounted and `{image:N}` tokens dropped to bare labels on the only creatable
+ * video node.
+ */
+export function referenceModalityForHandle(targetHandle: string | null | undefined): ReferenceModality | null {
+  if (targetHandle == null) return null
+  const key = REFERENCE_HANDLE_MAP[targetHandle]
+  return key === "referenceImageUrls" ? "image" : key === "referenceVideoUrls" ? "video" : key === "referenceAudioUrls" ? "audio" : null
+}
+
+/**
+ * Frame target handles (start / end keyframes). An image wired into one of these
+ * is a KEYFRAME, not an `{image:N}` reference: the backend appends frames at the
+ * TAIL of `reference_image_urls` (`resolveSeedance2Inputs`), never numbered. The
+ * editor MUST therefore exclude them from `{image:N}` numbering so editor token N
+ * equals the worker reference slot N.
+ *
+ * The SINGLE source of truth for "is this a frame handle," shared by the
+ * config-panel autocomplete (`video-configs.tsx`) AND the inline/modal builder
+ * (`connected-references.ts`) — without ONE definition those two surfaces drifted
+ * and the inline editor numbered the frame as `{image:1}` (the C1 bug). Frames
+ * are deliberately NOT in `REFERENCE_HANDLE_MAP`: they carry no reference
+ * modality, so `referenceModalityForHandle` already returns `null` for them on
+ * the count side — this set is the exclusion lever for the EDITOR-numbering side.
+ */
+export const FRAME_TARGET_HANDLES: ReadonlySet<string> = new Set(["startFrame", "endFrame"])
+
+/**
+ * Minimal structural edge shape {@link countRefModalityEdges} reads — only the
+ * two fields the count needs. Both the FE `WorkflowEdge` (xyflow `Edge`, whose
+ * `target` is a non-null string) and the BE `SimpleEdge` satisfy it.
+ */
+export interface RefModalityEdge {
+  target?: string | null
+  targetHandle?: string | null
+}
+
+/**
+ * Count the reference-handle edges of a given reference MODALITY wired into a
+ * node — the ONE positional `{image:N}` / `{video:N}` / `{audio:N}` counter
+ * shared by the FE preview (`video-prompt-assembly.ts`), the FE run
+ * (`execute-node.ts`), and the BE orchestrator (`payload-builder.ts`). Counting
+ * via `referenceModalityForHandle` (not a single handle string) covers BOTH the
+ * legacy single-name ids (`references` / `reference-videos` / `reference-audio`)
+ * AND the canonical Generate Video ids (`imageReferences` / `videoReferences` /
+ * `audioReferences`), so editor token N maps 1:1 to the worker
+ * `referenceImageUrls` / `referenceVideoUrls` / `referenceAudioUrls` slot N on
+ * every handle alias. This is the EDGE count (not the resolved/list-expanded URL
+ * count) so all three paths stay byte-identical; the edge-vs-resolved divergence
+ * for a reference edge that fans out to >1 URL (a List producer) is a shared,
+ * documented v1 limitation.
+ */
+export function countRefModalityEdges(
+  edges: ReadonlyArray<RefModalityEdge>,
+  nodeId: string,
+  modality: ReferenceModality,
+): number {
+  let n = 0
+  for (const e of edges) {
+    if (e.target === nodeId && referenceModalityForHandle(e.targetHandle) === modality) n += 1
+  }
+  return n
+}
+
+/** A candidate contribution to the `{label}` map: the node's label, its resolved
+ *  output, and its direct-parent handle category (-1 = not combinable / deeper). */
+export interface RefCandidate {
+  label: string
+  output: string
+  category: number
+}
+
+/**
+ * Same-label COMBINE: when ≥2 direct-parent candidates (category ≥ 0) share a
+ * label, `{label}` resolves to their values joined by ", " ordered prompt →
+ * elements → look, and within a category by candidate (edge) order. Returns a
+ * Map of ONLY the combined labels; the caller fills the rest with its own
+ * (FE suffix / BE last-wins) logic, skipping any label present here. Shared so
+ * the frontend executor and backend orchestrator never drift.
+ */
+export function combineSameLabelRefs(candidates: ReadonlyArray<RefCandidate>): Map<string, string> {
+  const byLabel = new Map<string, RefCandidate[]>()
+  for (const c of candidates) {
+    if (c.category < 0) continue
+    const key = canonicalVarName(c.label) // TEXt + TEXT + text collapse into one {text}
+    const arr = byLabel.get(key)
+    if (arr) arr.push(c)
+    else byLabel.set(key, [c])
+  }
+  const combined = new Map<string, string>()
+  for (const [label, group] of byLabel) {
+    if (group.length < 2) continue
+    const ordered = group
+      .map((c, i) => ({ c, i }))
+      .sort((a, b) => a.c.category - b.c.category || a.i - b.i)
+      .map((x) => x.c.output)
+    combined.set(label, ordered.join(", "))
+  }
+  return combined
+}
+
+/**
+ * Resolve {Node Label} references in text by replacing them with actual node outputs.
+ * Skips reserved template variables used by applyTemplate().
+ * Iterates until stable to handle nested refs (e.g. {List} → {Animal1} → "dog").
+ */
+export function resolveNodeRefs(
+  text: string,
+  labelToOutput: ReadonlyMap<string, string>,
+): string {
+  const MAX_PASSES = 10
+  let result = text
+  for (let i = 0; i < MAX_PASSES; i++) {
+    const next = result.replace(NODE_REF_PATTERN, (match, raw: string) => {
+      const { name, fallback } = parseNodeRef(raw)
+      if (RESERVED_TEMPLATE_VARS.has(name)) return match
+      // Node-name vars are case-insensitive: try the literal key first (keeps
+      // original-cased maps like condition-variables working), then the
+      // lowercase-canonical key (node-ref maps are canonical-keyed).
+      const output = labelToOutput.get(name) ?? labelToOutput.get(canonicalVarName(name))
+      if (output !== undefined) return output            // connected, non-empty output → its value
+      if (fallback !== null) return fallback             // absent/empty + fallback → default ("" for {name || })
+      return match                                       // absent + no || → literal {name}
+    })
+    if (next === result) break
+    result = next
+  }
+  return result
+}

package/src/node-runtime-keys.ts

@@ -0,0 +1,117 @@
+/**
+ * Field names on a node's `data` that hold runtime / result / transient execution
+ * state (job ids, progress, generated outputs, fan-out bookkeeping). These are NEVER
+ * part of a node's reusable configuration.
+ *
+ * Single source of truth, consumed by:
+ *  - the workflow store's undo logic (execution-only updates skip undo capture, so job
+ *    polling does not pollute undo history or flip `isDirty`)
+ *  - the node-preset extractor (presets must never capture runtime state)
+ *  - the backend defensive strip on preset writes
+ *
+ * When adding a new runtime/result field to a node's data, add its key here.
+ */
+export const EXECUTION_DATA_KEYS: ReadonlySet<string> = new Set([
+  "executionStatus",
+  "currentJobId",
+  "currentJobProgress",
+  "errorMessage",
+  "isStreaming",
+  "generatedImageUrl",
+  "generatedVideoUrl",
+  "generatedAudioUrl",
+  "generatedText",
+  "generatedScript",
+  "generatedItems",
+  "generatedResults",
+  "activeResultIndex",
+  "sourceImageUrl",
+  "__listTotal",
+  "__listCompleted",
+  "__listResults",
+  // List fan-out window flag (abandon-guard exemption). Set/cleared by
+  // executeNodeForList — purely execution-related, never user-edited.
+  "__listRunning",
+  // Selector node dual-channel outputs (picked + rest). Server-side execution
+  // output, not user-edited config.
+  "pickedResults",
+  "restResults",
+  "__pickedResults",
+  "__restResults",
+  "__pickedTotal",
+  "__restTotal",
+  "generatedJson",
+  "subWorkflowProgress",
+  "outputResults",
+  "shots",
+  "result",
+  "processedResult",
+  "activeRoutes",
+  "routeOutputs",
+  "_upstreamRefresh",
+  "zoom",
+  // Character LoRA training status fields — written every 8s while training.
+  "loraReplicateVersion",
+  "loraTriggerWord",
+  "loraTrainingStatus",
+  // Collect (fan-in) execution snapshot.
+  "lastInputs",
+  "lastMeta",
+  "__upstreamCount",
+])
+
+/**
+ * The PURE RUN-STATE subset of EXECUTION_DATA_KEYS: per-tick values (status
+ * flips, job ids, progress counters, fan-out bookkeeping) that must NEITHER
+ * mark the workflow dirty NOR be persisted in the save payload. Everything
+ * else in EXECUTION_DATA_KEYS is a RESULT the user expects to survive reload
+ * (generated URLs/results, errorMessage, LoRA outputs, collect snapshots).
+ *
+ * Why this split exists: writing these keys used to set `isDirty`, so job
+ * polling phantom-dirtied passive tabs → spurious autosaves → false
+ * "changed in another tab" banners → the remote-ahead latch froze autosave
+ * (the "not saved for a long time" report). Consumed by the workflow
+ * store's dirty decision and the save-payload sanitizer below.
+ *
+ * Invariant (guarded by node-runtime-keys.test.ts): subset of
+ * EXECUTION_DATA_KEYS — anything transient is also undo-exempt.
+ */
+export const TRANSIENT_RUNTIME_KEYS: ReadonlySet<string> = new Set([
+  "executionStatus",
+  "currentJobId",
+  "currentJobProgress",
+  "isStreaming",
+  "subWorkflowProgress",
+  "__listTotal",
+  "__listCompleted",
+  "__listRunning",
+  "_upstreamRefresh",
+  "__upstreamCount",
+])
+
+/**
+ * Pure save-payload sanitizer: returns new node objects with the transient
+ * run-state keys removed from `data`. Nodes without transient keys (or
+ * without `data`) are returned by reference — cheap for the common case.
+ */
+export function stripTransientRuntimeData<
+  T extends { data?: Record<string, unknown> | undefined },
+>(nodes: readonly T[]): T[] {
+  return nodes.map((node) => {
+    const data = node.data
+    if (!data) return node
+    let hasTransient = false
+    for (const key of TRANSIENT_RUNTIME_KEYS) {
+      if (key in data) {
+        hasTransient = true
+        break
+      }
+    }
+    if (!hasTransient) return node
+    const cleaned: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(data)) {
+      if (!TRANSIENT_RUNTIME_KEYS.has(key)) cleaned[key] = value
+    }
+    return { ...node, data: cleaned }
+  })
+}

package/src/object-aspect-defaults.ts

@@ -0,0 +1,72 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Object aspect-ratio defaults
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Objects are isolated subjects — product-showcase framing. Unlike characters
+// (which have per-asset-type framing differences — head shots 3:4, full-body
+// 9:16), objects use 1:1 square framing for every asset type by default. This
+// matches the natural framing of the Object Studio's asset-card grid (square
+// tiles) and avoids cropping the subject regardless of which variant axis
+// (angles/materials/variations/motion) is being generated.
+//
+// Resolution precedence (low → high):
+//   1. Per-asset-type default (this table — all 1:1 currently)
+//   2. Object node's `defaultAssetAspectRatio` (user override, Phase E)
+//   3. Explicit `aspectRatio` on the API request (caller wins)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const OBJECT_ASPECT_OPTIONS = ["1:1", "3:4", "16:9", "9:16", "4:3"] as const
+export type ObjectAspectRatio = (typeof OBJECT_ASPECT_OPTIONS)[number]
+
+/**
+ * The asset categories with distinct natural framing. For objects, all bucket
+ * defaults are currently `"1:1"`, but the per-asset-type table is kept (vs a
+ * single flat constant) so future tuning (e.g., wider framing for motion clips
+ * with camera-orbit moves) can be added without touching the resolver.
+ */
+export type ObjectAssetTypeForAspect = "angles" | "materials" | "variations" | "motion" | "custom"
+
+export const OBJECT_ASPECT_DEFAULTS: Record<ObjectAssetTypeForAspect, ObjectAspectRatio> = {
+  angles: "1:1",
+  materials: "1:1",
+  variations: "1:1",
+  // Motion clips are 1:1 because objects rotate in place. Switch to "16:9" if
+  // future motion variants pan through a scene (e.g., drone-orbit with horizon).
+  motion: "1:1",
+  custom: "1:1",
+}
+
+export function isObjectAspectRatio(s: string): s is ObjectAspectRatio {
+  return (OBJECT_ASPECT_OPTIONS as readonly string[]).includes(s)
+}
+
+export interface ResolveObjectAspectOptions {
+  /** Explicit `aspectRatio` on the request body — highest precedence. */
+  readonly explicit?: string | null
+  /**
+   * The object node's `defaultAssetAspectRatio` — set per-canvas-node via the
+   * 5-pill toggle on the object node (Phase E). Flows through the API as
+   * `objectNodeAspectRatio`.
+   */
+  readonly nodeOverride?: string | null
+  /** What's being generated. Drives the default when nothing else is set. */
+  readonly assetType: ObjectAssetTypeForAspect
+}
+
+/**
+ * Resolve the final aspect ratio for an object generation request.
+ *
+ * Precedence: explicit > node override > per-asset-type default. The two
+ * "soft" inputs are tolerated as raw strings and only honored when they parse
+ * to a value in OBJECT_ASPECT_OPTIONS — anything else falls through to the
+ * next layer (so a stale enum value doesn't poison the generation).
+ */
+export function resolveObjectAspectRatio(opts: ResolveObjectAspectOptions): ObjectAspectRatio {
+  if (opts.explicit && isObjectAspectRatio(opts.explicit)) {
+    return opts.explicit
+  }
+  if (opts.nodeOverride && isObjectAspectRatio(opts.nodeOverride)) {
+    return opts.nodeOverride
+  }
+  return OBJECT_ASPECT_DEFAULTS[opts.assetType]
+}

package/src/object-picker-types.ts

@@ -0,0 +1,22 @@
+import { PARAMETER_NODE_TYPES } from "./parameter-node-value.js"
+
+/**
+ * The 5 parameter-picker node types that can wire INTO the Object Studio's
+ * `type` input handle as upstream identity providers (Material, Animal,
+ * Vehicle, Weapon, Furniture). The resolver in
+ * `backend/src/services/workflow-engine/input-resolver.ts` (and its frontend
+ * mirror) reads this set to discriminate wired pickers from arbitrary source
+ * nodes when composing the seedPromptHint.
+ *
+ * Defensive filter: if `PARAMETER_NODE_TYPES` doesn't yet contain `"furniture"`
+ * (i.e., the Furniture prereq PR hasn't been deployed in this environment),
+ * furniture silently drops from the set. The wired-picker resolver then
+ * skips furniture pickers without error rather than firing a wrong prompt
+ * fragment. Production deploy order is enforced as: Prereq PR (#2601, merged)
+ * → Object Studio PRs; this defensive code is a safety net.
+ */
+export const OBJECT_PICKER_NODE_TYPES: ReadonlySet<string> = new Set(
+  ["material", "animal", "vehicle", "weapon", "furniture"].filter((t) =>
+    PARAMETER_NODE_TYPES.has(t),
+  ),
+)