@slatesvideo/shared 0.5.5 → 0.5.7

package/dist/prompts/character-sheet.d.ts

@@ -9,7 +9,8 @@
  * that cannot match the portrait's, so the sheet would carry two competing
  * identities and the model averages them. A back view has no face to compete
  * with, and it is the only panel where hair fall reads. See the header comment
- * for the receipt and for why the phrasing must stay framing, not removal.
+ * for the receipt, and for why the phrasing must stay FRAMING rather than
+ * removal and must be SCOPED TO THE FACE rather than to the whole body.
  */
 export declare const CHARACTER_SHEET_PANELS_DESC: string;
 /** Panel identifiers, in sheet order. */

package/dist/prompts/character-sheet.js

@@ -11,14 +11,45 @@
 //   2. One authoritative face avoids averaging competing renderings.
 //   3. One generation means one asset to inspect and bind.
 //
-// KNOWN COST, accepted for v1: a neutral chest-up portrait carries no dental
-// information, so a character who smiles in a shot gets invented teeth. The
-// 2026-06-26 doctrine already holds that the user's prompt owns expression.
-// Revisit only if a receipt shows invented teeth.
+// EXPRESSION IS A SLIGHT SMILE WITH THE TEETH JUST VISIBLE (Eric, 2026-07-30,
+// replacing the v1 neutral default). The v1 note called neutral's missing
+// dental information a "known cost, revisit only if a receipt shows invented
+// teeth" — this is that revisit, and it arrived from the other direction:
+// Eric hand-edited a sheet to smiling and the result "worked really well".
+//
+// WHY: a closed-mouth portrait carries ZERO dental information, so every
+// downstream shot where the character smiles has to invent teeth, and teeth are
+// person-specific and stable — inventing them is a highly visible identity
+// break. The smile also records the nasolabial fold, the eye crinkle and where
+// the cheeks sit raised, none of which a neutral mouth shows.
+//
+// THE COST, NAMED: `references-read-literally.md` says a baked-in property is
+// read as a property of the SUBJECT, so a smile risks a character who smiles
+// through a beat that asked for grief. Survivable because the 2026-06-26
+// doctrine still holds — the user's prompt owns expression, and downstream
+// prompts name an emotional register on every delivered line.
+//
+// SLIGHT, never a grin: a broad smile deforms eyes, cheeks and mouth enough
+// that the model has to un-deform it for any neutral shot.
+//
+// NON-HUMANS ARE CARVED OUT (Eric, 2026-07-30). A smile clause on a horse, a
+// dragon or a robot produces bared teeth. Non-human characters get a natural
+// neutral expression instead. NOTE THE SCOPE DIFFERS from the A-pose carve-out
+// beside it: that one is anatomical (quadruped / non-bipedal), this one is
+// about having a human mouth — so a BIPEDAL robot or humanoid alien is covered
+// by this carve-out and not by that one. Two carve-outs, deliberately, because
+// one predicate does not fit both.
+//
+// Receipt strength: N=1, and it is a "looked right" judgement, not a scored
+// identity-hold comparison against the neutral sheets. HOW YOU'D KNOW THIS IS
+// BEATEN: a character smiling through a beat prompted angry or grieving, or
+// identity holding measurably worse than neutral did. Reverting is one line.
 //
 // THE FRONT PANEL IS HEADLESS (shipped 2026-07-22, receipt-gated). The face is
-// cropped off the front body panel — the "ghost mannequin" treatment — taking
-// competing face renderings 2 → 1. The BACK panel keeps its head: it has no
+// cropped off the front body panel, taking competing face renderings 2 → 1.
+// ONLY the face — the body, neck, arms and hands render normally; see the
+// 2026-07-30 (b) note below for what happens when that isn't said. The BACK
+// panel keeps its head: it has no
 // face to compete with the portrait, and it is the only panel where hair fall
 // reads. The rule is "kill every competing rendering of the FACE", not "kill
 // every head".
@@ -27,9 +58,45 @@
 // real generations (research/model-prompting-research.md, "Head-crop receipt"):
 //   1. It is prompt-reachable. NB2 renders a clean invisible-mannequin panel
 //      with no refusal. THIS DEPENDS ON THE PHRASING: it is framed as FRAMING
-//      ("cropped at the collarbone, head not shown, invisible-mannequin
-//      presentation"), a standard e-commerce genre with deep training data.
-//      Never phrase it as removal or decapitation.
+//      ("cropped at the collarbone, invisible-mannequin presentation"), a
+//      standard e-commerce genre with deep training data. Never phrase it as
+//      removal or decapitation.
+//
+//      2026-07-30 (a) — THE PHRASING NARROWED, and the receipt above was
+//      MODEL-SCOPED. "framed from the collarbone down with the head not shown"
+//      passed NB2 and is a HARD 422 on gpt-image-2: fal returns
+//      content_policy_violation with loc ["body","prompt"], so the text is
+//      rejected before any image is read. Diagnosis: "the head not shown"
+//      states an anatomical ABSENCE — a headless human body — which reads as
+//      gore to OpenAI's classifier. "cropped at the collarbone" states a
+//      CAMERA fact and carries the same instruction.
+//      RULE: describe an exclusion as a framing choice, never as a missing
+//      body part. The "invisible-mannequin" genre anchor is KEPT because the
+//      NB2 receipt says it is what makes the panel reachable there.
+//      HOW YOU'D KNOW THIS IS BEATEN: a front panel that comes back with a
+//      head on it, meaning "cropped at the collarbone" alone is too weak
+//      without the absence clause. If that happens, the fix is a
+//      model-conditional phrasing, not restoring the 422.
+//
+//      2026-07-30 (b) — THE GENRE ANCHOR HAS TO BE SCOPED TO THE FACE, and
+//      this one cost real generations. "an invisible-mannequin presentation
+//      WHERE THE CLOTHING HOLDS ITS OWN SHAPE" is the e-commerce genre stated
+//      in full — and the full genre means NO BODY AT ALL, an empty outfit
+//      photographed on nothing. Eric's sheets came back with the skin removed:
+//      no neck, no hands, no forearms, a floating garment. The genre anchor
+//      was doing exactly what it says.
+//      Eric's replacement, verbatim, and the default since: "an invisible-
+//      mannequin presentation with just the face cropped out." Same anchor
+//      (still what makes the panel reachable on NB2), bounded so the only
+//      thing missing is the face.
+//      RULE: a genre anchor imports the WHOLE genre unless you bound it —
+//      name what STAYS, not just what goes. This is the same failure shape as
+//      (a) from the opposite side: (a) was an exclusion phrased too
+//      anatomically, (b) was an exclusion scoped too widely.
+//      HOW YOU'D KNOW THIS IS BEATEN: front panels returning with a head on
+//      them — "just the face cropped out" would then be reading as a face
+//      edit rather than a crop, leaving the collarbone clause to carry it
+//      alone.
 //   2. The literal-reading law does NOT fire on it. This was the real risk and
 //      it is ours, not the source corpus's: `references-read-literally.md` says
 //      a baked-in property is read as a property of the SUBJECT, and this panel
@@ -65,11 +132,12 @@ import { renderStyleInstruction } from './style-library.js';
  * that cannot match the portrait's, so the sheet would carry two competing
  * identities and the model averages them. A back view has no face to compete
  * with, and it is the only panel where hair fall reads. See the header comment
- * for the receipt and for why the phrasing must stay framing, not removal.
+ * for the receipt, and for why the phrasing must stay FRAMING rather than
+ * removal and must be SCOPED TO THE FACE rather than to the whole body.
  */
 export const CHARACTER_SHEET_PANELS_DESC = 'a large chest-up portrait on the left at a three-quarter angle (never dead-on), ' +
-    'a full-body front view in a relaxed A-pose in the centre, framed from the collarbone down with the head not shown — ' +
-    'an invisible-mannequin presentation where the clothing holds its own shape, ' +
+    'a full-body front view in a relaxed A-pose in the centre, cropped at the collarbone — ' +
+    'an invisible-mannequin presentation with just the face cropped out, ' +
     'and a full-body back view on the right with the head and hair fully visible';
 /** Panel identifiers, in sheet order. */
 export const BODY_POSE_LABELS = ['portrait', 'front', 'back'];
@@ -89,8 +157,9 @@ export function buildCharacterIdentityPrompt(userStyle) {
         `${CHARACTER_SHEET_PANELS_DESC}. ` +
         `The portrait is the largest panel and occupies roughly a quarter to a third of the sheet — it is the sole authority for the face, so render it at maximum facial detail. ` +
         `No second rendering of the face anywhere on the sheet. ` +
-        `Neutral expression and identical appearance, wardrobe and hair across all three panels. ` +
+        `A slight natural smile with the teeth just visible, and identical appearance, wardrobe and hair across all three panels. ` +
         `${styleDirective(userStyle)} ${IDENTITY_LIGHTING_CLAUSE} ${IDENTITY_CRAFT_CLAUSE} ` +
+        `For non-human characters, use a natural neutral expression instead of a smile. ` +
         `For quadruped or non-bipedal characters, replace the A-pose with a natural standing stance, show the whole animal including the head on both body panels, and keep the same three-panel layout. ` +
         `No text, no labels, no captions, no panel borders.`);
 }

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

@@ -1,13 +1,55 @@
 export interface ModelFact {
     id: string;
     label: string;
-    kind: 'image' | 'video';
+    kind: 'image' | 'video' | 'audio';
     /** Max reference images (image models) — null if not applicable. */
     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", "remove", "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,63 @@
 // 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.
+/**
+ * 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 = [
+    'add', 'remove', '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 +118,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), or tighter prompt adherence. Pick 2.0 when resolution matters at all. VIDEO-ONLY. 🚨 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). 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. 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 +155,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',
@@ -103,6 +189,22 @@ export const MODEL_FACTS = [
         maxIngredients: 0, // prompt + source clip ONLY — no element/style refs on this endpoint
         notes: 'VIDEO-TO-VIDEO EDIT, prompt-only — THE EDIT-FIDELITY WINNER (7/09 head-to-head vs Kling edit on real talking footage: lips held perfectly, audio near-identical, both action beats landed). Takes an EXISTING 3-10s clip and changes what the prompt names, footage-synced (prop/effect/environment/lighting swaps). Fidelity is EARNED by prompt discipline: ONE short instruction + "Keep everything else the same." — long descriptive prompts DESTROY it (Google-documented + 7/09 receipt). Never name objects as metaphors ("candle-like" → literal candle). Quirk: occasional tail jitter/doubled last speech beat — trim the tail. NO reference images (identity swaps needing refs → Kling edit); bit-exact audio needs → Kling keep_audio or segment-splice. 720p output, cheapest edit seat (~2/3 of Kling edit Std).',
     },
+    {
+        id: 'seed-audio',
+        label: 'Seed Audio 1.0',
+        kind: 'audio',
+        maxRefImages: 1, // ONE image XOR up to 3 audio clips — the two inputs are mutually exclusive.
+        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-sfx',
+        label: 'ElevenLabs Sound Effects v2',
+        kind: 'audio',
+        maxRefImages: null,
+        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.',
+    },
 ];
 const FACT_BY_ID = new Map(MODEL_FACTS.map((m) => [m.id, m]));
 export function getModelFact(id) {

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';
+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
@@ -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,90 @@ 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.',
     ],
 };
+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), and audio-only references — and it gives up 1080p and 4K entirely. It is 480p or 720p, on every route. Everything below about writing the prompt is the same as 2.0.',
+        "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", "remove", "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,
+            },
+            ...SEEDANCE.columns[0],
+        ],
+        [
+            {
+                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. Every reference rule still holds: 2-4 strong references beat both extremes, one reference per role, one authoritative rendering per subject — and past 4 reference PEOPLE, output stability drops regardless of the cap. 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 to a red one.',
+                note: 'The clip already carries its composition, motion, timing and performance — re-describing them fights the model. 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: '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: 'Prompt and clip only',
+                note: 'No character or style reference images on this engine. 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.',
+    ],
+};
 const KLING = {
     label: 'Kling 3.0',
     intro: [
@@ -359,8 +458,110 @@ const NANO_BANANA_LITE = {
             : card),
     ],
 };
+// ── Audio lane ──────────────────────────────────────────────────
+// 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.
+const SEED_AUDIO = {
+    label: 'Seed Audio 1.0',
+    intro: [
+        'Seed Audio builds a whole audio scene — dialogue, effects and ambience together — from one plain sentence. Write it the way you would describe the moment to a person standing next to you, not the way you would write a video prompt.',
+        'It has no duration setting. Length comes from the words, so Slates appends your chosen duration to the prompt ("… 15 seconds") and bills exactly that. Set the duration control to what you actually want and let the sentence stay clean.',
+    ],
+    columns: [
+        [
+            {
+                heading: 'One plain sentence',
+                example: 'nature soundscape, wide open field cicadas and birds and a loon.',
+                note: 'No shot language, no production jargon, no formatting. Plain description outperforms anything that reads like a spec sheet.',
+            },
+            {
+                heading: 'Duration lives in the prompt',
+                example: 'tiny applause of 2 or 3 people at an open mic. 15 seconds',
+                note: 'The duration control writes this for you. Do not also type a different length into your sentence — the two will fight and you pay for the one you selected.',
+                critical: true,
+            },
+            {
+                heading: 'Say the crowd size',
+                example: 'tiny applause of 2 or 3 people  ·  a packed arena roaring',
+                note: '"Applause" alone returns a full room. Scale words are the single highest-leverage edit on any crowd, traffic or nature bed.',
+            },
+            {
+                heading: 'Cut beds longer than the shot',
+                note: 'Ask for a few seconds more than the clip needs so the edit has handles to fade in and out of. Beds that end exactly on the cut always sound clipped.',
+            },
+        ],
+        [
+            {
+                heading: 'No Kling syntax here',
+                example: '✗ SFX: heavy boots\n✓ heavy boots on wet pavement, a siren far off',
+                note: 'The "SFX:" and "Ambient noise:" prefixes belong to Kling video prompts. Seed Audio treats them as words in the scene and the result gets worse.',
+                critical: true,
+            },
+            {
+                heading: 'Dialogue in quotes',
+                example: 'a tired bartender says, "we closed twenty minutes ago", glasses clinking behind him',
+                note: 'Speech goes in quotes inside the same sentence as the room. Pick a preset voice for a specific speaker, or leave it unset and let the scene cast itself.',
+            },
+            {
+                heading: 'References',
+                example: 'match the room tone of @Audio1',
+                note: 'Up to 3 audio clips (max 30s each), referenced as @Audio1–@Audio3 — OR one image to score what is in frame. Never both in the same generation.',
+            },
+            {
+                heading: 'Know its seat',
+                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.',
+            },
+        ],
+    ],
+};
+const ELEVEN_SFX = {
+    label: 'ElevenLabs Sound Effects',
+    intro: [
+        'Sound Effects makes one short sound with an exact length — the lane for a hit that has to land on a specific frame, or a seamless loop you can lay under a whole scene.',
+        'Duration is always sent explicitly (0.5–22s). Billing is per second, so the length you pick is the price you pay.',
+    ],
+    columns: [
+        [
+            {
+                heading: 'Describe the cause, not the label',
+                example: '✗ door sound\n✓ heavy oak door slams shut in a stone hallway',
+                note: 'Material, weight and room are what separate a usable effect from a stock-library shrug. Name all three.',
+                critical: true,
+            },
+            {
+                heading: 'One sound per generation',
+                note: 'This surface makes a single event. A door, then footsteps, then a siren is three generations layered on the timeline — or one Seed Audio scene.',
+            },
+            {
+                heading: 'Duration is the edit',
+                example: '0.8s for an impact · 4s for a whoosh · 22s for a bed',
+                note: 'Ask for roughly the length you need. A 4-second request for a door slam pads the tail with room tone you then have to trim.',
+            },
+        ],
+        [
+            {
+                heading: 'Loops',
+                example: 'steady rain on a canvas tent  (loop on, 12s)',
+                note: 'Turn loop on for anything continuous — rain, engine hum, crowd murmur — and it will tile without a seam.',
+            },
+            {
+                heading: 'Prompt influence',
+                example: '0.3 default · 0.7 literal',
+                note: 'Higher hugs your wording with less variation between takes; lower explores. Raise it when a re-roll keeps wandering off the brief.',
+            },
+            {
+                heading: 'Know its seat',
+                note: 'One precise effect on a known frame. Full rooms and layered scenes are cheaper and better in one Seed Audio pass.',
+            },
+        ],
+    ],
+};
 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,
@@ -368,6 +569,8 @@ export const PROMPTING_TIPS = {
     'omni-flash-edit': OMNI_FLASH_EDIT,
     'nano-banana': NANO_BANANA,
     'nano-banana-lite': NANO_BANANA_LITE,
+    'seed-audio': SEED_AUDIO,
+    'eleven-sfx': ELEVEN_SFX,
 };
 /** Null when no tips exist for the key — callers render an honest fallback. */
 export function getPromptingTips(key) {