@slatesvideo/shared 0.5.6 → 0.5.8

package/dist/prompts/model-facts.d.ts

@@ -6,8 +6,50 @@ export interface ModelFact {
     maxRefImages: number | null;
     /** Max ingredient images (video models) — null if not applicable. */
     maxIngredients: number | null;
+    /** Reference VIDEOS accepted in one generation. null/absent = none. */
+    maxReferenceVideos?: number | null;
+    /** Reference AUDIO clips accepted in one generation. null/absent = none. */
+    maxReferenceAudio?: number | null;
+    /** Combined seconds across every reference video. */
+    maxReferenceVideoSeconds?: number | null;
+    /** Combined seconds across every reference audio clip. */
+    maxReferenceAudioSeconds?: number | null;
+    /** Ceiling on TOTAL reference files across all modalities. */
+    maxReferenceFilesTotal?: number | null;
+    /** An audio reference needs at least one image or video reference alongside. */
+    audioRefNeedsCompanion?: boolean;
     notes: string;
 }
+/**
+ * One sentence of multimodal-reference capacity for a model, derived. Returns
+ * an empty string for a model that takes none, so a caller can append it
+ * unconditionally.
+ */
+export declare function multimodalRefSummary(id: string): string;
+/**
+ * The prompt words that make Seedance 2.5 reclassify a reference-carrying
+ * request as a video EDIT or EXTEND — after which it fails on task-type
+ * constraints it never set, ASYNCHRONOUSLY, once the job has queued.
+ *
+ * 🚨 THIS DRIVES A WARNING THAT NAMES THE WORDS. It must never drive a rewrite:
+ * silently mutating the user's prompt to dodge a provider classifier is banned
+ * by the prompt-transparency invariant (slate/CLAUDE.md). "Remove the tripod" is
+ * the user's sentence; the honest move is to say what will happen.
+ *
+ * ⚠️ MIRRORED, and the mirror is deliberate. The desktop's copy is
+ * `SEEDANCE_EDIT_INTENT_KEYWORDS` + `SEEDANCE_EXTEND_INTENT_KEYWORDS` in
+ * `slate/src/shared/pricing.ts`, which cannot import from this package (it is
+ * loaded by the renderer through the `@shared/*` alias, with no npm dependency).
+ * Same situation as `promptComposition.ts` ↔ `reference-composer.ts`. Change one,
+ * change the other in the same pass. Both sides match on a WORD BOUNDARY, so
+ * "added" and "readdress" are not hits.
+ */
+export declare const SEEDANCE_TASK_INTENT_WORDS: readonly ["add", "insert", "remove", "delete", "modify", "replace", "change", "edit the video", "extend", "continue", "continue the story"];
+/** Which trigger words a prompt actually contains, so a warning can name them.
+ *  Mirrors `seedanceTaskIntentWords()` in slate/src/shared/pricing.ts. */
+export declare function seedanceTaskIntentWords(prompt: string): string[];
+/** Every model that reads reference video and/or audio, for op descriptions. */
+export declare function multimodalRefModels(): string[];
 export declare const MODEL_FACTS: ModelFact[];
 export declare function getModelFact(id: string): ModelFact | undefined;
 /** The official NB2 / general image prompt formula (subject-first). */

package/dist/prompts/model-facts.js

@@ -3,6 +3,74 @@
 // RUNTIME source of truth for limits is slate/src/shared/pricing.ts
 // (MODEL_REGISTRY.maxRefImages / maxIngredientImages); these mirror it for
 // documentation. Code-verified 2026-06-25.
+//
+// Prose that ALSO appears in a skill or the tips card comes from
+// skills/_partials/*.md via PARTIALS — never restated here. A `notes` string is
+// a third rendering of a fact, and a third rendering is a third thing that can
+// survive a doctrine reversal the other two got.
+import { PARTIALS } from './partials.generated.js';
+/**
+ * One sentence of multimodal-reference capacity for a model, derived. Returns
+ * an empty string for a model that takes none, so a caller can append it
+ * unconditionally.
+ */
+export function multimodalRefSummary(id) {
+    const f = MODEL_FACTS.find((m) => m.id === id);
+    if (!f)
+        return '';
+    const v = f.maxReferenceVideos ?? 0;
+    const a = f.maxReferenceAudio ?? 0;
+    if (v === 0 && a === 0)
+        return '';
+    const parts = [];
+    if (v > 0)
+        parts.push(`${v} reference video${v === 1 ? '' : 's'} (${f.maxReferenceVideoSeconds}s combined)`);
+    if (a > 0)
+        parts.push(`${a} reference audio clip${a === 1 ? '' : 's'} (${f.maxReferenceAudioSeconds}s combined)`);
+    const total = f.maxReferenceFilesTotal ? `, ${f.maxReferenceFilesTotal} files max across all modalities` : '';
+    const companion = f.audioRefNeedsCompanion
+        ? ' Audio needs at least one image or video reference alongside it.'
+        : ' Audio-only references are allowed.';
+    return `${f.label}: up to ${parts.join(' and ')}${total}.${companion}`;
+}
+/**
+ * The prompt words that make Seedance 2.5 reclassify a reference-carrying
+ * request as a video EDIT or EXTEND — after which it fails on task-type
+ * constraints it never set, ASYNCHRONOUSLY, once the job has queued.
+ *
+ * 🚨 THIS DRIVES A WARNING THAT NAMES THE WORDS. It must never drive a rewrite:
+ * silently mutating the user's prompt to dodge a provider classifier is banned
+ * by the prompt-transparency invariant (slate/CLAUDE.md). "Remove the tripod" is
+ * the user's sentence; the honest move is to say what will happen.
+ *
+ * ⚠️ MIRRORED, and the mirror is deliberate. The desktop's copy is
+ * `SEEDANCE_EDIT_INTENT_KEYWORDS` + `SEEDANCE_EXTEND_INTENT_KEYWORDS` in
+ * `slate/src/shared/pricing.ts`, which cannot import from this package (it is
+ * loaded by the renderer through the `@shared/*` alias, with no npm dependency).
+ * Same situation as `promptComposition.ts` ↔ `reference-composer.ts`. Change one,
+ * change the other in the same pass. Both sides match on a WORD BOUNDARY, so
+ * "added" and "readdress" are not hits.
+ */
+export const SEEDANCE_TASK_INTENT_WORDS = [
+    // The edit half and the extension half of ByteDance's own trigger lists
+    // (Seedance 2.5 prompt guide → "Trigger keywords in prompt"). 'insert',
+    // 'delete' and 'modify' are named there and were missing here; 'change to',
+    // 'extend forward/backward', 'continue from' and 'extend the story' are all
+    // caught by the shorter word already in the list.
+    'add', 'insert', 'remove', 'delete', 'modify', 'replace', 'change', 'edit the video',
+    'extend', 'continue', 'continue the story',
+];
+/** Which trigger words a prompt actually contains, so a warning can name them.
+ *  Mirrors `seedanceTaskIntentWords()` in slate/src/shared/pricing.ts. */
+export function seedanceTaskIntentWords(prompt) {
+    return SEEDANCE_TASK_INTENT_WORDS.filter((w) => new RegExp(`\\b${w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i').test(prompt));
+}
+/** Every model that reads reference video and/or audio, for op descriptions. */
+export function multimodalRefModels() {
+    return MODEL_FACTS
+        .filter((m) => (m.maxReferenceVideos ?? 0) > 0 || (m.maxReferenceAudio ?? 0) > 0)
+        .map((m) => m.id);
+}
 export const MODEL_FACTS = [
     {
         id: 'nano-banana-2',
@@ -61,7 +129,36 @@ export const MODEL_FACTS = [
         kind: 'video',
         maxRefImages: null,
         maxIngredients: 9, // ingredient images per video gen
-        notes: 'PREMIUM video tier — route here the moment physics, effects, destruction, or scale matter, and for hero shots. VIDEO-ONLY: cannot generate standalone images (use NB2/FLUX.2/Seedream for those). Up to 9 ingredient images. Strong I2V / own-footage restyle. Native 4K, but 4K VIDEO is a Pro-only tier gate (base maxes at 1080p; server returns PRO_REQUIRED) — default 1080p unless the user is on Pro. Also the PREMIUM engine inside the Motion Transfer and Lip Sync tools (single-pass: driving video / dialogue are native conditioning signals — better motion fidelity, natural speech, voice cloned from a video source; video references bill input+output seconds).',
+        maxReferenceVideos: 3,
+        maxReferenceAudio: 3,
+        maxReferenceVideoSeconds: 15,
+        maxReferenceAudioSeconds: 15,
+        maxReferenceFilesTotal: 12,
+        audioRefNeedsCompanion: true,
+        notes: 'PREMIUM video tier and the DEFAULT video model — route here the moment physics, effects, destruction, or scale matter, and for hero shots. VIDEO-ONLY: cannot generate standalone images (use NB2/FLUX.2/Seedream for those). 4-15s, up to 9 ingredient images. Strong I2V / own-footage restyle. Native 4K, but 4K VIDEO is a Pro-only tier gate (base maxes at 1080p; server returns PRO_REQUIRED) — default 1080p unless the user is on Pro. Attaching a clip as a video reference (own-footage restyle, motion or dialogue conditioning) bills combined input+output seconds. 2.0 STAYS THE DEFAULT over 2.5 because it is the only Seedance with 1080p and 4K.',
+    },
+    {
+        id: 'seedance-2.5',
+        label: 'Seedance 2.5',
+        kind: 'video',
+        maxRefImages: null,
+        maxIngredients: 30, // 30 image refs; the model also takes 10 video + 10 audio (50 total)
+        maxReferenceVideos: 10,
+        maxReferenceAudio: 10,
+        maxReferenceVideoSeconds: 30,
+        maxReferenceAudioSeconds: 30,
+        maxReferenceFilesTotal: 50,
+        // No companion requirement — audio-only references are one of the things
+        // the second seat actually buys.
+        notes: `A SECOND SEAT NEXT TO 2.0, NOT AN UPGRADE OF IT — and the single most important fact is that it is 480p/720p ONLY. No 1080p, no 4K, on any provider. Pick 2.5 over 2.0 when the shot needs LENGTH (one 30s take vs 15s), MANY REFERENCES (30 images, plus video and audio references — 50 total), an AUDIO-ONLY reference (2.0 requires an image or video alongside audio; 2.5 does not), TIMED BEATS, or tighter prompt adherence. Pick 2.0 when resolution matters at all. VIDEO-ONLY. TIMESTAMPS: ${PARTIALS['seedance-25-timestamps-short']} Multi-view subject reference images are also supported on 2.5 (up to 5 subjects) where 2.0 wanted one view per subject. 🚨 COST DISCIPLINE: 720p STOPS READING AS "THE CHEAP ONE" HERE. A 30s 720p clip on the real-face route is 710 credits and on the AI-face route 484 — more than a 15s 1080p Seedance 2.0 face generation (411), against a 1,000-credit welcome grant. Always quote with slates_estimate_generation_cost before a long take, and draft at 480p/4-8s. 🚨 PROMPT INTENT IS A TASK-TYPE TRIGGER: when a request carries reference images/video/audio, the words "add", "remove", "replace", "change", "edit the video", "extend" or "continue" make the provider reclassify it as a video EDIT or EXTEND and fail it AFTER the job queues (credits are refunded, but the run stalls). If you mean to edit an existing clip, use slates_edit_video with model seedance-2.5-edit. If you mean a fresh shot, describe the finished frame rather than an instruction to change one.`,
+    },
+    {
+        id: 'seedance-2.5-edit',
+        label: 'Seedance 2.5 Edit',
+        kind: 'video',
+        maxRefImages: null,
+        maxIngredients: 0, // prompt + source clip only on slates_edit_video
+        notes: 'VIDEO-TO-VIDEO EDIT via slates_edit_video — the ONLY edit engine that accepts a clip LONGER THAN 15 SECONDS (4-30s vs Kling O3 edit 3-15s and Omni Flash edit 3-10s), though ByteDance recommends staying inside 20s for quality. That length is the whole reason to route here; for a clip inside the others\' range compare on fidelity instead (Omni Flash edit won the 7/09 prompt-only head-to-head; Kling edit is the one that takes element/style reference images). 480p/720p output, native audio. Prompt + source clip only on this op — no reference images (the MODEL takes 1-5 reference images on an edit; Slates has not wired that path). Phrase the change as "from A to B", and TIMESTAMP a partial edit ("…from 4-6 seconds…") — 2.5 reads whole-second timestamps on edits, and without a range the instruction applies to the whole clip. AUDIO is editable on this same row: change a line, change an accent, translate dialogue with re-fitted lips, strip or replace BGM and sound effects. Output length follows the SOURCE clip and is billed as the ceiled source length, on the video-reference rate tier: an edit costs roughly DOUBLE a plain 2.5 generation of the same length, because every provider bills an edit on input + output seconds. Set seedanceFace:true when a character face is visible in the clip — the faceless provider blocks faces outright. There is no consented-real-face route for editing.',
     },
     {
         id: 'kling-v3',
@@ -69,7 +166,7 @@ export const MODEL_FACTS = [
         kind: 'video',
         maxRefImages: null,
         maxIngredients: 4,
-        notes: 'DEFAULT general-purpose video model — cost-effective, strong start-frame adherence (identity/layout/text), acting, dialogue, lip-sync, any aspect ratio. Escalate to Seedance for physics. In the Motion Transfer / Lip Sync tools, Kling (MC / lip-sync / avatar) is the cheap utility lane; Seedance is the premium single-pass lane.',
+        notes: 'DEFAULT general-purpose video model — cost-effective, strong start-frame adherence (identity/layout/text), acting, dialogue, lip-sync, any aspect ratio. Escalate to Seedance for physics. Kling is also the ONLY engine behind the Motion Transfer and Lip Sync tools (MC std/pro, lip-sync, avatar) — those two tools are Kling-only.',
     },
     {
         id: 'kling-v3-edit',
@@ -111,14 +208,6 @@ export const MODEL_FACTS = [
         maxIngredients: null,
         notes: 'DEFAULT audio model — the one-pass SCENE workhorse: dialogue, SFX, and ambience together from ONE plain sentence. Route here for continuity beds, room tone, crowd/nature soundscapes, and quick scratch VO. AUDIO-ONLY: cannot generate images or video. 🚨 THERE IS NO DURATION PARAMETER — length comes from the words, so you MUST NAME THE LENGTH IN THE PROMPT TEXT ("... 15 seconds"). Slates appends the requested length automatically and BILLS the requested seconds, so a prompt that fights the number wastes credits. Prompts are ONE plain sentence, no production jargon and no SFX:/Ambient: prefixes (those are Kling syntax and hurt here). Say the crowd size out loud — "applause" returns a full room when the joke was three people. 1-120s. Inputs: ONE image (describe-what-you-see scoring) XOR up to 3 audio clips referenced in the prompt as @Audio1-@Audio3, never both. 20 preset voices, or leave voice unset and let the scene cast itself.',
     },
-    {
-        id: 'eleven-v3',
-        label: 'ElevenLabs Eleven v3 (TTS)',
-        kind: 'audio',
-        maxRefImages: null,
-        maxIngredients: null,
-        notes: 'CONTROLLED, REPEATABLE named-voice VOICEOVER — route here whenever the exact words matter and must be re-renderable in the same voice (ad reads, narration, character lines to lip-sync against). AUDIO-ONLY. The text field IS the script: it is spoken verbatim, so never put stage directions in it. 1-5000 characters, billed per 100-character bucket, so trimming a sentence genuinely saves credits. 20 preset voices (Rachel default) — pick one and keep it for the whole piece. stability 0-1 trades consistency against expressiveness (low = more emotive and more variable). No voice cloning on this route. Word-level timestamps come back free and are what a future caption pass consumes. For scene ambience or SFX rather than speech, use seed-audio / eleven-sfx.',
-    },
     {
         id: 'eleven-sfx',
         label: 'ElevenLabs Sound Effects v2',
@@ -127,14 +216,6 @@ export const MODEL_FACTS = [
         maxIngredients: null,
         notes: 'ONE-SHOT SOUND EFFECT with an EXACT duration — route here for a single hit that must land on a frame (door slam, whoosh, impact, UI blip) or for a seamless loop. AUDIO-ONLY. 0.5-22s, and Slates always sends the duration explicitly (a null duration means a non-deterministic charge, so it is never left to the model). Describe the physical CAUSE, not the label: "heavy oak door slams shut in a stone hallway" beats "door sound". Text caps at 450 characters. loop=true produces a seamless bed. prompt_influence 0-1: higher hugs the prompt with less variation, lower explores. For layered scenes with dialogue or room tone, seed-audio does it in one pass instead.',
     },
-    {
-        id: 'suno',
-        label: 'Suno',
-        kind: 'audio',
-        maxRefImages: null,
-        maxIngredients: null,
-        notes: 'FULL MUSIC TRACKS with structure — route here for anything a listener would call a song or a score. AUDIO-ONLY. EVERY call returns TWO variations for one flat price, and duration is FREE up to 360s (measured 2026-07-31: a 240s track costs the same as a default one), which makes it the cheapest way to get a bed that outlasts a cut. Two modes: DESCRIPTION mode (customMode=false, prompt is a <=500-char description and the lyrics get written for you) and CUSTOM mode (customMode=true, needs style + title; prompt then holds the EXACT LYRICS, sung as written — never put a description there). instrumental=true scores a scene with no vocals. Steer with style/negativeTags rather than piling adjectives into the prompt. duration 10-360s is V5_5 + custom mode only. Unofficial API wrapper, so treat availability as best-effort.',
-    },
 ];
 const FACT_BY_ID = new Map(MODEL_FACTS.map((m) => [m.id, m]));
 export function getModelFact(id) {

package/dist/prompts/partials.generated.js

@@ -9,6 +9,8 @@ export const PARTIALS = {
     "reference-rules-core": "Identity = a few flat-lit neutral angles; one reference per role, named inline; 2-4 refs not 12; describe environments instead of feeding a grid.\n\n1. **2-4 strong references beat both extremes.** Not 1 (warps toward itself), not 12 (averages worse). Start with 2-3 focused refs — each one adds context AND another variable to balance.\n2. **One reference per ROLE, named in the prompt** — identity / style-grade / environment. The model does **not** infer a reference's role from its position in the list; the inline name carries it. Same-role competitors drift (two \"identity\" refs of different people blend into a third face). Slates composes the naming for you from your `@mentions` / `#tags` — you never hand-write role labels.\n3. **One identity sheet per character, named inline.** A character's identity is a single asset (dominant portrait + body panels), so attach that one asset rather than a pile of views: **fewer competing renderings of a face is better, because the model cannot tell which one is authoritative and averages them.** Slates cites it as `Marcus (image 1)`. **Do NOT hand-write a \"Reference Image Instructions\" block or role essays** (\"use for identity, ignore the outfit, render a neutral expression\") — that drags the sheet's studio lighting and wardrobe into a scene that asked for neither. The prompt leads; the user's words own wardrobe, expression, lighting, and action.\n4. **Flat-light identity refs.** Prep identity references with flat, even, shadowless lighting on a plain neutral background. A studio-lit or scene-lit character sheet bleeds its lighting into every generation — the failure looks like the subject was green-screen-pasted in front of the location. Reference prep beats prompting here.\n5. **Environment: describe it, don't feed a grid.** Default to describing the location in words and let the model build a space that fits the shot. Reserve an environment reference for a mandatory exact-match, and then use ONE clean establishing image with natural ambient light that reads as the location's real light — never a multi-panel grid fed whole.\n6. **Grids: explore, don't input.** Use grids to explore compositions cheaply, then pick a cell. Never feed a grid back in as a reference — the cells share a split detail budget and were generated jointly, so their flaws propagate.\n7. **Reuse the same refs across every shot** in a sequence. Lock a set and keep it; swapping references mid-sequence causes drift, because the model adapts each reference to the current prompt rather than copying it.\n8. **Legible in-shot text → bake it into a still start frame, never trust text-to-video.** Have an image model render the text, then animate from that locked frame. Video models smear type.\n9. **Working from existing media — describe ONLY what changes.** The source already carries its composition, motion, timing, and performance; re-describing them fights the model. Narrate the delta. (Video lane: restyle your own clip while keeping the performance; delayed-VFX on \"video one\"; marker-object insertion; video-as-reference for a series.)\n10. **Style transforms happen in natural language.** By default the source's artistic medium and visual style are inherited. To change it, add a plain-text instruction (\"anime → real person\"). There are no preset pickers, and there is no style slider.",
     "reference-tips-short": "Name each reference inline; never write role essays. Slates does this for you: `@mention` a subject or environment and it composes `Marcus (image 1) in the cafe (image 2)`, citing them in the exact order it sends them. One canonical identity image avoids competing facial renderings; a \"Reference Image Instructions\" block drags reference lighting into your scene. Start with 2-3 focused refs.",
     "references-read-literally": "> **The general law: the model reads a reference literally.**\n> A reference image is not a suggestion. Whatever is baked into it — lighting, medium, texture, symmetry, competing identities — is read as a **property of the subject** and reproduced downstream. A baked rim light tints every shot made from that sheet. A sheet that looks like a 3D game render gets animated like game footage. Two competing renderings of one face get averaged into a third face.\n\nEvery reference rule below is a corollary of that one sentence, which is why \"prep the reference\" beats \"prompt around the reference\" every time:\n\n- **Flat, plain identity refs** — because scene lighting in the sheet becomes scene lighting in the output (Slates' own receipt: a studio-lit sheet produced a subject that looked green-screen-pasted in front of mountains).\n- **One authoritative rendering per subject** — because the model cannot tell which panel is the real one. ByteDance documents this failure directly: multi-view character assets \"confuse the model's character recognition, causing it to generate duplicate characters of the same appearance.\"\n- **No 3D-game-render look in a reference** — the model recognizes the render mood and inherits its motion character, so the *animation* comes out looking like game footage. This is not a taste rule; it is the same literal-reading mechanism applied to the temporal layer.\n- **Break perfect symmetry** — mirrored faces and dead-square framing read as synthetic, and the model preserves that reading rather than correcting it.\n\n**What this means in practice:** when output is wrong in a way that tracks the *subject* rather than the *scene* — the lighting is wrong the same way in every shot, the face drifts, the material looks synthetic everywhere — fix the reference, not the prompt. Prompting around a baked-in property is the expensive way to lose.",
+    "seedance-25-timestamps": "**2.0 does not respond to timestamps and answers only to shot numbers. 2.5 responds to\ninteger-second timestamps.** That is ByteDance's own first line under \"Differences from Seedance\n2.0\", and it is why a 30-second take is usable at all: the length is only worth buying if you can\nsay *when* things happen inside it.\n\nBoth formats are valid on 2.5, and you can mix them — `Shot N` blocks for a storyboard whose\npacing you are happy to leave to the model, timestamps when a beat has to land at a moment.\n\n**Three ways to control time, all first-party:**\n\n| Form | Write it like |\n|---|---|\n| **Interval** | `0-3 seconds… 3-7 seconds… 7-15 seconds` or `[1s-4s]… [4s-8s]… [8s-12s]` |\n| **Time point** | *\"Quick left sideways transition at the 5-second mark.\"* |\n| **Relative** | *\"After 3 seconds, everyone around him shakes their head.\"* · *\"The frame freezes for 1 second after he presses the shutter.\"* |\n\n**The rules that come with them:**\n\n- **One second is the smallest unit.** Integers only — no `2.5s`, no frames.\n- **No gaps in the timeline.** `0-3s… 5-6s…` leaves 3-5s unspecified and the model fills it however\n  it likes. Intervals must abut: `0-3s`, `3-7s`, `7-15s`.\n- **Budget the plot to the seconds.** Too little content in a range and the model improvises to\n  fill it; too much and you get extra cuts or dropped beats. This is the actual craft of a 30s take.\n- **Never time-code a high-frequency action.** *\"Shake your head three times per second\"* is\n  explicitly called out as a misuse — timestamps schedule beats, they don't choreograph frames.\n- **Transitions want both halves:** the moment AND the method — *\"At the 5-second mark, the camera\n  transitions leftward with a left wipe into a natural dissolve.\"*\n- **Timestamps work on an EDIT too**, and that is where they earn the most: they scope a change in\n  time as well as in content — *\"Change the man's action from drinking coffee to mopping the floor\n  from 4-6 seconds in Video 1, and leave the rest of the content unchanged.\"* Without a range, a\n  whole-clip instruction is applied to the whole clip.\n\nDo **not** carry this back to 2.0, and do not carry Veo's `[00:00-00:02]` bracket syntax into\neither — 2.0 ignores time entirely, and the cross-model syntax swap is its own known failure.",
+    "seedance-25-timestamps-short": "Seedance 2.0 ignores timing and answers only to \"Shot 1 / Shot 2\"; 2.5 acts on whole-second timestamps, and that is what makes a 30-second take controllable rather than just long. Three forms work: intervals (\"0-3 seconds…3-7 seconds\"), a point (\"at the 5-second mark\"), or relative (\"after 3 seconds\"). Whole seconds only, no gaps between intervals, and never to choreograph fast repeated motion. They work on edits too, where a range scopes the change: \"…from 4-6 seconds…\".",
     "still-gate": "**A visible defect in the still is already a STOP.** Do not animate it. Fix the frame first, then move to motion — and go to motion only when the crop passes the still scan and you genuinely need movement to confirm an uncertain edge, reflection, or object.\n\nThis is a **cost** rule as much as a craft rule: a 1080p/10s premium video generation costs many multiples of an image re-roll, and video is where a defect stops being fixable. Anything wrong in the still gets worse in motion — soft geometry mushes, broken-but-plausible objects fall apart, oily textures start crawling. **Animating a known-bad frame is the single most expensive mistake in the pipeline.** Re-rolling the image is the cheap move; re-rolling the video is not.",
 };
 //# sourceMappingURL=partials.generated.js.map

package/dist/prompts/prompting-tips.d.ts

@@ -16,7 +16,7 @@ export interface PromptingTipsEntry {
     /** Footer callout paragraphs. */
     footer?: string[];
 }
-export type PromptingTipsKey = 'seedance' | 'kling' | 'kling-edit' | 'veo' | 'omni-flash' | 'omni-flash-edit' | 'nano-banana' | 'nano-banana-lite' | 'seed-audio' | 'eleven-v3' | 'eleven-sfx' | 'suno';
+export type PromptingTipsKey = 'seedance' | 'seedance-2-5' | 'seedance-2-5-edit' | 'kling' | 'kling-edit' | 'veo' | 'omni-flash' | 'omni-flash-edit' | 'nano-banana' | 'nano-banana-lite' | 'seed-audio' | 'eleven-sfx';
 export declare const PROMPTING_TIPS: Record<PromptingTipsKey, PromptingTipsEntry>;
 /** Null when no tips exist for the key — callers render an honest fallback. */
 export declare function getPromptingTips(key: string): PromptingTipsEntry | null;

package/dist/prompts/prompting-tips.js

@@ -1,7 +1,20 @@
-// Per-model PROMPTING TIPS — the user-facing card content rendered by the
-// desktop app's "See prompting tips" modals. SINGLE SOURCE OF TRUTH: this
-// file. The desktop renders whatever this exports (no hand-written tips JSX
-// in slate — that's how the Omni Flash / Veo / Kling chimera modal shipped).
+// Per-model PROMPTING TIPS — the short, curated, FREE prompting guidance.
+// SINGLE SOURCE OF TRUTH: this file. Nothing downstream authors tips copy (no
+// hand-written tips JSX or prose anywhere — that's how the Omni Flash / Veo /
+// Kling chimera modal shipped).
+//
+// WHERE IT RENDERS (changed 2026-08-10): exactly one place, the generated page
+// https://slates.video/docs/prompting, emitted by slates-web
+// scripts/build-llm-docs.mjs via scripts/llm-docs/extract-tips.ts. It used to
+// render inside the desktop app's Settings modal — 92 cards, 12 families,
+// two-up, in a 448px drawer. It is documentation, so it lives on the web; the
+// app links to it. Do not add an in-app renderer back (slate/CLAUDE.md →
+// Prompting-tips SSOT).
+//
+// A NEW ENTRY NEEDS A READING GROUP. extract-tips.ts owns the order the page
+// lists families in; a key that appears in no group ships in this package and
+// renders on no page. The generator warns, it does not fail — check the
+// `npm run build:llm-docs` output.
 //
 // Relationship to the skills: packages/shared/skills/slates-prompting-*.md
 // are the LONG-FORM agent guidance; these tips are the curated end-user
@@ -33,7 +46,7 @@ const SEEDANCE = {
             {
                 heading: 'Shot 1 / Shot 2 / Shot 3 — never time stamps',
                 example: 'Shot 1: Side shot of the alley; the man slowly starts running.\nShot 2: He knocks over a fruit stand; the camera shakes and cuts to his face.\nShot 3: He climbs a low wall; the camera pulls back onto the empty street.',
-                note: 'ByteDance: write a "Shot 1 / Shot 2 / Shot 3" storyboard in the order events occur, then merge it into one prompt. Do NOT write "At 4 seconds" or "0:00–0:03" and do not set per-shot durations — official docs say precise timing is unstable and forcing it "may lead to abnormal generation results." Let the plot set the pacing.',
+                note: 'ByteDance: write a "Shot 1 / Shot 2 / Shot 3" storyboard in the order events occur, then merge it into one prompt. Do NOT write "At 4 seconds" or "0:00–0:03" and do not set per-shot durations — Seedance 2.0 does not respond to timestamps at all, and forcing them "may lead to abnormal generation results." Let the plot set the pacing. (Seedance 2.5 is the exception: it does read integer-second timestamps.)',
                 critical: true,
             },
             {
@@ -68,6 +81,12 @@ const SEEDANCE = {
                 example: 'The earbud rises smoothly. The camera tracks upward.',
                 note: 'Two different sentences. Mixing them ("the camera speed ramps as the earbud rises") is a common cause of shaky, glitchy output.',
             },
+            {
+                heading: 'Images, clips and audio in ONE generation',
+                example: 'Marcus (image 1) performs the motion from video 1, speaking the line in audio 1.',
+                note: 'Attaching a clip does NOT mean "edit this clip". A video or audio attachment is a REFERENCE, numbered in the rail exactly like an image, and it sits alongside your images in the same generation — the composer cites them as "image N", "video N", "audio N", in rail order, and shows you the exact sentence before you press Generate. Reorder the tiles to change what those numbers mean. To actually rewrite a clip, use Edit with AI instead — that is a different, deliberate choice.',
+                critical: true,
+            },
             {
                 heading: 'Multi-character shots — forbid twins',
                 example: 'Throughout the video, characters with completely identical appearance, clothing, and accessories are prohibited. Do not generate duplicate avatars or a twin effect.',
@@ -78,10 +97,111 @@ const SEEDANCE = {
     footer: [
         'Quality and constraint slots have their own official vocabulary: ask for "HD, rich details, cinematic texture, natural colors, soft lighting" — not "8K / masterpiece / trending on artstation." Seedance has no negative-prompt field, so constraints go inline: "keep it subtitle-free", "do not generate a logo", "do not generate a watermark".',
         'Style block at the end: one primary anchor plus 2-3 supporting details. End with "Single continuous take" if you want one shot with no cuts. Never write "no cut" or "seamless transition" — those aren\'t in the training vocabulary.',
-        'Multi-modal: up to 9 images, 3 videos and 3 audio references. Cite them by type and index — "Zhang San@Image 1", or the "Marcus (image 1)" form Slates composes from your @mentions. Never cite an asset ID instead of the image number; the model can\'t associate the two. Max length: 4,000 characters.',
+        'Multi-modal: up to 9 images, 3 videos and 3 audio references — 12 files in total, with the reference video capped at 15 seconds combined and the audio at 15. An audio reference on 2.0 needs at least one image or video alongside it (2.5 accepts audio on its own). Cite them by type and index — "Zhang San@Image 1", or the "Marcus (image 1)" form Slates composes from your @mentions. Never cite an asset ID instead of the image number; the model can\'t associate the two. Max length: 4,000 characters.',
+        'A reference VIDEO changes the price: it bills input seconds PLUS output seconds, summed across every clip attached. Two 5-second references on an 8-second generation bills 18 seconds, not 8. The Generate button and the duration menu both show that total before you commit. Over the cap is refused rather than trimmed, precisely so you are never charged for a clip the model never saw.',
         'Don\'t cross-pollinate image-model syntax: named lenses, apertures and film stocks ("85mm f/1.4", "Kodak Portra 400") are a Nano Banana lever and a Seedance anti-pattern. Translate them into shot size, depth of field and colour tone instead.',
     ],
 };
+/** The 2.0 tip that 2.5 REVERSES — 2.0 ignores timestamps, 2.5 acts on them.
+ *  Matched by heading so the 2.5 entry drops it rather than contradicting it. */
+const SEEDANCE_NO_TIMESTAMPS_HEADING = 'Shot 1 / Shot 2 / Shot 3 — never time stamps';
+const SEEDANCE_25 = {
+    ...SEEDANCE,
+    label: 'Seedance 2.5',
+    intro: [
+        'Seedance 2.5 is a SECOND SEAT next to 2.0, not an upgrade of it. It buys one 30-second take instead of 15, up to 30 image references (plus 10 video and 10 audio), audio-only references and integer-second timestamps — and it gives up 1080p and 4K entirely. It is 480p or 720p, on every route.',
+        "ByteDance's official advanced formula has 8 slots: precise subject + action details + scene/environment + lighting & color tone + camera movement + visual style + image quality + constraints. Sweet spot 60-150 words for a single shot, longer for multi-shot.",
+    ],
+    columns: [
+        [
+            {
+                heading: 'Do not write edit instructions here',
+                example: '\u274c a wide shot of the workshop, remove the tripod\n\u2705 the workshop bench, clear and uncluttered',
+                note: 'With references attached, "add", "insert", "remove", "delete", "modify", "replace", "change", "extend" and "continue" make Seedance 2.5 treat the request as a video EDIT, and it then fails on constraints it never set — after the job has queued. Describe the finished frame instead. To actually edit a clip, attach it and pick Seedance 2.5 Edit.',
+                critical: true,
+            },
+            {
+                heading: 'Timestamps work here — they do not on 2.0',
+                example: '0-3 seconds: he steps off the curb, rain starting.\n3-7 seconds: headlights sweep across him; he turns.\n7-15 seconds: he runs; the camera falls behind.',
+                note: PARTIALS['seedance-25-timestamps-short'],
+                critical: true,
+            },
+            ...SEEDANCE.columns[0].filter((t) => t.heading !== SEEDANCE_NO_TIMESTAMPS_HEADING),
+        ],
+        [
+            {
+                heading: '720p is not the cheap one here',
+                example: '30s \u00b7 720p \u00b7 Face route = 484 credits\n15s \u00b7 1080p \u00b7 Seedance 2.0 Face = 411 credits',
+                note: 'Length is what moves the price, and 2.5 doubles the length ceiling — so a 30-second 720p clip can cost more than a 15-second 1080p one, against a 1,000-credit starting balance. Draft at 480p and 4-8 seconds; spend the length only on a take you already know works. The Generate button always shows the exact number first.',
+                critical: true,
+            },
+            {
+                heading: 'Audio-only references',
+                example: 'Reference the timbre in audio 1 to generate...',
+                note: '2.5 accepts an audio reference on its own — a voice line, a music bed, a room tone — with no image or video alongside it. 2.0 could not. Audio references never cost extra on any Seedance route.',
+            },
+            ...SEEDANCE.columns[1],
+        ],
+    ],
+    footer: [
+        '30 image references is a budget, not a target — 2-4 strong references still beat both extremes, one per role. ByteDance\'s own ceilings for 2.5: 1-8 subjects bound by image reference stay stable (9-12 works but needs re-rolls), 1-5 subjects bound by video or audio reference, and 5-10 seconds is the sweet spot for a reference clip. Unlike 2.0, a multi-view turnaround sheet can be a single subject reference here — past 5 subjects, go back to one view per image. The larger budget is for long multi-shot takes and for video plus audio references alongside images.',
+        'A reference VIDEO bills input seconds PLUS output seconds, and 2.5 accepts references up to 30s combined — so a 20-second reference driving a 20-second output bills 40 seconds. The Generate button shows the total.',
+        ...(SEEDANCE.footer ?? []).slice(0, 2),
+        'Frames and reference images stay mutually exclusive, and on a first/last-frame generation Seedance 2.5 chooses the aspect ratio itself — the ratio control shows "Adaptive" because the start frame decides the shape.',
+    ],
+};
+const SEEDANCE_25_EDIT = {
+    ...SEEDANCE_25,
+    label: 'Seedance 2.5 Edit',
+    intro: [
+        'Seedance 2.5 Edit changes an existing clip: attach the clip, describe only what should be different, and the original motion, framing and timing are kept. It is the only editor in Slates that takes a clip longer than 15 seconds — 4 to 30s, against Kling O3 Edit\'s 3-15s and Omni Flash Edit\'s 3-10s.',
+        'Output length and aspect ratio follow the SOURCE clip, so there is no duration or ratio control — the clip you attach is the quote. Output is 480p or 720p with native audio.',
+    ],
+    columns: [
+        [
+            {
+                heading: 'Name the change, keep the rest',
+                example: 'Strictly edit the clip, and change the blue jacket from navy to red.',
+                note: 'The clip already carries its composition, motion, timing and performance — re-describing them fights the model. Say the change as "from A to B" rather than as an outcome: naming what it currently is tells the model what to overwrite. One change per pass; chain passes for compound edits. Never write "reference the video" in an edit: that phrasing gets the request re-read as a fresh generation inspired by your clip instead of an edit of it.',
+                critical: true,
+            },
+            {
+                heading: 'Scope the edit in time',
+                example: 'Change the man\'s action from drinking coffee to mopping the floor from 4-6 seconds, and leave the rest of the clip unchanged.',
+                note: PARTIALS['seedance-25-timestamps-short'],
+                critical: true,
+            },
+            {
+                heading: 'Turn Face on when a face is visible',
+                note: 'The default provider blocks character faces outright — this is not a price optimisation, it is whether the job runs at all. There is no consented-real-face route for editing; real-person footage the Face route rejects has to go to Kling O3 Edit.',
+                critical: true,
+            },
+            {
+                heading: 'An edit costs about double a generation',
+                note: 'Every provider bills an edit on the input clip AND the output, so a 20-second edit is priced like 40 seconds of generation. Read the number on the Generate button rather than reasoning from the generation rate.',
+            },
+        ],
+        [
+            {
+                heading: 'When to use it instead of the others',
+                note: 'Length is the reason: it is the only engine that accepts a clip over 15 seconds. Inside the others\' range, choose on fidelity — Omni Flash Edit is the prompt-only fidelity winner and the cheapest seat, and Kling O3 Edit is the one that takes subject and style reference images.',
+            },
+            {
+                heading: 'It edits the audio too',
+                example: 'Only edit the man\'s dialogue: change it to "Don\'t come over here," in an American accent. Keep everything else unchanged.',
+                note: 'The same engine rewrites what is heard while the picture stays put — change a line, change an accent, translate the dialogue and re-fit the lip movement, or strip and replace music and sound effects. Priced like any other edit, on the source clip\'s length.',
+            },
+            {
+                heading: 'Prompt and clip only',
+                note: 'No character or style reference images on this engine in Slates today. If the edit needs a reference image to lock an identity, that is Kling O3 Edit\'s job.',
+            },
+        ],
+    ],
+    footer: [
+        'Trim before you edit, not after: the bill is the source clip\'s length rounded up, so a 30-second clip you only needed 8 seconds of costs nearly four times what it had to.',
+        'Clips under 20 seconds edit most reliably. Up to 30 is accepted, and the returned clip can land within about a third of a second of the source length — only transition frames are compressed, nothing is cut.',
+    ],
+};
 const KLING = {
     label: 'Kling 3.0',
     intro: [
@@ -360,7 +480,7 @@ const NANO_BANANA_LITE = {
     ],
 };
 // ── Audio lane ──────────────────────────────────────────────────
-// The four audio surfaces prompt NOTHING like the video models. The single
+// The two audio surfaces prompt NOTHING like the video models. The single
 // most expensive mistake is bringing Kling's "SFX:" / "Ambient noise:" syntax
 // to Seed Audio, which reads it as literal text. Every entry below leads with
 // what the surface actually wants.
@@ -412,55 +532,10 @@ const SEED_AUDIO = {
             },
             {
                 heading: 'Know its seat',
-                note: 'Scenes, beds and room tone in one pass. For an exact script in a repeatable voice use Eleven v3; for a single effect on a specific frame use Sound Effects; for a song use Suno.',
-            },
-        ],
-    ],
-};
-const ELEVEN_V3 = {
-    label: 'ElevenLabs Eleven v3',
-    intro: [
-        'Eleven v3 speaks your text verbatim in a named voice. It is the controlled, repeatable lane: the same text and the same voice give you a read you can regenerate after a script tweak without the performance drifting.',
-        'Billing is per 100 characters of text, rounded up — so tightening a sentence genuinely costs less, and a stray pasted paragraph genuinely costs more.',
-    ],
-    columns: [
-        [
-            {
-                heading: 'The text field is the script',
-                example: '✗ (excited) Say this fast: Grab yours today!\n✓ Grab yours today!',
-                note: 'Everything you type gets spoken. Stage directions, character names and bracketed notes will be read out loud.',
-                critical: true,
-            },
-            {
-                heading: 'Punctuate for pace',
-                example: 'It works. Every time.  ·  It works — every time…',
-                note: 'Full stops, commas, dashes and ellipses are your only timing controls. Rewrite the punctuation before you touch the settings.',
-            },
-            {
-                heading: 'Pick a voice and stay',
-                note: '20 preset voices. Choosing one per character or per piece is what makes a series sound deliberate; swapping voices mid-piece reads as a mistake.',
-            },
-        ],
-        [
-            {
-                heading: 'Stability',
-                example: '0.3 emotive · 0.5 default · 0.8 steady',
-                note: 'Lower is more expressive and more variable take-to-take. Higher is flatter and more repeatable. Raise it for long narration, lower it for a single dramatic line.',
-            },
-            {
-                heading: 'Spell out the tricky bits',
-                example: 'SKU → "ess kay you"  ·  2026 → "twenty twenty six"',
-                note: 'Acronyms, product names, prices and years are where TTS embarrasses itself. Write the pronunciation you want.',
-            },
-            {
-                heading: 'Know its seat',
-                note: 'Exact words, repeatable voice, lines you will lip-sync against. Ambience, crowds and rooms belong to Seed Audio; one-shot effects to Sound Effects.',
+                note: 'Scenes, beds, room tone and dialogue in one pass. For a single effect that has to land on a specific frame, use Sound Effects.',
             },
         ],
     ],
-    footer: [
-        'Word-level timestamps come back with every generation at no extra cost — that is what a future caption pass will read, so there is no reason to turn them off.',
-    ],
 };
 const ELEVEN_SFX = {
     label: 'ElevenLabs Sound Effects',
@@ -504,53 +579,10 @@ const ELEVEN_SFX = {
         ],
     ],
 };
-const SUNO = {
-    label: 'Suno',
-    intro: [
-        'Suno writes full music. Every generation returns TWO variations for one flat price, and length is free up to six minutes — so there is never a reason to generate a bed that is shorter than your edit.',
-        'The one thing to get right is which mode you are in, because it changes what the prompt field means.',
-    ],
-    columns: [
-        [
-            {
-                heading: 'Description mode',
-                example: 'brooding synthwave for a night drive, analog bass, no vocals',
-                note: 'The prompt is a description (max 500 characters) and the lyrics get written for you. This is the fast path when you just need a mood.',
-            },
-            {
-                heading: 'Custom mode — the prompt IS the lyrics',
-                example: 'Style: dream pop, hazy\nTitle: Blue Hour\nPrompt: [Verse 1] The lights come on…',
-                note: 'In custom mode the prompt is sung exactly as written. Putting a description there gets your description sung back at you.',
-                critical: true,
-            },
-            {
-                heading: 'Instrumental',
-                note: 'Turn instrumental on to score a scene with no vocals — style and title still steer it, and the prompt field is ignored.',
-            },
-        ],
-        [
-            {
-                heading: 'Steer with style, not adjectives',
-                example: 'Style: 90s trip-hop, dusty breakbeat, Rhodes\nAvoid: brass, EDM drops',
-                note: 'Genre, era, instrumentation and tempo belong in the style field. Negative tags remove what keeps creeping in.',
-            },
-            {
-                heading: 'Length is free',
-                example: '10–360 seconds',
-                note: 'A six-minute track costs exactly what a default one does. Ask for longer than the cut needs and trim on the timeline.',
-            },
-            {
-                heading: 'Two songs, both yours',
-                note: 'Both variations land in the gallery. They are genuinely different takes on the same brief — audition both before re-rolling.',
-            },
-        ],
-    ],
-    footer: [
-        'Files are hosted by the provider for a limited window — Slates downloads and stores them on your machine as soon as the track finishes, so nothing expires out from under a project.',
-    ],
-};
 export const PROMPTING_TIPS = {
     seedance: SEEDANCE,
+    'seedance-2-5': SEEDANCE_25,
+    'seedance-2-5-edit': SEEDANCE_25_EDIT,
     kling: KLING,
     'kling-edit': KLING_EDIT,
     veo: VEO,
@@ -559,9 +591,7 @@ export const PROMPTING_TIPS = {
     'nano-banana': NANO_BANANA,
     'nano-banana-lite': NANO_BANANA_LITE,
     'seed-audio': SEED_AUDIO,
-    'eleven-v3': ELEVEN_V3,
     'eleven-sfx': ELEVEN_SFX,
-    suno: SUNO,
 };
 /** Null when no tips exist for the key — callers render an honest fallback. */
 export function getPromptingTips(key) {

package/dist/prompts/reference-composer.d.ts

@@ -1,7 +1,7 @@
-export type ReferenceKind = 'character' | 'environment' | 'style' | 'pinned' | 'first-frame' | 'last-frame' | 'video';
+export type ReferenceKind = 'character' | 'environment' | 'style' | 'pinned' | 'first-frame' | 'last-frame' | 'video' | 'video-ref' | 'audio-ref';
 export interface ReferenceMedia {
     path: string;
-    mediaKind: 'image' | 'video';
+    mediaKind: 'image' | 'video' | 'audio';
 }
 /**
  * A named bucket of reference media that can be @mentioned. The whole definition
@@ -22,8 +22,25 @@ export interface ComposedReferences {
     prompt: string;
     /** Free-reference image paths in cited order — flatten yields "image 1..N". */
     orderedImagePaths: string[];
-    /** Video reference paths in cited order — "video 1..M". */
+    /** Video paths in cited order — "video 1..M". Edit sources and reference
+     *  clips SHARE this list and one counter, so a mixed state can never emit
+     *  two "Video 1"s. */
     orderedVideoPaths: string[];
+    /** Reference audio paths in cited order — "audio 1..K". */
+    orderedAudioPaths: string[];
+    /**
+     * Tokens written in the prompt that matched NO reference group, as authored
+     * (`'#noir'`, `'@bob'`), first-appearance order, deduped case-insensitively.
+     *
+     * 🚨 THIS FIELD EXISTS BECAUSE THE ALTERNATIVE IS A SILENT EDIT. A `#tag` with
+     * no matching style is DELETED from the text — a raw tag confuses every model,
+     * so removing it is right, but removing it without saying so changes what the
+     * user asked for behind their back. Prompt-transparency doctrine (slate
+     * `CLAUDE.md`) requires the surface to be able to say "this went nowhere", and
+     * this is the only record that the token was ever there. Callers that render a
+     * composed-prompt preview MUST surface it.
+     */
+    unresolvedTokens: string[];
 }
 /**
  * Compose the raw prompt (mentions intact) + an ORDERED list of reference groups
@@ -41,6 +58,7 @@ export interface ComposedReferences {
 export interface ComposeOptions {
     startImageNumber?: number;
     startVideoNumber?: number;
+    startAudioNumber?: number;
 }
 export declare function composeReferences(rawPrompt: string, groups: ReferenceGroup[], opts?: ComposeOptions): ComposedReferences;
 export interface KlingEditElement {