@nodaro/shared 1.4.2

package/src/character-aspect-defaults.ts

@@ -0,0 +1,102 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Character aspect-ratio defaults
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Characters are vertical subjects — the historical 16:9 default produced wide,
+// crop-unfriendly portraits. The per-asset-type table below picks the ratio
+// that fits each asset's natural framing:
+//
+//   - Portrait / canonical head shot           → 3:4
+//   - Expressions (head-and-shoulders)         → 1:1
+//   - Poses (full-body)                        → 9:16
+//   - Head angles                              → 3:4
+//   - Body angles (full-body)                  → 9:16
+//   - Lighting variations (full-body context)  → 3:4
+//   - Motions (vertical clip, full-body i2v)   → 9:16
+//
+// Resolution precedence (low → high):
+//   1. Per-asset-type default (this table)
+//   2. Character node's `defaultAssetAspectRatio` (user override on the canvas
+//      node — flows in as `characterNodeAspectRatio` in the request body)
+//   3. Explicit `aspectRatio` on the API request (caller wins)
+//
+// The character node's `defaultAssetAspectRatio` toggle (1:1 / 3:4 / 16:9 /
+// 9:16) drives BOTH the canvas thumbnail crop AND this override slot.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const CHARACTER_ASPECT_OPTIONS = ["1:1", "3:4", "16:9", "9:16"] as const
+export type CharacterAspectRatio = (typeof CHARACTER_ASPECT_OPTIONS)[number]
+
+/**
+ * The asset categories with distinct natural framing. Aliases:
+ *   - `angles` is the legacy single-surface key (now head-and-shoulders by
+ *     default). Use `headAngles` for clarity in new code.
+ *   - `bodyAngles` is the new full-body column added in migration 118.
+ */
+export type CharacterAssetTypeForAspect =
+  | "portrait"
+  | "expressions"
+  | "poses"
+  | "angles"
+  | "headAngles"
+  | "bodyAngles"
+  | "lighting"
+  | "motions"
+
+export const CHARACTER_ASPECT_DEFAULTS: Record<
+  CharacterAssetTypeForAspect,
+  CharacterAspectRatio
+> = {
+  portrait: "3:4",
+  // Legacy `angles` was head angles — keep its default aligned with `headAngles`.
+  angles: "3:4",
+  headAngles: "3:4",
+  // Full-body framings:
+  poses: "9:16",
+  bodyAngles: "9:16",
+  motions: "9:16",
+  // Expressions are head-and-shoulders — square framing matches the existing
+  // expression card grid and avoids cutting off forehead/chin.
+  expressions: "1:1",
+  // Lighting variations are framed like portraits (3:4) — they're full-body in
+  // the prompt but the user usually wants to see the lighting on the face.
+  lighting: "3:4",
+}
+
+export function isCharacterAspectRatio(s: string): s is CharacterAspectRatio {
+  return (CHARACTER_ASPECT_OPTIONS as readonly string[]).includes(s)
+}
+
+export interface ResolveCharacterAspectOptions {
+  /** Explicit `aspectRatio` on the request body — highest precedence. */
+  readonly explicit?: string | null
+  /**
+   * The character node's `defaultAssetAspectRatio` — set per-canvas-node via
+   * the 4-pill toggle on the character node. Flows through the API as
+   * `characterNodeAspectRatio`.
+   */
+  readonly nodeOverride?: string | null
+  /** What's being generated. Drives the default when nothing else is set. */
+  readonly assetType: CharacterAssetTypeForAspect
+}
+
+/**
+ * Resolve the final aspect ratio for a character 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 `CHARACTER_ASPECT_OPTIONS` — anything else falls
+ * through to the next layer (so a stale enum value doesn't poison the
+ * generation).
+ */
+export function resolveCharacterAspectRatio(
+  opts: ResolveCharacterAspectOptions,
+): CharacterAspectRatio {
+  if (opts.explicit && isCharacterAspectRatio(opts.explicit)) {
+    return opts.explicit
+  }
+  if (opts.nodeOverride && isCharacterAspectRatio(opts.nodeOverride)) {
+    return opts.nodeOverride
+  }
+  return CHARACTER_ASPECT_DEFAULTS[opts.assetType]
+}

package/src/character-facets.ts

@@ -0,0 +1,37 @@
+/**
+ * Facets of a source character/asset that can be selectively injected into a
+ * consumer character via the Character node's Assets handle (element/asset
+ * injection, P2). Single source of truth for the frontend facet chip options
+ * AND the backend facet-extraction instructions.
+ *
+ * `full` injects the whole source description verbatim (no LLM call needed).
+ * Every other facet is LLM-extracted on demand from the source's
+ * `canonicalDescription` via `POST /v1/character/extract-facet`.
+ */
+export interface CharacterFacet {
+  /** Stable id stored on the connection (`assetInjections[].facet`). */
+  readonly id: string
+  /** Human label shown in the facet chip. */
+  readonly label: string
+  /** What the extractor should pull from the source description. Phrased to
+   *  complete "Extract {instruction} …". Unused for `full`. */
+  readonly instruction: string
+}
+
+export const CHARACTER_FACETS: readonly CharacterFacet[] = [
+  { id: "full", label: "Full likeness", instruction: "the complete physical likeness and appearance" },
+  { id: "hair", label: "Hair", instruction: "ONLY the hair — style, length, colour, and texture" },
+  { id: "skin-tone", label: "Skin tone", instruction: "ONLY the skin tone / complexion" },
+  { id: "face", label: "Face", instruction: "ONLY the facial features — face shape, eyes, nose, mouth, eyebrows, and any distinguishing marks" },
+  { id: "style", label: "Style", instruction: "ONLY the overall visual style, aesthetic, and vibe — not specific garments" },
+  { id: "outfit", label: "Outfit", instruction: "ONLY the clothing, outfit, and wardrobe" },
+  { id: "personality", label: "Personality", instruction: "ONLY the personality, demeanour, and characteristic expression" },
+] as const
+
+export const DEFAULT_CHARACTER_FACET = "full"
+
+export const CHARACTER_FACET_IDS: ReadonlySet<string> = new Set(CHARACTER_FACETS.map((f) => f.id))
+
+export function getCharacterFacet(id: string): CharacterFacet | undefined {
+  return CHARACTER_FACETS.find((f) => f.id === id)
+}

package/src/character-mention-slug.ts

@@ -0,0 +1,166 @@
+import { isUsageMode, type UsageMode } from "./character-usage-mode.js"
+
+/**
+ * Slugify a name (character or variant) for use in @-mention tokens.
+ * Lowercase, strip non-alphanumeric, collapse runs of dashes.
+ */
+export function characterMentionSlug(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+}
+
+export interface CharacterMentionTokenInfo {
+  readonly token: string
+  readonly characterSlug: string
+  /**
+   * 1-based positional index assigned at insertion time by the autocomplete.
+   * Lets the user wire a literal-text mention (`@kira:1`) to a final-prompt
+   * identity directive (`Image 1 (person) — match exactly…`) so the order in
+   * the typed prompt matches the order in the assembled directive block.
+   */
+  readonly imageIndex: number
+  readonly variantSlug: string | null
+  /**
+   * Optional per-mention usage-mode override (e.g. `:face`, `:style`). When
+   * `null`, the assembled directive falls back to the source character node's
+   * `defaultUsageMode`, then to the global `"identical"` default. Always one
+   * of the entries in `USAGE_MODES` when non-null — the parser rejects any
+   * other 4-part token.
+   */
+  readonly usageMode: UsageMode | null
+  /**
+   * Additive per-mention identity-lock sentinel (Unified Reference Roles,
+   * Task 4 + F4). Tri-state: `true` (trailing `~lock`, force lock ON) |
+   * `false` (trailing `~nolock`, force lock OFF — suppresses a ref-level
+   * `identityLock.enabled = true`) | ABSENT/undefined (neither sentinel —
+   * inherit the ref/source default; byte-identical to the pre-Task-4 shape).
+   * Only ACTED UPON by the HYBRID resolvers; the LEGACY resolvers ignore it
+   * entirely, so both `~lock` and `~nolock` are inert on the legacy path.
+   */
+  readonly lock?: boolean
+  readonly offset: number
+}
+
+/**
+ * Parse a single `@<character>:<index>(:<variant>)?(:<usageMode>)?` token.
+ *
+ * Supported shapes (each segment after `:` may contain internal dashes, so
+ * `@young-kira:1:soft-smile` parses unambiguously as character + index +
+ * variant):
+ *
+ *  - `@kira:1`              → canonical, default mode
+ *  - `@kira:1:smile`        → variant smile, default mode
+ *  - `@kira:1:face`         → canonical, mode "face"  (mode is detected by
+ *                              checking the 3rd segment against `USAGE_MODES`)
+ *  - `@kira:1:smile:face`   → variant smile, mode "face"
+ *  - `@kira:1:smile:bogus`  → null (4-part rejected when last segment is not
+ *                              a valid usage mode — keeps the format strict)
+ *
+ * Format change: as of the index-in-slug update, the index segment is required.
+ * Bare `@kira` is not a mention; the autocomplete always inserts at least
+ * `@kira:N`.
+ *
+ * `knownCharacterSlugs` is no longer needed for parsing (the structure is
+ * unambiguous given the closed `USAGE_MODES` enum) — it remains accepted for
+ * API compatibility but ignored here. `findCharacterMentionTokens` still uses
+ * it to filter unknown characters.
+ */
+export function parseCharacterMentionToken(
+  text: string,
+  _knownCharacterSlugs?: readonly string[],
+): { characterSlug: string; imageIndex: number; variantSlug: string | null; usageMode: UsageMode | null; lock?: boolean } | null {
+  if (!text.startsWith("@")) return null
+  let rest = text.slice(1)
+  if (rest.length === 0 || !/^[a-z]/.test(rest)) return null
+
+  // Additive `~lock` / `~nolock` sentinels (Unified Reference Roles, Task 4 +
+  // F4). Strip a trailing `~nolock` (force lock OFF) or `~lock` (force lock ON)
+  // BEFORE splitting on ":" so the segment grammar below is byte-identical to
+  // pre-Task-4 (a `~` can never appear inside a segment — the shapes are
+  // `[a-z][a-z0-9-]*`). Check `~nolock` FIRST: `"x~nolock".endsWith("~lock")` is
+  // false (last 5 chars "olock"), but the explicit ordering keeps intent clear.
+  // A token with NEITHER sentinel is untouched here and gains NO `lock` key
+  // (byte-identical). The parsed tri-state `lock` (true/false/undefined) is only
+  // honored by the HYBRID resolvers — undefined inherits the ref default, true
+  // forces the lock on, false forces it off.
+  let lockField: { lock?: boolean } = {}
+  if (rest.endsWith("~nolock")) {
+    rest = rest.slice(0, -"~nolock".length)
+    lockField = { lock: false }
+  } else if (rest.endsWith("~lock")) {
+    rest = rest.slice(0, -"~lock".length)
+    lockField = { lock: true }
+  }
+
+  // Format: <character>:<index>(:<variant|mode>)?(:<mode>)?.
+  // Splitting on ":" requires 2–4 parts (no bare @character anymore).
+  const parts = rest.split(":")
+  if (parts.length < 2 || parts.length > 4) return null
+
+  const [characterSlug, indexStr, third, fourth] = parts
+  if (!/^[a-z][a-z0-9-]*$/.test(characterSlug)) return null
+  if (!/^\d+$/.test(indexStr)) return null
+  const imageIndex = parseInt(indexStr, 10)
+  if (!Number.isInteger(imageIndex) || imageIndex < 1) return null
+
+  // 2-part: kira:1 — canonical, default mode.
+  if (parts.length === 2) {
+    return { characterSlug, imageIndex, variantSlug: null, usageMode: null, ...lockField }
+  }
+
+  // 3-part: kira:1:X — X is either a usage-mode keyword or a variant slug.
+  // The closed `USAGE_MODES` enum + the variant-slug shape constraint
+  // (`[a-z][a-z0-9-]*`) makes this unambiguous. A keyword like "face" wins
+  // the mode interpretation; anything else is treated as a variant slug.
+  if (parts.length === 3) {
+    if (!/^[a-z][a-z0-9-]*$/.test(third)) return null
+    if (isUsageMode(third)) {
+      return { characterSlug, imageIndex, variantSlug: null, usageMode: third, ...lockField }
+    }
+    return { characterSlug, imageIndex, variantSlug: third, usageMode: null, ...lockField }
+  }
+
+  // 4-part: kira:1:smile:mode — variant + mode override. Both segments must
+  // satisfy their respective shape; an unknown mode kills the token entirely
+  // (callers fall back to literal text, matching unknown-character behavior).
+  if (parts.length === 4) {
+    if (!/^[a-z][a-z0-9-]*$/.test(third)) return null
+    if (!isUsageMode(fourth)) return null
+    return { characterSlug, imageIndex, variantSlug: third, usageMode: fourth, ...lockField }
+  }
+
+  return null
+}
+
+/** Find all @-mentions in a prompt that match a known character slug. */
+export function findCharacterMentionTokens(
+  prompt: string,
+  knownCharacterSlugs: readonly string[],
+): CharacterMentionTokenInfo[] {
+  const tokens: CharacterMentionTokenInfo[] = []
+  // `@<character>:<index>(:<variant|mode>)?(:<mode>)?` preceded by
+  // non-alphanumeric (or start of string) to prevent email-like matches.
+  // The `\d+` index segment is required — see `parseCharacterMentionToken`
+  // for the rationale. The two optional trailing `:<slug>` groups absorb
+  // either `:<variant>`, `:<mode>`, or `:<variant>:<mode>`; the parser
+  // disambiguates which segment is which based on `USAGE_MODES`. The optional
+  // trailing `(?:~(?:no)?lock)?` absorbs the additive Task-4/F4 identity-lock
+  // sentinel (`~lock` force-on OR `~nolock` force-off) INTO the token (so it is
+  // spliced out at resolve time); it is optional, so a lock-less token matches
+  // byte-identically to before. The `(?![a-z0-9-])` word boundary keeps
+  // `~locked` / `~nolockx` literal.
+  const regex = /(?:^|[^a-zA-Z0-9])(@[a-z][a-z0-9-]*:\d+(?::[a-z][a-z0-9-]*)?(?::[a-z][a-z0-9-]*)?(?:~(?:no)?lock(?![a-z0-9-]))?)/g
+  const knownSet = new Set(knownCharacterSlugs)
+  for (const match of prompt.matchAll(regex)) {
+    const token = match[1]
+    const offset = (match.index ?? 0) + (match[0].length - token.length)
+    const parsed = parseCharacterMentionToken(token)
+    if (parsed && knownSet.has(parsed.characterSlug)) {
+      tokens.push({ token, ...parsed, offset })
+    }
+  }
+  return tokens
+}

package/src/character-usage-mode.ts

@@ -0,0 +1,109 @@
+/**
+ * Character-mention usage modes — describe HOW the AI should consume a
+ * referenced character image. The mode shapes the per-image directive in the
+ * assembled prompt (see `usageModeDirective`) so the same character reference
+ * can act as a full likeness replacement, a face-only crop, a style donor,
+ * etc., without needing different upstream images.
+ *
+ * The mode source-of-truth lives in two places:
+ *
+ *   1. **Character node default** — `CharacterNodeData.defaultUsageMode`.
+ *      Set via the small dropdown in the character node's title row.
+ *      Propagates into every `ConnectedReference` derived from that node.
+ *
+ *   2. **Per-mention override** — optional 4th segment in the slug,
+ *      e.g. `@kira:1:smile:face` overrides the character's default for that
+ *      specific mention. Parsed by `parseCharacterMentionToken` in
+ *      `character-mention-slug.ts`.
+ *
+ * Mode resolution at prompt-build time (in `resolveCharacterMentions`):
+ *   token.usageMode  ??  ref.defaultUsageMode  ??  "identical"
+ */
+
+export const USAGE_MODES = [
+  "identical",
+  "face",
+  "face-pose",
+  "pose",
+  "emotion",
+  "style",
+  "name",
+  "none",
+] as const
+
+export type UsageMode = (typeof USAGE_MODES)[number]
+
+/** Default mode when neither the slug nor the character node specifies one. */
+export const DEFAULT_USAGE_MODE: UsageMode = "identical"
+
+/** Type guard — narrows an arbitrary string to `UsageMode` when valid. */
+export function isUsageMode(s: string): s is UsageMode {
+  return (USAGE_MODES as readonly string[]).includes(s)
+}
+
+/**
+ * Return the natural-language directive appended to a per-image bullet for the
+ * given mode. The text is intentionally explicit so the model knows exactly
+ * which aspects of the reference to take and which to derive from the rest of
+ * the prompt.
+ *
+ * `name` and `none` are minimal-intervention modes that return `null` — the
+ * caller emits NO trailing directive for them. `name` still includes the
+ * character name in the labeled subject (`Image A (shira)`); `none` suppresses
+ * the name as well (bare `Image A`) and excludes the character entirely from
+ * the top-level "Use these characters:" header when ALL of its mentions are
+ * `none`. Use these when the user wants the visual reference to speak for
+ * itself without textual bias.
+ *
+ * Calling sites: `resolveCharacterMentions` (shared/prompt-builder.ts) and the
+ * per-character canonical fallback (also in prompt-builder.ts), plus the video
+ * mention resolvers on frontend (execute-node.ts) and backend (payload-builder.ts)
+ * which mirror the same directive shape.
+ */
+export function usageModeDirective(mode: UsageMode): string | null {
+  switch (mode) {
+    case "identical":
+      return "The subject must remain exactly the same person — preserve 100% facial identity, bone structure, skin tone, proportions, and all unique features. Do not alter eyes, nose, mouth, or facial shape. Maintain natural skin texture, including pores and imperfections."
+    case "face":
+      return "Take ONLY the facial features and expression — preserve 100% facial identity, bone structure, skin tone, and all unique features. Do not alter eyes, nose, mouth, or facial shape. Maintain natural skin texture, including pores and imperfections. Adopt clothing, hair styling, and posture from the rest of the prompt."
+    case "face-pose":
+      return "Take the facial features AND body pose — preserve 100% facial identity, bone structure, skin tone, and all unique features. Do not alter eyes, nose, mouth, or facial shape. Maintain natural skin texture. Adopt clothing and styling from the rest of the prompt."
+    case "pose":
+      return "Take only the body pose and posture — do not copy facial identity, features, or skin. Adopt face, clothing, hair, and all other details from the rest of the prompt."
+    case "emotion":
+      return "Take only the emotional expression — preserve 100% facial identity and all unique features unchanged. Adopt face shape, clothing, body, and pose from the rest of the prompt; transfer only the emotional cue."
+    case "style":
+      return "Take only the visual style and tone (lighting, color grade, atmosphere). Do not copy the subject's identity, clothing, or pose."
+    case "name":
+    case "none":
+      return null
+  }
+}
+
+/** Human-readable label for the dropdown / badge UI. */
+export function usageModeLabel(mode: UsageMode): string {
+  switch (mode) {
+    case "identical": return "Identical"
+    case "face": return "Face only"
+    case "face-pose": return "Face + Pose"
+    case "pose": return "Pose only"
+    case "emotion": return "Emotion only"
+    case "style": return "Style only"
+    case "name": return "Name only"
+    case "none": return "None"
+  }
+}
+
+/**
+ * Whether the labeled subject for this mode should include the character name
+ * in parens (e.g. `Image A (shira)`) or stay bare (`Image A`). Only `none`
+ * returns false — every other mode (including `name`) keeps the name so the
+ * model can correlate the bullet with a named entity in the rest of the
+ * prompt. Used by `resolveCharacterMentions` to decide the subject form AND to
+ * filter the top-level "Use these characters:" header (a character whose
+ * mentions are ALL `none` is invisible textually — only the image is
+ * attached).
+ */
+export function usageModeIncludesName(mode: UsageMode): boolean {
+  return mode !== "none"
+}

package/src/character-variant-assets.ts

@@ -0,0 +1,121 @@
+/**
+ * Single source of truth for a character's `{name, url}[]` variant-asset buckets
+ * — the image/video variants that are expandable into connected references and
+ * therefore selectable in the reference picker AND `@`-mentionable in prompts.
+ *
+ * Historically the expansion list was hardcoded (6 copies across frontend
+ * `connected-references.ts` / `connected-refs-builder.ts` / `execute-node.ts` and
+ * backend `payload-builder.ts`), so when wardrobe (`outfitVariations`) and detail
+ * close-ups (`detailCloseups`) were added — same `{name,url}[]` shape, written by
+ * studio.nodaro.ai — they were silently dropped from the picker and `@` list.
+ * Drive every expansion site off this constant so a new bucket can't drift again.
+ *
+ * NOT included (different shapes, handled elsewhere):
+ *  - `sheets` (`ReferenceSheet[]` — composited multi-panel boards)
+ *  - `referenceVideosByVariant` (`Record<variant, url[]>` — per-emotion video refs)
+ */
+export const CHARACTER_VARIANT_ASSET_BUCKETS = [
+  "expressions",
+  "poses",
+  "motions",
+  "angles",
+  "bodyAngles",
+  "lightingVariations",
+  "outfitVariations",
+  "detailCloseups",
+] as const
+
+export type CharacterVariantAssetBucket = (typeof CHARACTER_VARIANT_ASSET_BUCKETS)[number]
+
+export interface CharacterVariantAssetItem {
+  readonly name: string
+  readonly url: string
+  readonly description?: string
+}
+
+/**
+ * Build the `{ bucket: items[] }` map for every variant-asset bucket from a
+ * character node's data. Missing / non-array buckets coerce to `[]`. One helper
+ * for all six expansion sites so the bucket set is defined exactly once.
+ */
+export function characterVariantAssetArrays(
+  data: Record<string, unknown> | null | undefined,
+): Record<CharacterVariantAssetBucket, readonly CharacterVariantAssetItem[]> {
+  const out = {} as Record<CharacterVariantAssetBucket, readonly CharacterVariantAssetItem[]>
+  for (const bucket of CHARACTER_VARIANT_ASSET_BUCKETS) {
+    const value = data?.[bucket]
+    out[bucket] = Array.isArray(value) ? (value as readonly CharacterVariantAssetItem[]) : []
+  }
+  return out
+}
+
+/**
+ * Map a character's composite reference `sheets` (ReferenceSheet[] — a different
+ * shape, with a composite board `url` + `type`/`skin`) into mentionable
+ * `{name,url}` items so they too can be picked / `@`-mentioned. Each sheet → one
+ * item named `"<type> <skin>"` (e.g. "turnaround studio"). Drops url-less sheets.
+ */
+export function characterSheetRefItems(sheets: unknown): CharacterVariantAssetItem[] {
+  if (!Array.isArray(sheets)) return []
+  return sheets.flatMap((s) => {
+    const sheet = s as { url?: unknown; type?: unknown; skin?: unknown }
+    if (!sheet || typeof sheet.url !== "string" || !sheet.url) return []
+    const type = typeof sheet.type === "string" && sheet.type ? sheet.type : "sheet"
+    const skin = typeof sheet.skin === "string" && sheet.skin ? ` ${sheet.skin}` : ""
+    return [{ name: `${type}${skin}`, url: sheet.url }]
+  })
+}
+
+/** Legacy `selected_asset_by_variant` keys that hold boards born before the
+ *  `boards` column existed (studio.nodaro.ai's reserved namespace). */
+const BOARD_SHIM_KEY = "studioBoard"
+const BOARD_SHIM_PREFIX = "studioBoard:"
+
+/**
+ * Resolve a character's named reference boards from BOTH the `boards` column AND
+ * the LEGACY `selected_asset_by_variant` shim (`studioBoard` / `studioBoard:<name>`)
+ * — mirroring studio.nodaro.ai's read (entity-boards.ts), which merges both since
+ * pre-column boards still live in the shim. Column wins on duplicate name; the
+ * unnamed legacy board is named "board". Drops url-less entries.
+ */
+export function characterBoardItems(
+  data: Record<string, unknown> | null | undefined,
+): CharacterVariantAssetItem[] {
+  const column: CharacterVariantAssetItem[] = Array.isArray(data?.boards)
+    ? (data!.boards as unknown[]).flatMap((b) => {
+        const board = b as { name?: unknown; url?: unknown }
+        if (!board || typeof board.url !== "string" || !board.url) return []
+        return [{ name: typeof board.name === "string" && board.name ? board.name : "board", url: board.url }]
+      })
+    : []
+
+  const map = (data?.selectedAssetByVariant ?? {}) as Record<string, unknown>
+  const shim: CharacterVariantAssetItem[] = []
+  const legacy = map[BOARD_SHIM_KEY]
+  if (typeof legacy === "string" && legacy) shim.push({ name: "board", url: legacy })
+  for (const [k, v] of Object.entries(map)) {
+    if (k.startsWith(BOARD_SHIM_PREFIX) && typeof v === "string" && v) {
+      shim.push({ name: k.slice(BOARD_SHIM_PREFIX.length) || "board", url: v })
+    }
+  }
+
+  const haveNames = new Set(column.map((b) => b.name.toLowerCase()))
+  return [...column, ...shim.filter((b) => !haveNames.has(b.name.toLowerCase()))]
+}
+
+/**
+ * The COMPLETE set of mentionable character asset arrays: the `{name,url}[]`
+ * variant buckets + derived `sheets` and `boards` buckets. This is what the
+ * connected-reference / `@`-mention expansion sites iterate, so every
+ * studio-produced asset (variants, composite sheets, AND boards — incl. legacy
+ * shim boards) surfaces in the reference picker and `@` list.
+ */
+export function characterMentionableAssetArrays(
+  data: Record<string, unknown> | null | undefined,
+): Record<string, readonly CharacterVariantAssetItem[]> {
+  return {
+    ...characterVariantAssetArrays(data),
+    sheets: characterSheetRefItems(data?.sheets),
+    boards: characterBoardItems(data),
+  }
+}