@nodaro/shared 1.4.1

package/src/settled-with-limit.ts

@@ -0,0 +1,42 @@
+/**
+ * Like Promise.allSettled but limits how many tasks run concurrently.
+ * Uses a worker-pool pattern so a new task starts as soon as a slot frees up.
+ * When `cancelledRef` is provided and becomes truthy, remaining un-started
+ * tasks are skipped (already-running tasks continue to completion/rejection).
+ */
+export async function settledWithLimit<T>(
+  tasks: (() => Promise<T>)[],
+  limit: number,
+  cancelledRef?: { cancelled: boolean },
+): Promise<PromiseSettledResult<T>[]> {
+  const results: PromiseSettledResult<T>[] = new Array(tasks.length)
+  let nextIndex = 0
+
+  const cancelledError = new Error("Execution cancelled")
+
+  async function worker(): Promise<void> {
+    while (nextIndex < tasks.length) {
+      if (cancelledRef?.cancelled) break
+      const idx = nextIndex++
+      try {
+        const value = await tasks[idx]()
+        results[idx] = { status: "fulfilled", value }
+      } catch (reason) {
+        results[idx] = { status: "rejected", reason }
+      }
+    }
+  }
+
+  const workers = Array.from(
+    { length: Math.min(limit, tasks.length) },
+    () => worker(),
+  )
+  await Promise.all(workers)
+
+  // Fill any un-started slots (from cancellation) with a shared rejection
+  for (let i = 0; i < results.length; i++) {
+    if (!results[i]) results[i] = { status: "rejected", reason: cancelledError }
+  }
+
+  return results
+}

package/src/shot-element.ts

@@ -0,0 +1,43 @@
+import type { SupportedFontName } from "./supported-fonts.js"
+
+export interface ShotTextElement {
+  readonly id: string
+  readonly type: "text"
+  readonly text: string
+  readonly fontFamily?: SupportedFontName
+  readonly fontSize: number
+  readonly fontWeight?: 300 | 400 | 700 | 900
+  readonly color?: string
+  readonly x: number
+  readonly y: number
+  readonly letterSpacing?: number
+  readonly opacity?: number
+  readonly dir?: "rtl" | "ltr"
+}
+export interface ShotShapeElement {
+  readonly id: string
+  readonly type: "shape"
+  readonly shape: "rectangle" | "circle" | "line"
+  readonly fill?: string
+  readonly stroke?: string
+  readonly strokeWidth?: number
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+  readonly cornerRadius?: number
+  readonly opacity?: number
+}
+export interface ShotImageElement {
+  readonly id: string
+  readonly type: "image"
+  readonly src: string
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+  readonly fit?: "contain" | "cover"
+  readonly radius?: number
+  readonly opacity?: number
+}
+export type ShotElement = ShotTextElement | ShotShapeElement | ShotImageElement

package/src/social-media-specs.ts

@@ -0,0 +1,121 @@
+export type SocialMediaPlatform = "instagram" | "tiktok" | "x" | "youtube" | "facebook" | "linkedin" | "telegram"
+
+export type SocialMediaContentType =
+  | "feed-square" | "feed-portrait" | "feed-landscape" | "story-reel"  // Instagram
+  | "video"                                                             // TikTok
+  | "image-landscape" | "image-square" | "x-video"                     // X
+  | "short"                                                             // YouTube
+  | "fb-feed-portrait" | "reel"                                        // Facebook
+  | "li-image-landscape" | "li-image-square" | "li-video"              // LinkedIn
+
+export interface SocialMediaSpec {
+  readonly platform: SocialMediaPlatform
+  readonly contentType: SocialMediaContentType
+  readonly label: string
+  readonly width: number
+  readonly height: number
+  readonly maxDurationSeconds: number | null  // null = image only (no duration limit)
+  readonly textLimit: number
+  readonly isVideo: boolean
+}
+
+export const PLATFORM_SPECS: Record<string, SocialMediaSpec> = {
+  "instagram:feed-square": {
+    platform: "instagram", contentType: "feed-square", label: "Feed Square",
+    width: 1080, height: 1080, maxDurationSeconds: 60, textLimit: 2200, isVideo: true,
+  },
+  "instagram:feed-portrait": {
+    platform: "instagram", contentType: "feed-portrait", label: "Feed Portrait",
+    width: 1080, height: 1350, maxDurationSeconds: 60, textLimit: 2200, isVideo: true,
+  },
+  "instagram:feed-landscape": {
+    platform: "instagram", contentType: "feed-landscape", label: "Feed Landscape",
+    width: 1080, height: 566, maxDurationSeconds: 60, textLimit: 2200, isVideo: true,
+  },
+  "instagram:story-reel": {
+    platform: "instagram", contentType: "story-reel", label: "Story / Reel",
+    width: 1080, height: 1920, maxDurationSeconds: 180, textLimit: 2200, isVideo: true,
+  },
+  "tiktok:video": {
+    platform: "tiktok", contentType: "video", label: "Video",
+    width: 1080, height: 1920, maxDurationSeconds: 600, textLimit: 4000, isVideo: true,
+  },
+  "x:image-landscape": {
+    platform: "x", contentType: "image-landscape", label: "Image Landscape",
+    width: 1200, height: 675, maxDurationSeconds: null, textLimit: 280, isVideo: false,
+  },
+  "x:image-square": {
+    platform: "x", contentType: "image-square", label: "Image Square",
+    width: 1080, height: 1080, maxDurationSeconds: null, textLimit: 280, isVideo: false,
+  },
+  "x:x-video": {
+    platform: "x", contentType: "x-video", label: "Video",
+    width: 1920, height: 1080, maxDurationSeconds: 140, textLimit: 280, isVideo: true,
+  },
+  "youtube:short": {
+    platform: "youtube", contentType: "short", label: "Short",
+    width: 1080, height: 1920, maxDurationSeconds: 180, textLimit: 5000, isVideo: true,
+  },
+  "facebook:fb-feed-portrait": {
+    platform: "facebook", contentType: "fb-feed-portrait", label: "Feed Portrait",
+    width: 1080, height: 1350, maxDurationSeconds: null, textLimit: 63206, isVideo: false,
+  },
+  "facebook:reel": {
+    platform: "facebook", contentType: "reel", label: "Reel",
+    width: 1080, height: 1920, maxDurationSeconds: 90, textLimit: 63206, isVideo: true,
+  },
+  "linkedin:li-image-landscape": {
+    platform: "linkedin", contentType: "li-image-landscape", label: "Image Landscape",
+    width: 1200, height: 627, maxDurationSeconds: null, textLimit: 3000, isVideo: false,
+  },
+  "linkedin:li-image-square": {
+    platform: "linkedin", contentType: "li-image-square", label: "Image Square",
+    width: 1080, height: 1080, maxDurationSeconds: null, textLimit: 3000, isVideo: false,
+  },
+  "linkedin:li-video": {
+    platform: "linkedin", contentType: "li-video", label: "Video",
+    width: 1920, height: 1080, maxDurationSeconds: 600, textLimit: 3000, isVideo: true,
+  },
+}
+
+export const CONTENT_TYPES_BY_PLATFORM: Record<SocialMediaPlatform, ReadonlyArray<{ key: string; label: string }>> = {
+  instagram: [
+    { key: "instagram:feed-square", label: "Feed Square (1080×1080)" },
+    { key: "instagram:feed-portrait", label: "Feed Portrait (1080×1350)" },
+    { key: "instagram:feed-landscape", label: "Feed Landscape (1080×566)" },
+    { key: "instagram:story-reel", label: "Story / Reel (1080×1920)" },
+  ],
+  tiktok: [
+    { key: "tiktok:video", label: "Video (1080×1920)" },
+  ],
+  x: [
+    { key: "x:image-landscape", label: "Image Landscape (1200×675)" },
+    { key: "x:image-square", label: "Image Square (1080×1080)" },
+    { key: "x:x-video", label: "Video (1920×1080)" },
+  ],
+  youtube: [
+    { key: "youtube:short", label: "Short (1080×1920)" },
+  ],
+  facebook: [
+    { key: "facebook:fb-feed-portrait", label: "Feed Portrait (1080×1350)" },
+    { key: "facebook:reel", label: "Reel (1080×1920)" },
+  ],
+  linkedin: [
+    { key: "linkedin:li-image-landscape", label: "Image Landscape (1200×627)" },
+    { key: "linkedin:li-image-square", label: "Image Square (1080×1080)" },
+    { key: "linkedin:li-video", label: "Video (1920×1080)" },
+  ],
+  telegram: [
+    { key: "telegram:message", label: "Message (text)" },
+  ],
+}
+
+export const PLATFORM_LABELS: Record<SocialMediaPlatform, string> = {
+  instagram: "Instagram",
+  tiktok: "TikTok",
+  x: "X (Twitter)",
+  youtube: "YouTube",
+  facebook: "Facebook",
+  linkedin: "LinkedIn",
+  telegram: "Telegram",
+}

package/src/social-post.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared constants for social post nodes.
+ *
+ * Used by both the frontend DAG executor and backend orchestrator so input
+ * routing + API validation agree on which node types are social posts and
+ * on Instagram's carousel item limits.
+ */
+
+/** Node types that publish to a social platform via POST /v1/social/publish. */
+export const SOCIAL_POST_NODE_TYPES = new Set([
+  "instagram-post",
+  "tiktok-post",
+  "youtube-upload",
+  "linkedin-post",
+  "x-post",
+  "facebook-post",
+  "telegram-post",
+])
+
+/** Instagram carousel limits per Meta Graph API.
+ *  Meta's documented limit is 10 items; sending >10 fails at container
+ *  creation with "(#100) too little or too many attachments". */
+export const INSTAGRAM_CAROUSEL_MIN_ITEMS = 2
+export const INSTAGRAM_CAROUSEL_MAX_ITEMS = 10

package/src/sub-workflow-validation.ts

@@ -0,0 +1,78 @@
+export interface SubWorkflowPort {
+  readonly id: string
+  readonly name: string
+  readonly mediaType: "text" | "image" | "video" | "audio" | "any"
+}
+
+interface BoundaryNode {
+  readonly id: string
+  readonly type: string
+  readonly data: { readonly routeId?: string; readonly ports?: readonly SubWorkflowPort[] }
+}
+
+export type ValidationError =
+  | { code: "missing_output_for_route"; routeId: string; inputNodeId: string }
+  | { code: "missing_input_for_route";  routeId: string; outputNodeId: string }
+  | { code: "route_has_no_output_ports"; routeId: string; outputNodeId: string }
+  | { code: "duplicate_route_id";       routeId: string; nodeIds: readonly string[] }
+
+export type ValidationResult =
+  | { ok: true }
+  | { ok: false; errors: readonly ValidationError[] }
+
+export function validateSubWorkflowRoutes(
+  nodes: readonly BoundaryNode[],
+): ValidationResult {
+  const inputs  = nodes.filter((n) => n.type === "sub-workflow-input")
+  const outputs = nodes.filter((n) => n.type === "sub-workflow-output")
+
+  if (inputs.length === 0 && outputs.length === 0) return { ok: true }
+
+  const errors: ValidationError[] = []
+
+  // 1. Duplicate routeIds within input or output lists
+  const groupByRoute = (list: readonly BoundaryNode[]) => {
+    const map = new Map<string, BoundaryNode[]>()
+    for (const n of list) {
+      const r = n.data.routeId
+      if (!r) continue
+      const bucket = map.get(r) ?? []
+      bucket.push(n)
+      map.set(r, bucket)
+    }
+    return map
+  }
+  for (const [routeId, group] of groupByRoute(inputs)) {
+    if (group.length > 1) errors.push({ code: "duplicate_route_id", routeId, nodeIds: group.map((g) => g.id) })
+  }
+  for (const [routeId, group] of groupByRoute(outputs)) {
+    if (group.length > 1) errors.push({ code: "duplicate_route_id", routeId, nodeIds: group.map((g) => g.id) })
+  }
+
+  // 2. Every input routeId must have a matching output
+  const outputByRoute = new Map(outputs.map((o) => [o.data.routeId, o] as const))
+  for (const inputNode of inputs) {
+    const routeId = inputNode.data.routeId
+    if (!routeId) continue
+    const matchingOutput = outputByRoute.get(routeId)
+    if (!matchingOutput) {
+      errors.push({ code: "missing_output_for_route", routeId, inputNodeId: inputNode.id })
+      continue
+    }
+    if (!matchingOutput.data.ports || matchingOutput.data.ports.length === 0) {
+      errors.push({ code: "route_has_no_output_ports", routeId, outputNodeId: matchingOutput.id })
+    }
+  }
+
+  // 3. Every output routeId must have a matching input
+  const inputByRoute = new Map(inputs.map((i) => [i.data.routeId, i] as const))
+  for (const outputNode of outputs) {
+    const routeId = outputNode.data.routeId
+    if (!routeId) continue
+    if (!inputByRoute.has(routeId)) {
+      errors.push({ code: "missing_input_for_route", routeId, outputNodeId: outputNode.id })
+    }
+  }
+
+  return errors.length === 0 ? { ok: true } : { ok: false, errors }
+}

package/src/supported-fonts.ts

@@ -0,0 +1,40 @@
+/**
+ * Canonical list of font display names supported by the Remotion renderer.
+ *
+ * Single source of truth shared by:
+ *  - the backend Zod schemas (`z.enum(SUPPORTED_FONT_NAMES)`), which CANNOT
+ *    import `@nodaro/remotion` (its font-registry pulls the render runtime +
+ *    `@remotion/google-fonts` side-effects into a validation path), and
+ *  - `packages/remotion/src/lib/font-registry.ts`, which loads each face and
+ *    is kept in lock-step with this tuple by a compile-time `satisfies` guard.
+ *
+ * Order/spelling MUST match the keys of the `fonts` object in font-registry.ts.
+ */
+export const SUPPORTED_FONT_NAMES = [
+  "Inter",
+  "Roboto",
+  "Open Sans",
+  "Montserrat",
+  "Poppins",
+  "Raleway",
+  "Nunito",
+  "Lato",
+  "Playfair Display",
+  "Merriweather",
+  "Lora",
+  "EB Garamond",
+  "Bebas Neue",
+  "Oswald",
+  "Anton",
+  "Dancing Script",
+  "Pacifico",
+  "Caveat",
+  "Roboto Mono",
+  "Fira Code",
+  "Rubik",
+  "Heebo",
+  "Cairo",
+  "Tajawal",
+] as const
+
+export type SupportedFontName = (typeof SUPPORTED_FONT_NAMES)[number]

package/src/surround.ts

@@ -0,0 +1,113 @@
+/**
+ * Surround continuation — shared single source of truth.
+ *
+ * The Location 360° "look-around" builds each ring view (45°, 90°, …) as an
+ * image-to-image continuation of the previous view. The platform forces
+ * geometric continuity by handing the model a half-done frame: one edge holds
+ * the previous view's carried pixels, the rest is flat gray, and the model is
+ * asked to paint the gray region.
+ *
+ * This module owns the bits that are pure and reused across the route Zod
+ * schema, the SDK input type, and the worker: the direction enum, the carried
+ * fraction defaults, and the fill prompt. The geometry math + sharp compositing
+ * + color harmonization live backend-side (they need `sharp`).
+ */
+
+/**
+ * The carry/paint axis for a continuation.
+ *
+ * PAN (horizontal — half-carry continuation):
+ * - `right` — turning right: the new frame's LEFT edge continues the previous
+ *   view's RIGHT edge, so the carried band sits on the LEFT, painted on the RIGHT.
+ * - `left` — turning left: the new frame's RIGHT edge continues the previous
+ *   view's LEFT edge, so the carried band sits on the RIGHT, painted on the LEFT.
+ *   (Mirror of `right`. Lets studio chain BOTH ways from a keyframe, capping
+ *   chain depth so quality doesn't compound down a long one-way chain.)
+ *
+ * TILT (vertical — thin-strip, subject-driven re-render):
+ * - `up` — tilting straight up: render the open SKY overhead. A thin strip of
+ *   the establishing shot's TOP edge is carried into the new frame's BOTTOM for
+ *   a soft horizon transition; the rest is painted as sky (NOT a mirrored
+ *   landscape).
+ * - `down` — tilting straight down: render the GROUND below. A thin strip of the
+ *   BOTTOM edge is carried into the new frame's TOP.
+ */
+export const SURROUND_DIRECTIONS = ["right", "left", "up", "down"] as const
+export type SurroundDirection = (typeof SURROUND_DIRECTIONS)[number]
+
+/** Half the frame is carried for a horizontal pan (matches studio's composite). */
+export const DEFAULT_CARRIED_FRACTION = 0.5
+/**
+ * Tilts carry only a thin horizon strip. Carrying half of a horizontal frame is
+ * exactly what makes the model echo/mirror the landscape vertically instead of
+ * rendering what's actually overhead/underfoot — so tilts keep the carry small
+ * and let the tilt prompt drive the subject.
+ */
+export const TILT_CARRIED_FRACTION = 0.12
+
+/** True for the vertical tilt directions (up/down), false for the pans. */
+export function isTiltDirection(direction: SurroundDirection): boolean {
+  return direction === "up" || direction === "down"
+}
+
+/** The carried fraction the platform uses when the caller doesn't pin one. */
+export function defaultCarriedFraction(direction: SurroundDirection): number {
+  return isTiltDirection(direction) ? TILT_CARRIED_FRACTION : DEFAULT_CARRIED_FRACTION
+}
+
+/** Which edge of the NEW frame holds the carried pixels vs the painted region. */
+const EDGE: Record<SurroundDirection, { carried: string; painted: string }> = {
+  right: { carried: "left", painted: "right" },
+  left: { carried: "right", painted: "left" },
+  up: { carried: "bottom", painted: "top" },
+  down: { carried: "top", painted: "bottom" },
+}
+
+/** What a tilt must actually render (NOT a continuation of the landscape). */
+const TILT_SUBJECT: Record<"up" | "down", { word: string; subject: string; where: string }> = {
+  up: {
+    word: "up",
+    subject: "the open sky directly overhead — sky, clouds, or (for an interior) the canopy or ceiling",
+    where: "overhead",
+  },
+  down: {
+    word: "down",
+    subject: "the ground directly below — terrain, floor, or water surface",
+    where: "below",
+  },
+}
+
+/**
+ * Build the fill prompt the model receives alongside the half-carry composite.
+ *
+ * `userPrompt` (an optional scene hint from the caller) is woven in front. PAN
+ * directions get the seamless-continuation prompt (with the anti-golden-hour
+ * negative that fights the documented warm-regrade drift). TILT directions get a
+ * subject-forcing prompt — render the sky / ground overhead / below, explicitly
+ * NOT a mirrored landscape — which is what stops the vertical echo.
+ */
+export function buildSurroundFillPrompt(direction: SurroundDirection, userPrompt?: string): string {
+  const scene = userPrompt && userPrompt.trim() ? `${userPrompt.trim()}. ` : ""
+  const { carried, painted } = EDGE[direction]
+
+  if (direction === "up" || direction === "down") {
+    const t = TILT_SUBJECT[direction]
+    return (
+      `${scene}` +
+      `This is a camera tilted straight ${t.word} from the same scene. The ${carried} strip holds real, finished pixels from the edge of the horizon view; the ${painted} region is flat gray and MUST be painted as ${t.subject}. ` +
+      `Render what is genuinely ${t.where} — do NOT repeat, mirror, or continue the landscape, and do NOT draw a horizon line or distant scenery in the painted region. ` +
+      `CRITICAL: keep the ${carried} strip unchanged and match the scene's EXACT lighting, time of day, white balance, and color grade — the same light as the ${carried} strip; no golden hour, no sunset, no warm relight, no cinematic regrade. ` +
+      `Blend smoothly into the ${carried} strip with no visible seam. No people, no text, no labels, no watermarks.`
+    )
+  }
+
+  // pan (right / left)
+  return (
+    `${scene}` +
+    `This is a partial frame: the ${carried} portion contains real, finished pixels and the ${painted} portion is flat gray that MUST be painted in. ` +
+    `Paint ONLY the ${painted} gray region as a natural, seamless continuation of the ${carried} portion — same scene, same perspective, continuing the horizon, geometry, and content across the boundary with no break. ` +
+    `Keep the ${carried} portion completely unchanged. ` +
+    `CRITICAL: do NOT change the lighting, exposure, white balance, or time of day. Match the ${carried} portion's EXACT light, color temperature, and contrast across the whole frame — if it is flat overcast daylight, keep flat overcast daylight. No golden hour, no sunset, no warm relight, no cinematic regrade. ` +
+    `The seam between the ${carried} and ${painted} portions must be invisible. No people, no text, no labels, no watermarks.`
+  )
+}

package/src/switchx-pricing.ts

@@ -0,0 +1,33 @@
+// Beeble SwitchX — Relight & Switch video node. Non-monetary tier bucketing
+// and credit-identifier helpers. Beeble bills per 30-frame block with no
+// per-job meter returned, so we reserve a block tier (the smallest tier that
+// covers the clip's frame count) and commit it verbatim — tiers are 30-frame
+// multiples, so a clip snaps to the exact number of blocks Beeble bills
+// (ceil(frames/30)); there is no tier over-charge.
+//
+// The $-per-block provider rate and the credits-per-block formula derived
+// from it live in `backend/src/lib/pricing/switchx-cost.ts` (core, not ee/).
+// They were moved out of this package (published Apache-2.0 on npm — an
+// irrevocable grant) per the 2026-07-06 public-flip IP audit, S5.
+export const SWITCHX_FRAME_TIERS = [30, 60, 90, 120, 150, 180, 210, 240] as const
+
+/** Beeble's metering granularity: frames per billed block. */
+export const SWITCHX_BLOCK_FRAMES = 30
+
+export function pickSwitchXFrameTier(frames?: number): number {
+  if (frames === undefined || !Number.isFinite(frames) || frames <= 0) return 240
+  for (const t of SWITCHX_FRAME_TIERS) if (frames <= t) return t
+  return 240
+}
+
+function readMaxResolution(body: Record<string, unknown>): 720 | 1080 {
+  const r = Number(body.maxResolution ?? body.max_resolution)
+  return r === 720 ? 720 : 1080 // default 1080
+}
+
+// Frames are stashed on the raw body by the route's ffprobe preHandler.
+export function resolveSwitchXCreditId(body: Record<string, unknown>): string {
+  const frames = Number(body.__probedFrameCount)
+  const tier = pickSwitchXFrameTier(Number.isFinite(frames) ? frames : undefined)
+  return `beeble-switchx:${tier}f:${readMaxResolution(body)}p`
+}

package/src/text-separators.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared separator presets for the Combine Text and Split Text nodes.
+ * Single source of truth for both the frontend DAG executor and backend orchestrator.
+ */
+
+export const SEPARATOR_PRESETS = [
+  "newline",
+  "double-newline",
+  "comma",
+  "space",
+  "stars",
+  "custom",
+] as const
+
+export type SeparatorPreset = (typeof SEPARATOR_PRESETS)[number]
+
+const SPLIT_MAP: Record<string, string> = {
+  newline: "\n",
+  "double-newline": "\n\n",
+  comma: ",",
+  space: " ",
+  stars: "***",
+}
+
+const COMBINE_MAP: Record<string, string> = {
+  ...SPLIT_MAP,
+  comma: ", ",
+}
+
+/** Human-readable label for the node badge. */
+export const SEPARATOR_DISPLAY: Record<string, string> = {
+  newline: "\\n",
+  "double-newline": "\\n\\n",
+  comma: ",",
+  space: "space",
+  stars: "***",
+}
+
+export interface ResolveSeparatorOptions {
+  /** Use combine-text spacing — e.g. ", " for comma instead of "," */
+  combineSpacing?: boolean
+}
+
+/**
+ * Resolve a separator value to its actual string.
+ * - Enum preset → mapped value (e.g. "newline" → "\n")
+ * - "custom" → customSeparator field
+ * - Anything else → literal string (back-compat with legacy values like "===NEXT===")
+ */
+export function resolveSeparator(
+  raw: string | undefined,
+  customSeparator: string | undefined,
+  opts?: ResolveSeparatorOptions,
+): string {
+  const r = raw || "newline"
+  if (r === "custom") return customSeparator ?? ""
+  const map = opts?.combineSpacing ? COMBINE_MAP : SPLIT_MAP
+  return map[r] ?? r
+}

package/src/to-connected-references.ts

@@ -0,0 +1,77 @@
+import type { ConnectedReference } from "./types.js"
+import { characterMentionSlug } from "./character-mention-slug.js"
+import { locationMentionSlug } from "./location-mention-slug.js"
+
+/**
+ * A bound entity (a wired Character or Location) ready to convert into a
+ * `ConnectedReference`. The minimal identity an app captures when a user binds
+ * an entity — the SLUG (and thus the resolver match) is DERIVED from `name`
+ * here, so callers can't drift from Nodaro's mention resolver. Apps own their
+ * own binding UX (chips, pickers); this is just the contract mapping.
+ */
+export interface EntityReferenceInput {
+  /** The entity row id. */
+  readonly id: string
+  readonly kind: "character" | "location" | "creature"
+  /** Display name — the slug is derived from this. */
+  readonly name: string
+  /** Resolved thumbnail/source URL; null/undefined → "" (placeholder-safe). */
+  readonly url?: string | null
+  /** Variant slug (e.g. "smile", "rain"); undefined = canonical/default. */
+  readonly variant?: string
+  /** Optional free-text descriptor (creature bindings: species/appearance) —
+   *  folded into the auto-generated directive subject by the prompt builder. */
+  readonly description?: string | null
+}
+
+/**
+ * Map ONE bound entity to its `ConnectedReference`. character → `wired-character`
+ * (slug via `characterMentionSlug`), location → `wired-location` (slug via
+ * `locationMentionSlug`), creature → `wired-creature` (no mention-slug machinery
+ * — like `wired-object`, a bound creature AUTO-ATTACHES and gets a canonical-style
+ * creature/animal-subject directive with zero typing; `{image:N:creature}` tokens
+ * also resolve against it). Canonical-description fields are null here (a binding
+ * captures only name+variant; the picker/full-row path supplies descriptions).
+ */
+export function toConnectedReference(entity: EntityReferenceInput): ConnectedReference {
+  if (entity.kind === "character") {
+    return {
+      id: entity.id,
+      defaultName: entity.name,
+      source: "wired-character",
+      url: entity.url ?? "",
+      characterSlug: characterMentionSlug(entity.name),
+      variantSlug: entity.variant,
+      characterCanonicalDescription: null,
+      variantDescription: null,
+      variantDisplayName: entity.variant ?? "canonical",
+    }
+  }
+  if (entity.kind === "creature") {
+    return {
+      id: entity.id,
+      defaultName: entity.name,
+      source: "wired-creature",
+      url: entity.url ?? "",
+      ...(entity.description ? { description: entity.description } : {}),
+    }
+  }
+  return {
+    id: entity.id,
+    defaultName: entity.name,
+    source: "wired-location",
+    url: entity.url ?? "",
+    locationSlug: locationMentionSlug(entity.name),
+    locationCanonicalDescription: null,
+    locationVariantBucket: undefined,
+    locationVariantSlug: entity.variant,
+    locationVariantDisplayName: entity.variant ?? "canonical",
+  }
+}
+
+/** Batch form — `entities.map(toConnectedReference)`. */
+export function toConnectedReferences(
+  entities: readonly EntityReferenceInput[],
+): ConnectedReference[] {
+  return entities.map(toConnectedReference)
+}