@nodaro/prompts 1.53.2 → 1.55.0

package/src/factory-presets/shelves.ts

@@ -0,0 +1,50 @@
+/**
+ * The shelves an image-preset picker files the catalog's groups under: Video,
+ * Marketing, Photos & products, Creative, Life, then the pro catalog's groups
+ * (Studio · Pro). A group no shelf names goes on "more", so a group added to
+ * the catalog still shows. One mapping for every picker that shelves the
+ * catalog (a client's preset window, a menu that lists the categories, the
+ * catalog's group summary `GET /v1/node-presets/factory/groups`).
+ */
+
+export type PresetShelf = "video" | "marketing" | "photos" | "creative" | "life" | "more" | "pro"
+
+/** The shelves in the order a picker shows them. */
+export const PRESET_SHELF_ORDER: readonly PresetShelf[] = ["video", "marketing", "photos", "creative", "life", "more", "pro"]
+
+/** The generate-image catalog's groups on the five named shelves, in the order they are shown. */
+const NAMED_SHELVES: ReadonlyArray<readonly [string, PresetShelf]> = [
+  ["YouTube", "video"],
+  ["Shorts · TikTok", "video"],
+  ["Social & Ads", "marketing"],
+  ["Business", "marketing"],
+  ["Business & Marketing", "marketing"],
+  ["Personal Photos", "photos"],
+  ["Products & Fashion", "photos"],
+  ["Home & Spaces", "photos"],
+  ["Text", "creative"],
+  ["Content & Creative", "creative"],
+  ["Layout", "creative"],
+  ["Life & Events", "life"],
+  ["Family & Events", "life"],
+]
+
+/** The pro catalog's groups (the canvas's and Studio's presets), on the Studio · Pro shelf. */
+const PRO_GROUPS: ReadonlySet<string> = new Set([
+  "Reference Sheet", "Cast & Consistency", "Edit by Name", "Face Privacy", "Photography & Cinematic", "Characters", "Product & Commerce",
+  "Branding & Logos", "Marketing & Social", "Print & Posters", "Illustration & Art Styles", "Handmade & Stop-Motion", "Film & Storyboard",
+  "Architecture & Interiors", "Icons, Game Assets & Textures", "Diagrams & Infographics", "Portrait Transformations", "Stylized Subject", "Edits",
+  "Realism & Authentic",
+])
+
+const SHELF_OF: ReadonlyMap<string, PresetShelf> = new Map(NAMED_SHELVES)
+
+/** The shelf a group goes on. */
+export function presetShelf(group: string): PresetShelf {
+  return SHELF_OF.get(group) ?? (PRO_GROUPS.has(group) ? "pro" : "more")
+}
+
+/** Where a group stands among the named shelves' groups (the design's order), or -1 for one no named shelf lists. */
+export function presetShelfRank(group: string): number {
+  return NAMED_SHELVES.findIndex(([name]) => name === group)
+}

package/src/picker-art/images.ts

@@ -23,6 +23,23 @@ export interface PickerImageOptions {
    * ask for it), and four URLs per option are dead weight to an agent (MCP).
    */
   readonly srcSet?: boolean
+  /**
+   * A deployment's own pictures, in place of the platform's. When set, an
+   * option is pictured by what this returns for it and by nothing else — no
+   * self-hosted photo, emoji or flag, no render — so an option it has nothing
+   * for has no picture, and no Person / Styling topic has one (a topic is not
+   * an option). `baseUrl` and `lookPreviews` are not read. The package names no
+   * deployment picture itself: the API passes what the deployment registered.
+   */
+  readonly own?: (catalogId: string, optionId: string) => PickerOwnPicture | undefined
+}
+
+/** A deployment's own picture for one picker option (`PickerImageOptions.own`). */
+export interface PickerOwnPicture {
+  /** Absolute URL of the picture. */
+  readonly url: string
+  /** Absolute URL of its enlarged version, when the deployment gave one. */
+  readonly largeUrl?: string
 }
 
 /** Hosts whose Cloudflare zone resizes on the fly (`/cdn-cgi/image/`, `/cdn-cgi/media/`). */
@@ -65,6 +82,12 @@ export interface PickerOptionImage {
   readonly url: string
   /** `<url> 240w, <url> 480w, …` — present only for a render the CDN resizes (Nodaro Cloud), when asked for (`srcSet: true`). */
   readonly srcSet?: string
+  /**
+   * The option's enlarged picture — present only for a deployment's own
+   * picture that has one (`PickerImageOptions.own`), when asked for
+   * (`srcSet: true`, the same request that asks for a srcset).
+   */
+  readonly largeUrl?: string
 }
 
 /**
@@ -84,7 +107,10 @@ function renderImage(url: string, withSrcSet: boolean): PickerOptionImage | unde
 }
 
 /**
- * The picture of one picker option, or undefined when it has none:
+ * The picture of one picker option, or undefined when it has none.
+ *
+ * With `images.own` (a deployment's own pictures), what it returns for the
+ * option, and nothing else. Otherwise, the platform's:
  *
  * 1. the self-hosted character photos;
  * 2. when renders are allowed (Nodaro Cloud), the music / voice pickers'
@@ -101,6 +127,7 @@ export function pickerOptionImage(
   id: string,
   images: PickerImageOptions,
 ): PickerOptionImage | undefined {
+  if (images.own) return ownImage(images.own(catalog.catalogId, id), images.srcSet === true)
   const origin = originOf(images.baseUrl)
   const photo = characterArtPath(catalog.catalogId, id)
   if (photo) return origin ? { url: origin + photo } : undefined
@@ -116,6 +143,11 @@ export function pickerOptionImage(
   return render ? renderImage(render, images.srcSet === true) : undefined
 }
 
+function ownImage(own: PickerOwnPicture | undefined, withLarge: boolean): PickerOptionImage | undefined {
+  if (!own) return undefined
+  return withLarge && own.largeUrl ? { url: own.url, largeUrl: own.largeUrl } : { url: own.url }
+}
+
 /** The absolute picture URL of one picker option, or undefined — `pickerOptionImage(...)?.url`. */
 export function pickerOptionImageUrl(
   catalog: { readonly nodeType: string; readonly catalogId: string },
@@ -126,8 +158,13 @@ export function pickerOptionImageUrl(
   return pickerOptionImage(catalog, field, id, images)?.url
 }
 
-/** The absolute URL of a Person / Styling topic's round picture, or undefined. */
+/**
+ * The absolute URL of a Person / Styling topic's round picture, or undefined —
+ * always, with a deployment's own pictures (`images.own`): a topic is not an
+ * option, so it has none of them.
+ */
 export function pickerSectionImageUrl(sectionLabel: string, images: PickerImageOptions): string | undefined {
+  if (images.own) return undefined
   const origin = originOf(images.baseUrl)
   const path = characterSectionArtPath(sectionLabel)
   return origin && path ? origin + path : undefined

package/src/picker-catalogs.ts

@@ -1088,8 +1088,9 @@ function projectOption(o: PickerOption, detail: PickerCatalogDetail, image?: Pic
 }
 
 function projectOptionFields(o: PickerOption, detail: PickerCatalogDetail, image?: PickerOptionImage): ProjectedPickerOption {
-  // `imageUrl` / `imageSrcSet` (display data) ride at both detail levels too,
-  // present only when the option has a picture (a srcset only for a CDN render).
+  // `imageUrl` / `imageSrcSet` / `imageLargeUrl` (display data) ride at both
+  // detail levels too, present only when the option has a picture (a srcset
+  // only for a CDN render, a large picture only for a deployment's own).
   const extras = {
     ...(o.motion ? { motion: o.motion } : {}),
     // A style's media rides at both detail levels: a thin client filters its image style list by it.
@@ -1098,6 +1099,7 @@ function projectOptionFields(o: PickerOption, detail: PickerCatalogDetail, image
     ...(o.restyle === false ? { restyle: false as const } : {}),
     ...(image ? { imageUrl: image.url } : {}),
     ...(image?.srcSet ? { imageSrcSet: image.srcSet } : {}),
+    ...(image?.largeUrl ? { imageLargeUrl: image.largeUrl } : {}),
   }
   return detail === "full"
     ? {

package/src/prompt-wizard-categories.ts

@@ -182,6 +182,8 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "seedream-5-lite": "Lighter Seedream, faster artistic generation",
     "seedream-5-pro": "Flagship Seedream — strongest instruction following, 2K via high quality",
     "seedream-5-flash": "Fast, low-cost Seedream 5 — quick drafts and iteration at 1K or 2K",
+    "minimax-h3-image": "MiniMax H3 — readable text in the picture, up to about 16 MP at 4K, same price at 1K and 2K",
+    "seedream-5-5": "Seedream 5.5 — natural light, materials and skin, dense small text, transparent backgrounds; 1K / 1.5K / 2K",
     "z-image": "Experimental, novel generation approaches",
     "wan-2.7":     "Wan 2.7 T2I — 1K/2K/4K, up to 9 ref images",
     "wan-2.7-pro": "Wan 2.7 Pro T2I — higher quality, 1K/2K/4K",
@@ -210,6 +212,8 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "seedream-5-lite-i2i": "Light artistic transformation",
     "seedream-5-pro-i2i": "Pro-grade instruction-based edits, multi-reference",
     "seedream-5-flash-i2i": "Fast, low-cost Seedream edits — up to 10 input images",
+    "minimax-h3-image-i2i": "MiniMax H3 edits — up to 16 reference images in one edit, readable text, up to 4K",
+    "seedream-5-5-i2i": "Seedream 5.5 edits — round after round, the rest of the picture untouched; up to 10 input images",
     "flux-kontext": "Character-consistent edits with reference awareness",
     "flux-kontext-max": "Premium character-consistent editing",
     "kontext-multi": "Multi-image Kontext via Replicate — up to 4 refs",
@@ -238,6 +242,8 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "seedream-5-lite-i2i": "Light artistic transformation",
     "seedream-5-pro-i2i": "Pro-grade instruction-based edits, multi-reference",
     "seedream-5-flash-i2i": "Fast, low-cost Seedream edits — up to 10 input images",
+    "minimax-h3-image-i2i": "MiniMax H3 edits — up to 16 reference images in one edit, readable text, up to 4K",
+    "seedream-5-5-i2i": "Seedream 5.5 edits — round after round, the rest of the picture untouched; up to 10 input images",
     "flux-kontext": "Character-consistent edits with reference awareness",
     "flux-kontext-max": "Premium character-consistent editing",
     "kontext-multi": "Multi-image Kontext via Replicate — up to 4 refs",
@@ -279,7 +285,9 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "vidu-q4": "Vidu Q4 — start frame or up to 15 reference images + 3 MP3 audio refs, native audio, 3–16s, 540p–4K (image required)",
     "kling-4": "Kling 4.0 — text, or up to 10 reference images / 5 videos / 7 characters / 3 voices; native audio, 3–30s, 720p/1080p",
     "kling-4-keyframes": "Kling 4.0 Keyframes — start frame, up to 8 in-between frames and an end frame; native audio, 3–30s, 720p/1080p",
-    "grok-imagine-video-1.5": "Grok Imagine 1.5 — image-to-video only; requires an input image",
+    "kling-4-flash": "Kling 4.0 Flash — text, or up to 10 reference images / 5 videos / 7 characters (a voice clip per character); native audio, 3–20s, 720p",
+    "grok-imagine-video-1.5": "Grok Imagine 1.5 — image-to-video only; exact start and end frame (the same image loops), up to 4 in-between frames; requires an input image",
+    "pixverse-v6-max": "PixVerse V6 Max — cinematic text-to-video, 8 aspect ratios incl. 21:9, optional native audio, 1–15s, 360p–1080p",
   },
   "image-to-video": {
     "minimax": "Versatile animation from still images",
@@ -318,7 +326,9 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "vidu-q4": "Vidu Q4 — animate a start frame, or direct up to 15 reference images + 3 MP3 audio refs; native audio, 3–16s, 540p–4K",
     "kling-4": "Kling 4.0 — a start frame joins up to 10 reference images, 5 videos, 7 characters and 3 voices; native audio, 3–30s, 720p/1080p",
     "kling-4-keyframes": "Kling 4.0 Keyframes — start frame, up to 8 in-between frames and an end frame; native audio, 3–30s, 720p/1080p",
-    "grok-imagine-video-1.5": "Grok Imagine 1.5 — stylized animation, 1–15s, 480p/720p (image required)",
+    "kling-4-flash": "Kling 4.0 Flash — a start frame alone is the exact opening frame; beside up to 10 reference images, 5 videos and 7 characters it joins them; native audio, 3–20s, 720p",
+    "grok-imagine-video-1.5": "Grok Imagine 1.5 — stylized animation, 1–15s, 480p/720p/1080p, start + up to 4 in-between + end frames (image required)",
+    "pixverse-v6-max": "PixVerse V6 Max — the image is the exact first frame and sets the shape; optional native audio, 1–15s, 360p–1080p",
   },
   "video-to-video": {
     "wan": "Style transfer and video transformation",
@@ -335,7 +345,9 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
   "extend-video": {
     "veo-extend": "Extend VEO-generated videos",
     "runway-extend": "Extend Runway-generated videos",
-    "seedance-2-extend": "Extend ANY video by URL — seamless trim-stitched continuation with audio (Seedance 2.0)",
+    "seedance-2-5-extend": "Extend ANY video by URL — seamless trim-stitched continuation with audio, 4–30s added (Seedance 2.5)",
+    "seedance-2-0-extend": "Extend ANY video by URL — seamless trim-stitched continuation with audio, 4–15s added (Seedance 2.0)",
+    "kling-4-extend": "Extend ANY video by URL — seamless trim-stitched continuation with audio, 3–30s added (Kling 4)",
   },
   "speech-to-video": {
     "wan-speech": "Wan 2.2 speech-driven video generation",

package/src/provider-prompt-doctrine.ts

@@ -302,7 +302,7 @@ const GROK_IMAGINE_DOCTRINE: ProviderPromptDoctrine = {
   tips: [
     "Keep prompts simple and direct — Subject + Action + Setting + Camera + Mood. Grok expands the prompt itself; over-specification fights the expander.",
     "Image-to-video: the input image IS the first frame (composition, identity, and style are preserved) — describe the MOTION, don't re-describe the still.",
-    "Video 1.5: 1-15s (default 8), 480p/720p/1080p, up to 7 input images (1080p allows only one). Native audio incl. music, SFX, and lip-synced dialogue — quote the line to have it spoken.",
+    "Video 1.5: 1-15s (default 8), 480p/720p/1080p; exact start and end frame (one image as both = seamless loop), up to 4 in-between frames. Native audio incl. dialogue — quote the line to have it spoken.",
     "Aspect ratio applies to text runs (1:1/16:9/9:16/3:2/2:3/auto); a single input image locks the output to the image's own aspect.",
   ],
   doctrine: `Prompt structure (xAI's guidance is minimal by design — the model auto-expands prompts):
@@ -311,18 +311,18 @@ descriptions of static/unchanged parts — spend the words on what MOVES.
 
 **Image-to-video (the primary mode)**
 - The input image is the FIRST FRAME, not a loose reference: composition, subject identity, and visual style carry over. Describe motion and camera only ("she turns toward the window as the camera slowly pushes in"); re-describing the still wastes adherence.
-- grok-imagine-video-1.5 accepts up to 7 images (identity/scene references beyond the first frame); at 1080p only ONE image is allowed.
+- grok-imagine-video-1.5 takes frames, not loose references: the start frame is the exact FIRST frame, an end frame the exact LAST frame, and the same image wired as both makes a seamless loop. Its Image References are up to 4 IN-BETWEEN frames, in order, placed evenly over the clip at whole seconds (one per second inside it — a 3s clip takes 2); extra frames are left out. Describe the motion that carries the shot from one frame to the next; the frames cannot be named in the prompt, so refer to them in words ("by the midpoint she has reached the door").
 - grok-i2v with reference images: images are addressed \`@image(n)\` in array order. Your references come first (\`@image(1)\` is your first reference); a wired start frame is appended after them and the platform names it as the opening frame.
 
 **Audio (video-1.5)**
-- Native audio generates with the clip — background music, SFX, and lip-synced dialogue. Quote the spoken line; describe the music/SFX plainly. There is no audio toggle on the KIE contract — cue (or exclude) sound in the prompt text.
+- Native audio generates with the clip — background music, SFX, and lip-synced dialogue. Quote the spoken line; describe the music/SFX plainly. The platform offers no audio toggle for it — cue (or exclude) sound in the prompt text.
 
 **Durations / tiers**
-- grok-i2v: 6 or 10 seconds. grok-imagine-video-1.5: 1-15 seconds in 1s steps (default 8), 480p (default) / 720p / 1080p. Prompt cap 4096 chars — but shorter is better here.
+- grok-i2v: 6 or 10 seconds. grok-imagine-video-1.5: 1-15 seconds in 1s steps (default 8), 480p (default) / 720p / 1080p. At 1080p it takes the start frame ALONE — a run with an end frame, a loop or in-between frames is refused before any credits are held, so use 720p for those. Prompt cap 4096 chars — but shorter is better here.
 
 Sources: KIE Grok Imagine contracts (docs.kie.ai/market/grok-imagine/image-to-video,
 docs.kie.ai/market/grok-imagine/1-5-preview), xAI Grok Imagine 1.5 release notes
-(x.ai/news/grok-imagine-1-5). Captured 2026-08-09.`,
+(x.ai/news/grok-imagine-1-5). Captured 2026-08-09; frames and in-between frames 2026-11-11.`,
 }
 
 const WAN_DOCTRINE: ProviderPromptDoctrine = {
@@ -494,6 +494,44 @@ Source: KIE Kling 4.0 market contracts (docs.kie.ai/market/kling/v4-reference-to
 docs.kie.ai/market/kling/v4-keyframe-to-video), live-probed 2026-10-23.`,
 }
 
+// Kling 4.0 Flash — one id over KIE's two Flash endpoints, picked by what is
+// wired (a start frame alone → keyframe endpoint; anything else → reference
+// endpoint). KIE contract facts plus the platform-standard structure, as for
+// Kling 4.0. The provider runner names subjects (`@Name`), binds each voice
+// clip to a subject, and drops the `@` from any undeclared mention.
+const KLING_4_FLASH_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["kling-4-flash"],
+  heading: "Kling 4.0 Flash (kling-4-flash)",
+  tips: [
+    "A start frame alone is the exact opening frame (@first_frame). Beside references it joins the reference images, like kling-4.",
+    "References: up to 10 images, 5 videos (2-20s together) and 7 characters (15 in all). Name each: @image_1, @video_1, a character's @Name.",
+    "No standalone voice: voice clip N is the voice of wired character N, if that character has 2-4 images (else the clip is dropped); write the character, never @audio_N.",
+    "3-20s (default 5), 720p only, native audio always on, no end frame. Prompt cap 8,000 chars. Aspect auto / 16:9 / 9:16 / 1:1 / 21:9 (a start frame alone sets its own shape).",
+  ],
+  doctrine: `Prompt structure (no public Kling 4.0 Flash prompt guide is captured — the KIE API contract is
+the doctrine source; platform-standard structure applies):
+subject → action → scene/environment → lighting → camera movement → style → constraints.
+
+**One model, two endpoints (picked by what is connected)**
+- A start frame with nothing else — no reference image, no reference video, no character — runs keyframe-to-video: the frame is the exact opening frame and the clip takes its shape. Name it @first_frame.
+- Anything else — text only, reference images, reference videos, characters, or a start frame beside any of them — runs reference-to-video. A start frame there joins the reference images and is named as the opening frame, as on kling-4.
+
+**Naming materials in the prompt**
+- @image_1 … for reference images, @video_1 … for reference videos, a character by its own name (@Maya). Kling refuses a prompt that names a material the request does not carry; the platform removes the "@" from such a mention so the run still starts.
+- There are no standalone voices. Reference audio clip N becomes the voice of character N, in the order the characters are wired. A character needs 2-4 images to carry a voice: a clip whose character has one image, and any clip past the last character, is dropped (the run still starts). Write who speaks by the character's name ("@Maya says…"), never @audio_1.
+
+**Limits**
+- Reference images 10, reference videos 5, characters 7 — 15 in all. Reference videos together must be 2-20 seconds; a longer set is refused before the run starts.
+- No end frame and no in-between frames: describe how the shot ends in words.
+
+**Duration, resolution, audio**
+- 3-20 seconds (default 5); 720p only; aspect auto (follows the materials, 16:9 with none) / 16:9 / 9:16 / 1:1 / 21:9. Prompts up to 8,000 characters.
+- Native audio is always generated; keep-original-sound keeps a reference video's own audio. Not yet verified for scripted lines here, so plan key dialogue as a TTS + lip-sync pass.
+
+Source: KIE Kling 4.0 Flash market contracts (docs.kie.ai/market/kling/v4-flash-reference-to-video,
+docs.kie.ai/market/kling/v4-flash-keyframe-to-video), read 2026-11-11.`,
+}
+
 const HAPPYHORSE_DOCTRINE: ProviderPromptDoctrine = {
   providers: ["happyhorse", "happyhorse-i2v", "happyhorse-ref2v", "happyhorse-edit"],
   heading: "HappyHorse 1.1 (happyhorse, happyhorse-i2v, happyhorse-ref2v)",
@@ -555,6 +593,7 @@ export const PROVIDER_PROMPT_DOCTRINES: readonly ProviderPromptDoctrine[] = [
   WAN_3_DOCTRINE,
   VIDU_Q4_DOCTRINE,
   KLING_4_DOCTRINE,
+  KLING_4_FLASH_DOCTRINE,
   HAPPYHORSE_DOCTRINE,
   RUNWAY_KIE_DOCTRINE,
 ]

package/src/seatless-assets.ts

@@ -0,0 +1,141 @@
+/**
+ * Assets that take no image seat: the reference walk for a video model whose
+ * image references are its FRAMES (a `keyframes` model — Grok Imagine Video 1.5,
+ * Kling 4.0 Keyframes; decided 2026-11-11). Only what is wired into the node's
+ * Image References becomes a frame, so a wired character, a character extra or
+ * an entity attaches no picture and is numbered nowhere: no `@image_N` may point
+ * at a picture that is never sent.
+ *
+ * What a character still gives is its identity text — its name and description,
+ * the one line both reference formats render for a described reference — and a
+ * mention of it (`@kira:1`, `@kira:1:smile`) or a `{ref:<id>}` naming it reads as
+ * its name. A non-character extra or entity adds nothing.
+ *
+ * Pure: no I/O, no mutation of inputs. `resolveVideoReferenceCore` calls it when
+ * its caller passes `assetsTakeNoSeat`.
+ */
+
+import { DEFAULT_USAGE_MODE, findCharacterMentionTokens, type UsageMode } from "@nodaro/shared/entities"
+import type { ConnectedReference, DescribedReference } from "@nodaro/shared/types"
+
+/** The fields of a video extra this walk reads (structural: `VideoExtraRef` fits). */
+export interface SeatlessExtraRef {
+  id?: string
+  characterSlug?: string
+  description?: string
+  descriptionOverride?: string
+  usageMode?: UsageMode
+  elementInjection?: string | null
+}
+
+/** The fields of a character's metadata this walk reads (structural: `CharacterMeta` fits). */
+export interface SeatlessCharacterMeta {
+  characterName?: string
+  defaultUsageMode?: UsageMode
+  canonicalDescription?: string
+}
+
+export interface SeatlessAssets {
+  /** The prompt with every wired character's mention replaced by its name. */
+  prompt: string | undefined
+  /** One name + description per character with an identity to give, in wiring order. */
+  identities: DescribedReference[]
+  /** `{ref:<id>}` names for the character extras, which the walk seats nowhere. */
+  extraNamesById: Map<string, string>
+}
+
+/**
+ * The identity text a seatless character gives. Mirrors what the legacy
+ * canonical line puts after the name — the per-use override in every mode that
+ * renders a line, else the stored description in the modes that carry it, then
+ * the wired element injection — minus the usage directive, which instructs how
+ * to use a picture the model does not receive.
+ */
+function identityDescription(
+  mode: UsageMode,
+  override: string | null | undefined,
+  canonical: string | null | undefined,
+  injection: string | null | undefined,
+): string {
+  if (mode === "none" || mode === "name") return ""
+  const parts: string[] = []
+  const o = override?.trim()
+  const c = canonical?.trim()
+  if (o) parts.push(o)
+  else if ((mode === "identical" || mode === "face-pose") && c) parts.push(c)
+  const i = injection?.trim()
+  if (i) parts.push(i)
+  return parts.join(". ")
+}
+
+export function resolveSeatlessAssets(args: {
+  prompt: string | undefined
+  /** Every wired character reference, BEFORE canonical suppression. */
+  wiredCharRefs: readonly ConnectedReference[]
+  /** Character slugs whose canonical fallback the user hid. */
+  suppressedCanonicalSlugs: ReadonlySet<string>
+  extraRefs?: readonly SeatlessExtraRef[]
+  lookupCharacterBySlug?: (slug: string) => SeatlessCharacterMeta | undefined
+}): SeatlessAssets {
+  // The reference each wired character is described from: its canonical entry,
+  // else the first entry wired for it.
+  const bySlug = new Map<string, ConnectedReference>()
+  for (const r of args.wiredCharRefs) {
+    if (r.source !== "wired-character" || !r.characterSlug) continue
+    const known = bySlug.get(r.characterSlug)
+    if (!known || (known.variantSlug && !r.variantSlug)) bySlug.set(r.characterSlug, r)
+  }
+  const nameOf = (slug: string): string => {
+    const r = bySlug.get(slug)
+    return r?.defaultName || r?.characterSlug || slug
+  }
+
+  // Mentions read as the character's name (right to left, so offsets hold).
+  let prompt = args.prompt
+  const mentioned = new Set<string>()
+  if (prompt && bySlug.size > 0) {
+    const tokens = findCharacterMentionTokens(prompt, [...bySlug.keys()])
+    for (const t of [...tokens].sort((a, b) => b.offset - a.offset)) {
+      mentioned.add(t.characterSlug)
+      prompt = prompt.slice(0, t.offset) + nameOf(t.characterSlug) + prompt.slice(t.offset + t.token.length)
+    }
+  }
+
+  const identities: DescribedReference[] = []
+  const described = new Set<string>()
+  const describe = (slug: string, name: string, description: string): void => {
+    if (described.has(slug)) return
+    described.add(slug)
+    if (description) identities.push({ name, description })
+  }
+
+  // A wired character gives its identity unless the user hid its canonical
+  // fallback and the prompt does not mention it either.
+  for (const [slug, r] of bySlug) {
+    const shown = !args.suppressedCanonicalSlugs.has(slug) || mentioned.has(slug)
+    if (!shown) continue
+    describe(
+      slug,
+      nameOf(slug),
+      identityDescription(r.defaultUsageMode ?? DEFAULT_USAGE_MODE, r.descriptionOverride, r.characterCanonicalDescription, r.elementInjection),
+    )
+  }
+
+  // A character extra (a variant picked on the node) speaks for its character
+  // once; a non-character extra has no frame and no text.
+  const extraNamesById = new Map<string, string>()
+  for (const ex of args.extraRefs ?? []) {
+    if (!ex.characterSlug) continue
+    const meta = args.lookupCharacterBySlug?.(ex.characterSlug)
+    const name = bySlug.has(ex.characterSlug) ? nameOf(ex.characterSlug) : meta?.characterName || ex.characterSlug
+    if (ex.id) extraNamesById.set(ex.id, name)
+    const own = (ex.descriptionOverride ?? "").trim() || (ex.description ?? "").trim()
+    describe(
+      ex.characterSlug,
+      name,
+      identityDescription(ex.usageMode ?? meta?.defaultUsageMode ?? DEFAULT_USAGE_MODE, own, meta?.canonicalDescription, ex.elementInjection),
+    )
+  }
+
+  return { prompt, identities, extraNamesById }
+}

package/src/video-reference-resolver.ts

@@ -50,6 +50,7 @@ import { REF_BINDING } from "./ref-binding.js"
 import { resolveRefIdTokens } from "./ref-id-tokens.js"
 import { insertBeforeStyleSection } from "./prompt-style-section.js"
 import { tidyReferenceTokenGaps, unboundReferenceTokenText } from "./unbound-reference-tokens.js"
+import { resolveSeatlessAssets } from "./seatless-assets.js"
 
 // The binding surface string and the id-addressed token resolver live in their
 // own modules (see them for the contracts); re-exported here so every existing
@@ -268,6 +269,15 @@ export interface ResolveVideoReferenceCoreArgs {
    */
   videoCaptions?: readonly string[]
   audioCaptions?: readonly string[]
+  /**
+   * No asset takes an image seat: set for a model whose image references are
+   * its FRAMES (the `keyframes` feature), where only what is wired into Image
+   * References is sent. Wired characters and extras attach no URL and are
+   * numbered nowhere; a character gives its name and description in both
+   * formats, and its mentions and `{ref:<id>}` read as its name. See
+   * `seatless-assets.ts`.
+   */
+  assetsTakeNoSeat?: boolean
 }
 
 /** Result of the HYBRID mention pass — inline role phrases + surfaced opt-in
@@ -477,8 +487,21 @@ export function resolveVideoReferenceCore(
   // below and the main assembly have to carry them. They attach no URL and claim
   // no `@image_N` seat, so they take no part in the numbering walk. Empty for
   // every caller that sends neither → every existing output is untouched.
+  // On a frames model (`assetsTakeNoSeat`) the wired characters join them as
+  // identity lines: no asset is seated, so the whole walk below is skipped.
+  const seatless = args.assetsTakeNoSeat === true
+    ? resolveSeatlessAssets({
+      prompt: args.prompt,
+      wiredCharRefs: args.wiredCharRefs,
+      suppressedCanonicalSlugs: new Set(args.suppressedCanonicalCharacterIds ?? []),
+      extraRefs: args.extraRefs,
+      lookupCharacterBySlug: args.lookupCharacterBySlug,
+    })
+    : undefined
   const describedAndCaptionLines = [
-    ...renderDescribedReferenceLines(args.describedReferences),
+    ...renderDescribedReferenceLines(
+      seatless ? [...seatless.identities, ...(args.describedReferences ?? [])] : args.describedReferences,
+    ),
     ...renderReferenceCaptionLines(args.videoCaptions, args.audioCaptions, {
       video: args.videoRefCount ?? 0,
       audio: args.audioRefCount ?? 0,
@@ -510,6 +533,8 @@ export function resolveVideoReferenceCore(
   for (const ex of args.extraRefs ?? []) {
     if (ex.id && !nameByRefId.has(ex.id)) nameByRefId.set(ex.id, "")
   }
+  // Seated nowhere, a character extra's `{ref:<id>}` reads as its character.
+  for (const [id, name] of seatless?.extraNamesById ?? []) nameByRefId.set(id, name)
   for (const [id, name] of args.refNamesById ?? []) {
     if (id) nameByRefId.set(id, name)
   }
@@ -517,8 +542,10 @@ export function resolveVideoReferenceCore(
   // recovered from URLs afterwards (the walk counts a duplicate-URL extra that
   // `merged` dedups, so URL → index is ambiguous; id → position is not).
   const slotByRefId = new Map<string, number>()
-  if (wiredCharRefs.length === 0 && !hasExtras) {
-    // No wired chars / extras, but the node can still carry plain base reference
+  if (seatless || (wiredCharRefs.length === 0 && !hasExtras)) {
+    // No wired chars / extras — or none that may take a seat (`seatless`, whose
+    // characters already ride `describedAndCaptionLines` and whose mentions are
+    // already names) — but the node can still carry plain base reference
     // images (leadingRefUrls), so `{image:N}` body tokens MUST still resolve. The
     // count is the leading-ref count (or the legacy `imageRefCount` when no
     // leading refs were passed); the leading URLs are returned for the payload.
@@ -528,7 +555,7 @@ export function resolveVideoReferenceCore(
     // leadingRefUrls mode counts the leading refs; ordinalOffset mode counts the
     // caller-owned leading refs the offset stands in for.
     const resolved = resolveReferenceTokens(
-      resolveRefIdTokens(args.prompt, { slotById: slotByRefId, nameById: nameByRefId, imageCount: counts.image }),
+      resolveRefIdTokens(seatless ? seatless.prompt : args.prompt, { slotById: slotByRefId, nameById: nameByRefId, imageCount: counts.image }),
       counts,
     )
     return {