@nodaro/shared 1.4.1

package/src/entity-approval-types.ts

@@ -0,0 +1,31 @@
+import { z } from "zod"
+
+/**
+ * Body for POST /v1/pipelines/:id/entities/:entity_id/reject.
+ * Approve takes no body (optional `edits` future-deferred).
+ */
+export const EntityRejectInputSchema = z.object({
+  feedback: z.string().min(1).max(2000),
+})
+export type EntityRejectInput = z.infer<typeof EntityRejectInputSchema>
+
+export const ENTITY_STATUSES = [
+  "pending",
+  "generating",
+  "awaiting_approval",
+  "approved",
+  "rejected",
+  "failed",
+  // Phase 3 (granular-pipeline-control) — Stage 2 Character Wizard.
+  // `pending_description` is the initial state for character entities in
+  // manual/guided mode pipelines; the engine waits for the user's Step A
+  // approval before generating the portrait. `skipped` is a terminal state
+  // for entities the user explicitly opts out of (no generation, excluded
+  // from stage-advance gating). Migration: 154_phase_1d3_character_wizard.sql.
+  "pending_description",
+  "skipped",
+] as const
+export type EntityStatus = (typeof ENTITY_STATUSES)[number]
+
+export const ENTITY_TYPES = ["character", "object", "location", "scene"] as const
+export type EntityType = (typeof ENTITY_TYPES)[number]

package/src/entity-aspect-defaults.ts

@@ -0,0 +1,82 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Entity studio aspect-ratio defaults (location / creature / object)
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Character has its own table (`character-aspect-defaults.ts`); this is the
+// equivalent for the other three entity studios. It is the SINGLE source for:
+//   1. the generation request aspect sent to the provider (backend generate-*
+//      routes), and
+//   2. the studio card's *fallback* container ratio (frontend), shown until the
+//      real media aspect is probed.
+// Keeping both in one place means the framing a user sees can't drift from the
+// framing that was generated.
+//
+// Note: the frontend additionally sizes each card to the REAL decoded media
+// aspect (so a provider that returns a slightly different ratio still displays
+// uncropped). These per-type values are the deterministic placeholder + the
+// value requested at generation time.
+
+export type EntityStudioKind = "location" | "creature" | "object"
+
+/** Provider "W:H" ratio strings (same vocabulary as the character table). */
+export const ENTITY_ASPECT_DEFAULTS: Record<
+  EntityStudioKind,
+  Record<string, string>
+> = {
+  // Locations are environments → landscape framing everywhere.
+  location: {
+    timeOfDay: "16:9",
+    weather: "16:9",
+    seasons: "16:9",
+    angles: "16:9",
+    lighting: "16:9",
+    atmosphereMotions: "16:9",
+  },
+  // Creatures (animals): turnaround angles & condition variations read square;
+  // full-body poses read taller (portrait); motion clips are vertical.
+  creature: {
+    angles: "1:1",
+    poses: "3:4",
+    variations: "1:1",
+    motion: "9:16",
+  },
+  // Objects/props: product turnarounds, materials, and condition variants are
+  // square; motion clips are vertical.
+  object: {
+    angles: "1:1",
+    materials: "1:1",
+    variations: "1:1",
+    motion: "9:16",
+  },
+}
+
+const RATIO_RE = /^\d+:\d+$/
+
+/**
+ * Resolve the provider aspect string for an entity asset generation.
+ * Precedence: explicit > node override > per-asset-type default > "1:1".
+ * The two "soft" inputs are honored only when they parse as a "W:H" ratio, so a
+ * stale value falls through instead of poisoning the request.
+ */
+export function resolveEntityAspect(opts: {
+  entity: EntityStudioKind
+  assetType: string
+  explicit?: string | null
+  nodeOverride?: string | null
+}): string {
+  if (opts.explicit && RATIO_RE.test(opts.explicit)) return opts.explicit
+  if (opts.nodeOverride && RATIO_RE.test(opts.nodeOverride)) return opts.nodeOverride
+  return ENTITY_ASPECT_DEFAULTS[opts.entity]?.[opts.assetType] ?? "1:1"
+}
+
+/**
+ * "9:16" → 0.5625 (width / height) for a CSS `aspect-ratio` fallback value.
+ * Anything that isn't a "W:H" ratio (or has a zero term) → 1 (square).
+ */
+export function aspectRatioToNumber(ratio: string): number {
+  const m = /^(\d+):(\d+)$/.exec(ratio.trim())
+  if (!m) return 1
+  const w = Number(m[1])
+  const h = Number(m[2])
+  return w > 0 && h > 0 ? w / h : 1
+}

package/src/entity-asset-types.ts

@@ -0,0 +1,296 @@
+/**
+ * Structural entity vocabulary — asset-type/attach-column tuples, reference
+ * photo kinds, styles, labels. Product data visible in the UI and required
+ * by SDK consumers; deliberately part of the public Apache surface.
+ * (The prompt-BUILDING craft lives in @nodaro/prompts.)
+ */
+
+/**
+ * Prompt builders for entity nodes (character, face, object, location).
+ *
+ * Single source of truth shared between:
+ * - Route handlers: `backend/src/routes/generate-{character,face,object,location}.ts`
+ * - Backend orchestrator: `backend/src/services/workflow-engine/payload-builder.ts`
+ *
+ * The route handlers call these when no client-supplied prompt is provided.
+ * The orchestrator calls these to build the same prompt that a single-node
+ * HTTP call would produce.
+ */
+
+/**
+ * Allowed style values for character / face / object / location entities.
+ * Single source of truth: derive Zod enums + TS types from this tuple so the
+ * Zod schema, the TS union, the SDK input types, and the CLI flag validator
+ * never drift apart.
+ */
+export const CHARACTER_STYLES = ["realistic", "anime", "3d-pixar", "illustration"] as const
+export type EntityStyle = (typeof CHARACTER_STYLES)[number]
+
+/**
+ * Character asset-type enum — the kinds of variant a user can generate off a
+ * character's anchor portrait. Mirrors the literal accepted by
+ * `POST /v1/generate-character-asset` (`backend/src/routes/generate-character-asset.ts`)
+ * and consumed by the MCP `generate_character` verb (kind="asset") in
+ * `backend/src/lib/mcp/tools/verbs-clo.ts`.
+ *
+ * `angles` is the legacy single-surface alias for `headAngles` — both produce
+ * head-and-shoulders portrait framing. `bodyAngles` is the full-body variant.
+ * `lighting` is the bucket key (the DB column is `lighting_variations`).
+ */
+export const CHARACTER_ASSET_TYPES = [
+  "expressions",
+  "poses",
+  "lighting",
+  "angles",
+  "headAngles",
+  "bodyAngles",
+  "custom",
+] as const
+export type CharacterAssetType = (typeof CHARACTER_ASSET_TYPES)[number]
+
+/**
+ * DB columns the character-asset worker may auto-attach to. Required when
+ * `assetType === "custom"` (the worker can't infer the bucket from the asset
+ * type); for canonical asset types the column is derived automatically.
+ *
+ * Mirrors the literal accepted by the route's `attachToColumn` Zod field.
+ */
+export const CHARACTER_ATTACH_COLUMNS = [
+  "expressions",
+  "poses",
+  "angles",
+  "body_angles",
+  "lighting_variations",
+  // Reference-sheet buckets (migration 200). `sheets` holds composited
+  // reference sheets; `detail_closeups` holds macro close-up panels;
+  // `outfit_variations` holds wardrobe panels (character-only — objects and
+  // locations don't have an outfit dimension).
+  "sheets",
+  "detail_closeups",
+  "outfit_variations",
+] as const
+export type CharacterAttachColumn = (typeof CHARACTER_ATTACH_COLUMNS)[number]
+
+/**
+ * Canonical variant presets per character asset type — the SINGLE source of
+ * truth shared by the `generate-character-asset` route (Zod validation rejects a
+ * non-`custom` variant outside this list) and any client building the asset-set
+ * UI (e.g. the Studio character creator), so the two can't drift. `custom` has no
+ * preset list (free-form variant).
+ */
+export const CHARACTER_ASSET_VARIANTS = {
+  expressions: [
+    "neutral",
+    "smile",
+    "angry",
+    "surprised",
+    "sad",
+    "talking",
+    "laughing",
+    "disgusted",
+    "fearful",
+    "smirk",
+    "crying",
+  ],
+  poses: [
+    "standing",
+    "walking",
+    "sitting",
+    "running",
+    "crouching",
+    "pointing",
+    "fighting stance",
+    "jumping",
+    "turning",
+  ],
+  lighting: ["daylight", "night", "dramatic"],
+  angles: ["front", "3/4 left", "left profile", "right profile", "3/4 right", "back", "above", "below"],
+  headAngles: ["front", "3/4 left", "left profile", "right profile", "3/4 right", "above", "below", "back"],
+  bodyAngles: ["front", "3/4 left", "left profile", "right profile", "3/4 right", "back", "above", "below"],
+} as const satisfies Partial<Record<CharacterAssetType, readonly string[]>>
+
+/**
+ * Location asset-type enum — the kinds of variant a user can generate off a
+ * location's anchor establishing shot. Mirrors the literal accepted by
+ * `POST /v1/generate-location-asset` (`backend/src/routes/generate-location-asset.ts`)
+ * and consumed by the MCP `generate_location` verb (kind="asset").
+ *
+ * `lighting` is the bucket key (the DB column is `lighting`). `custom` is the
+ * free-form bucket where callers must supply `attachToColumn` explicitly since
+ * the worker can't infer the destination from the asset type.
+ */
+export const LOCATION_ASSET_TYPES = [
+  "timeOfDay",
+  "weather",
+  "seasons",
+  "angles",
+  "lighting",
+  "custom",
+] as const
+export type LocationAssetType = (typeof LOCATION_ASSET_TYPES)[number]
+
+/**
+ * DB columns the location-asset worker may auto-attach to. Required when
+ * `assetType === "custom"` (the worker can't infer the bucket from the asset
+ * type); for canonical asset types the column is derived automatically.
+ *
+ * Mirrors the literal accepted by the route's `attachToColumn` Zod field.
+ */
+export const LOCATION_ATTACH_COLUMNS = [
+  "time_of_day",
+  "weather",
+  "seasons",
+  "angles",
+  "lighting",
+  "atmosphere_motions",
+  // Reference-sheet buckets (migration 200). Locations get `sheets` +
+  // `detail_closeups` (no `outfit_variations` — that's character-only).
+  "sheets",
+  "detail_closeups",
+] as const
+export type LocationAttachColumn = (typeof LOCATION_ATTACH_COLUMNS)[number]
+
+/**
+ * Canonical variant presets per LOCATION asset type — hoisted from
+ * `backend/src/routes/generate-location-asset.ts` (single source of truth shared
+ * with the reference-sheet catalog; Plan 04 switches the route to import this).
+ */
+export const LOCATION_ASSET_VARIANTS = {
+  timeOfDay: ["dawn", "morning", "noon", "afternoon", "golden hour", "dusk", "blue hour", "night", "midnight"],
+  weather: ["clear", "cloudy", "light rain", "heavy rain", "storm", "snow", "blizzard", "fog", "mist"],
+  seasons: ["spring", "summer", "autumn", "winter"],
+  angles: ["wide", "medium", "closeup", "aerial", "low-angle", "eye-level", "bird's-eye", "dutch tilt"],
+  lighting: ["soft natural", "harsh sunlight", "golden", "blue hour", "neon", "candlelit", "cinematic", "dramatic chiaroscuro"],
+} as const satisfies Partial<Record<LocationAssetType, readonly string[]>>
+
+/**
+ * Reference-photo kind discriminator — the mood-board roles a user can attach
+ * to a location row. Single source of truth shared between:
+ *  - Backend route Zod enum (`backend/src/routes/locations.ts`)
+ *  - Backend export/import bundle schema (`backend/src/lib/workflow-assets.ts`)
+ *  - Frontend Studio picker (`reference-photos-section.tsx`)
+ *  - Frontend `LocationNodeData.referencePhotos.kind` union (`frontend/src/types/nodes.ts`)
+ *
+ * `other` is the free-form bucket; the rest are user-curated mood-board roles.
+ */
+export const LOCATION_REFERENCE_PHOTO_KINDS = [
+  "wide",
+  "interior",
+  "exterior",
+  "detail",
+  "moodBoard",
+  "other",
+] as const
+export type LocationReferencePhotoKind = (typeof LOCATION_REFERENCE_PHOTO_KINDS)[number]
+
+/**
+ * Human-friendly label for each photo kind, used in prompt subject lines
+ * (`Image N (Old Library — wide-angle reference)`) so the model knows the
+ * role of each reference photo at generate time. Kept as a separate map
+ * from `LOCATION_REFERENCE_PHOTO_KINDS` so labels can be edited without
+ * disturbing the kind enum (which is the schema-of-record).
+ */
+export const LOCATION_REFERENCE_PHOTO_KIND_LABELS: Record<LocationReferencePhotoKind, string> = {
+  wide: "wide-angle reference",
+  interior: "interior reference",
+  exterior: "exterior reference",
+  detail: "detail reference",
+  moodBoard: "mood-board reference",
+  other: "reference",
+}
+
+export function locationReferencePhotoKindLabel(kind: LocationReferencePhotoKind): string {
+  return LOCATION_REFERENCE_PHOTO_KIND_LABELS[kind]
+}
+
+/**
+ * Reference-photo kinds captured in the Character Studio identity foundation —
+ * the SINGLE schema-of-record for the 7 kinds. Previously duplicated across the
+ * `generate-character` + `characters` route Zod enums, `character-reference-set.ts`
+ * (backend ranking), and `frontend/src/lib/reference-photo-routing.ts` (UI
+ * filtering). All of those now derive from this const (build a Zod enum via
+ * `z.enum(CHARACTER_REFERENCE_PHOTO_KINDS)` at the backend edge — this package
+ * stays zod-free). Also the shape of the DB `characters.reference_photos[].kind`.
+ *
+ * `other` is the free-form bucket; the rest are curated identity-foundation roles
+ * (frontFace + the four rotation views + a full-body shot).
+ */
+export const CHARACTER_REFERENCE_PHOTO_KINDS = [
+  "frontFace",
+  "sideLeft",
+  "sideRight",
+  "threeQuarterLeft",
+  "threeQuarterRight",
+  "frontBody",
+  "other",
+] as const
+export type CharacterReferencePhotoKind = (typeof CHARACTER_REFERENCE_PHOTO_KINDS)[number]
+
+/** A single character reference photo: a URL plus its identity-foundation role. */
+export interface CharacterReferencePhoto {
+  url: string
+  kind: CharacterReferencePhotoKind
+}
+
+/**
+ * Reserved name the Character Studio auto-assigns when a user clicks Generate
+ * before naming the character. Treated as "no name" by prompt builders so the
+ * literal string "Untitled character" never leaks into a generation prompt.
+ * Frontend stays in sync via `@nodaro/shared`.
+ */
+export const PLACEHOLDER_CHARACTER_NAME = "Untitled character"
+
+
+export const OBJECT_ASSET_TYPES = [
+  "angles",
+  "materials",
+  "variations",
+  "motion",
+  "custom",
+] as const
+export type ObjectAssetType = (typeof OBJECT_ASSET_TYPES)[number]
+
+/**
+ * DB columns the object-asset worker may auto-attach to. Aligns with the
+ * `append_object_asset` RPC's CASE/WHEN whitelist (migration 147). Required
+ * when `assetType === "custom"`; for canonical asset types the column is
+ * derived automatically.
+ */
+export const OBJECT_ATTACH_COLUMNS = [
+  "angles",
+  "materials",
+  "variations",
+  "motion_clips",
+  // Reference-sheet buckets (migration 200). Objects get `sheets` +
+  // `detail_closeups` (no `outfit_variations` — that's character-only).
+  "sheets",
+  "detail_closeups",
+] as const
+export type ObjectAttachColumn = (typeof OBJECT_ATTACH_COLUMNS)[number]
+
+/** Worker-attachable JSONB asset columns on `creatures` (mirrors OBJECT_ATTACH_COLUMNS;
+ *  `materials`→`poses`). The append_creature_asset RPC (migration 206) whitelists these. */
+export const CREATURE_ATTACH_COLUMNS = [
+  "angles", "poses", "variations", "motion_clips", "sheets", "detail_closeups",
+] as const
+export type CreatureAttachColumn = (typeof CREATURE_ATTACH_COLUMNS)[number]
+
+/**
+ * Canonical variant presets per OBJECT asset type — hoisted from
+ * `backend/src/routes/generate-object-asset.ts` so the route, the reference-sheet
+ * catalog, and any client share one list and can't drift. (Plan 04 switches the
+ * route to import this.) `custom`/`motion` have no preset list.
+ */
+export const OBJECT_ASSET_VARIANTS = {
+  angles: ["front", "side", "top", "back", "three-quarter"],
+  materials: ["wood", "metal", "glass", "plastic", "fabric", "stone"],
+  variations: ["clean", "weathered", "damaged", "ornate", "minimal"],
+} as const satisfies Partial<Record<ObjectAssetType, readonly string[]>>
+
+/**
+ * Input shape for buildObjectMotionPrompt.
+ *
+ * Mirrors LocationMotionPromptInput's role. `canonicalDescription` is preferred
+ * (LLM-authored from the approved main image) but the helper falls back to
+ * category+name if not yet set, and to a generic placeholder if both are absent.
+ */

package/src/entity-image-handle.ts

@@ -0,0 +1,36 @@
+/**
+ * Entity node types that expose a plain `image` source handle (emitting the
+ * portrait URL) in addition to their identity `*Ref` handle. When a wire leaves
+ * the `image` handle, the entity is treated as a plain image PRODUCER
+ * (substituted to "upload-image") so it reaches image inputs and lists exactly
+ * like generate-image / upload-image, while the `*Ref` handle stays identity.
+ *
+ * SINGLE SOURCE OF TRUTH — consumed by:
+ *   - frontend connection validation (drop validator, drag-glow, popover),
+ *   - frontend run assemblers (execute-node, video-prompt-assembly),
+ *   - frontend config-panel reference preview builders,
+ *   - backend payload-builder identity-injection guards.
+ * Add future per-handle output-type remaps HERE so every surface inherits them.
+ */
+export const ENTITY_IMAGE_HANDLE_TYPES: ReadonlySet<string> = new Set([
+  "character",
+  "location",
+  "object",
+  "creature",
+])
+
+/**
+ * The effective output TYPE a given source handle emits. Returns the raw node
+ * type for every `(type, handle)` pair EXCEPT an entity `image` handle, which
+ * resolves to `"upload-image"` (a plain image producer). Pure — safe for both
+ * frontend and backend.
+ */
+export function resolveEffectiveSourceType(
+  rawSourceType: string | undefined | null,
+  sourceHandleId: string | undefined | null,
+): string {
+  if (sourceHandleId === "image" && ENTITY_IMAGE_HANDLE_TYPES.has(rawSourceType ?? "")) {
+    return "upload-image"
+  }
+  return rawSourceType ?? ""
+}

package/src/extra-refs.ts

@@ -0,0 +1,139 @@
+/**
+ * Shared helper for materializing user-attached "extra reference images" into
+ * `ConnectedReference` entries.
+ *
+ * Used by both:
+ *   - frontend `execute-node.ts` (single-node Run + DAG executor path) and
+ *   - backend `payload-builder.ts` (orchestrator path)
+ * so single-node frontend runs and orchestrator-driven runs produce identical
+ * `referenceImageUrls` + assembled prompts. See `frontend/src/types/nodes.ts`
+ * for the `ExtraRef` interface and `packages/shared/src/prompt-builder.ts`
+ * for the directive emission contract (`buildExtraRefDirectives`).
+ *
+ * Field mapping:
+ *   - manual upload  → source = "manual",          description = ref.description
+ *   - char-variant   → source = "wired-character", characterSlug + variantSlug
+ *                      preserved, description = ref.description (used as the
+ *                      bullet's per-image description in directives — overrides
+ *                      `variantDescription` from the character node).
+ *
+ * Usage-mode resolution: per-ref `usageMode` override → upstream character
+ * node's `defaultUsageMode` → global "identical". The resolved mode is stored
+ * in `defaultUsageMode` on the resulting `ConnectedReference` so the existing
+ * directive emission (`buildExtraRefDirectives`, `buildCanonicalFallback`,
+ * `resolveCharacterMentions`) reads it uniformly.
+ *
+ * Character-node lookup: takes a `lookupCharacterNode` callback so each caller
+ * can provide its own (frontend uses Zustand store + edges, backend uses
+ * `PayloadBuildContext.nodes` + edges). The callback should return the
+ * character node whose name slugifies to `characterSlug`, or undefined if
+ * no such character is wired upstream.
+ */
+
+import { DEFAULT_USAGE_MODE, type UsageMode } from "./character-usage-mode.js"
+import type { ConnectedReference } from "./types.js"
+
+/** Shape of an extra-ref entry on node data. Matches `ExtraRef` in the
+ *  frontend `types/nodes.ts`; duplicated here as a structural interface so
+ *  the backend (which sees node data as `Record<string, unknown>`) can pass
+ *  raw JSON through `expandExtraRefsToConnectedReferences`. */
+export interface ExtraRefInput {
+  readonly url?: string
+  readonly description?: string
+  readonly characterSlug?: string
+  readonly variantSlug?: string
+  readonly variantDisplayName?: string
+  readonly usageMode?: UsageMode
+}
+
+/** Hook that returns extra metadata for the upstream Character node backing
+ *  a given character slug, if any. Used to resolve `defaultUsageMode` and
+ *  `characterCanonicalDescription`. */
+export interface ExtraRefCharacterContext {
+  readonly defaultUsageMode?: UsageMode
+  readonly canonicalDescription?: string | null
+  readonly displayName?: string
+  /** Character node's hybrid `defaultRole` — stamped onto the extra's
+   *  `ConnectedReference.defaultRole` (only when the extra carries no per-ref
+   *  `usageMode` override, which would take precedence). */
+  readonly defaultRole?: string
+  /** Character node's `identityLock`, mapped to the per-reference lock shape
+   *  (`characterLockToRefLock`) — stamped onto the extra's
+   *  `ConnectedReference.identityLock`. */
+  readonly identityLock?: { enabled: boolean; text?: string }
+}
+
+/**
+ * Convert a list of `ExtraRef` entries into `ConnectedReference` entries that
+ * append to the consumer node's existing `connectedReferences` list. The
+ * resulting entries carry `isExtraRef: true` so the shared prompt-builder
+ * routes them through the dedicated extra-ref directive emission (which
+ * handles "Image N is the same subject as Image M, …" pairing).
+ *
+ * `lookupCharacterContext(slug)` is called for character-sourced extras to
+ * resolve the upstream character node's `defaultUsageMode` and canonical
+ * description. Returning `undefined` is safe — the helper falls back to the
+ * per-ref `usageMode` override or the global default.
+ */
+export function expandExtraRefsToConnectedReferences(
+  extras: ReadonlyArray<ExtraRefInput> | undefined,
+  lookupCharacterContext?: (slug: string) => ExtraRefCharacterContext | undefined,
+): ConnectedReference[] {
+  if (!extras || extras.length === 0) return []
+  const out: ConnectedReference[] = []
+  for (let i = 0; i < extras.length; i++) {
+    const r = extras[i]
+    if (!r || !r.url) continue
+    const description = (r.description ?? "").trim()
+    if (r.characterSlug) {
+      // Character-sourced extra. Resolution chain for the effective mode:
+      // per-ref override (r.usageMode) → upstream character node's default →
+      // global identical. The character node lookup also gives us the
+      // canonical description used by "identical"/"face-pose" mode displays.
+      const ctx = lookupCharacterContext?.(r.characterSlug)
+      const effectiveMode: UsageMode = r.usageMode ?? ctx?.defaultUsageMode ?? DEFAULT_USAGE_MODE
+      const displayName = ctx?.displayName || r.characterSlug
+      out.push({
+        id: `extra_${i}`,
+        defaultName: r.variantDisplayName
+          ? `${displayName} / ${r.variantDisplayName}`
+          : displayName,
+        source: "wired-character",
+        description,
+        url: r.url,
+        characterSlug: r.characterSlug,
+        variantSlug: r.variantSlug,
+        characterCanonicalDescription: ctx?.canonicalDescription ?? null,
+        variantDescription: description.length > 0 ? description : null,
+        variantDisplayName: r.variantDisplayName,
+        defaultUsageMode: effectiveMode,
+        // Node-default role (Character Node Role+Lock): stamped ONLY when the
+        // extra carries no per-ref `usageMode` override — the override wins
+        // (it's already folded into `defaultUsageMode` above, and
+        // `resolveDefaultRole` would otherwise let the role beat it).
+        defaultRole: r.usageMode ? undefined : ctx?.defaultRole,
+        // Node's mapped identity-lock (`characterLockToRefLock`) — orthogonal
+        // to the role; the hybrid renderers emit its line via
+        // `buildIdentityLockLine`.
+        identityLock: ctx?.identityLock,
+        isExtraRef: true,
+      })
+    } else {
+      // Manual upload extra. `description` is what the user typed in the
+      // per-row textarea; usage mode override applies if set (drives the
+      // directive's lock language even for manual refs — covers the "use as
+      // style/face only" case for an uploaded photo).
+      const effectiveMode: UsageMode | undefined = r.usageMode
+      out.push({
+        id: `extra_${i}`,
+        defaultName: `Image ${i + 1}`,
+        source: "manual",
+        description,
+        url: r.url,
+        defaultUsageMode: effectiveMode,
+        isExtraRef: true,
+      })
+    }
+  }
+  return out
+}