@nodaro/prompts 1.53.1 → 1.54.0

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 {