@slatesvideo/shared 0.6.4 → 0.6.6

package/dist/prompts/agent-doctrine.js

@@ -79,6 +79,7 @@ export function buildSkillIndex() {
 const PREAMBLE = fork(`You are the Slates Studio Agent — a production assistant living inside Slates, the AI video creation studio. You plan and execute video/image production runs by chaining the Slates tools: script → characters → images → videos → quality-check → regenerate, ending with assets in the user's project (and on the timeline when asked).`, `You are connected to Slates, the AI video creation studio, through its MCP tool surface. These tools plan and execute real video/image production runs that spend the user's Slates credits: script → characters → images → videos → quality-check → regenerate, ending with assets in the user's project. Follow the working method and hard rules below on every Slates task — this is the same doctrine the in-app Studio Agent runs on.`);
 // ── The working method ─────────────────────────────────────────────
 export const WORKING_METHOD = [
+    both(`For HOW/WHERE questions, load slates_get_prompting_guide with topic "app-manual" and relevant query keywords. Teach the documented buttons and tabs, preserving model-specific conditions; do not invent UI paths or mutate the project when the user only asks for instructions. Slates is a sandbox of optional tools, not a required pipeline.`),
     both(`1. UNDERSTAND the outcome the user wants. If intent is clear, act with sane defaults — don't interrogate. If genuinely ambiguous, batch every question into ONE message.`),
     both(`2. ORIENT: call slates_get_workspace_state once at the start of a workflow. Work in the user's CURRENT project — this chat lives inside it. NEVER create a new project unless explicitly asked; if there's no current project, ask which to use.`),
     both(`3. LOAD KNOWLEDGE ON DEMAND: before prompting any model or running a multi-step workflow, load the matching guide with slates_get_prompting_guide (index below). Only the guides the task needs, when it needs them.`),

package/dist/prompts/character-sheet.js

@@ -78,6 +78,16 @@
 //      without the absence clause. If that happens, the fix is a
 //      model-conditional phrasing, not restoring the 422.
 //
+//      2026-09-09 — THE MODEL IT WAS MEASURED ON IS RETIRED; THE RULE IS NOT.
+//      GPT Image 2.5 replaced gpt-image-2 in the picker. The 422 above was
+//      measured on gpt-image-2 and that wording is left exactly as recorded,
+//      because a receipt names what was actually tested. What carries over is
+//      the MECHANISM, not the measurement: the classifier belongs to OpenAI,
+//      not to a model version, so phrase exclusions as framing on 2.5 too.
+//      ⚠️ INHERITED, NOT RE-MEASURED — nobody has re-run the 422 on Flare or
+//      Sunburst. If one of them accepts the absence clause, that is a new
+//      receipt to write down, not a reason to delete this one.
+//
 //      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

package/dist/prompts/model-capabilities.js

@@ -133,10 +133,48 @@ export const MODEL_CAPABILITIES = {
         aspectRatios: FULL_ASPECT_RATIOS,
         maxRefImages: 14,
     },
-    'gpt-image-2': {
-        // FIVE, not ten. The op's flat enum offered eleven for every image model.
+    // `gpt-image-2` WAS HERE AND IS DELIBERATELY GONE (retired 2026-09-09).
+    //
+    // An earlier pass kept the row so that a Shot saved before the swap could
+    // still resolve its caps by stored id. That was the wrong fix and the
+    // desktop refuses it: `pricing.ts` throws at MODULE LOAD for any capability
+    // row with no MODEL_REGISTRY entry, because an orphan row makes THIS op
+    // advertise, validate and quote a model the desktop can no longer render —
+    // the agent passes every gate and then hits 'Unsupported model' at the
+    // handler.
+    //
+    // Old Shots are handled where they are READ instead: `migrateGptImageModel`
+    // in slate/src/shared/pricing.ts rewrites the stored id to Flare inside
+    // `transform` (slate/src/main/storage/shots.ts), the one place a DB row
+    // becomes a Shot. That is strictly better than keeping the row — the Shot
+    // comes back FIREABLE on a live model, rather than merely openable on a dead
+    // one. Do not re-add this row to make a stale id resolve; migrate it.
+    // GPT Image 2.5 — 16 references, which IS fal's documented ceiling rather
+    // than a number of ours: `image_urls` carries `maxItems: 16` on both 2.5
+    // endpoints AND on both gpt-image-2 endpoints (schema, read 2026-09-09,
+    // ripped verbatim to second-brain/business/projects/slates/research/
+    // gpt-image-2-5-fal-api-docs.md).
+    //
+    // 🚨 IT WAS 10 UNTIL 2026-09-09, AND 10 WAS NEVER ANYBODY'S LIMIT. The
+    // comment here used to call it "the 10-reference ceiling ... unchanged by the
+    // version bump", which reads as a verified fal constraint and was not one —
+    // nobody had checked. Six reference slots were being given away, worst on
+    // Sunburst, whose entire reason for shipping is multi-reference edit work.
+    // Raised by Eric 2026-09-09 ("did we go completely full-on with all of the
+    // options on fal?").
+    //
+    // The five aspect ratios ARE a product choice; fal takes any custom size
+    // inside its own bounds (see GPT_IMAGE_25_SIZES in slate/src/shared/
+    // pricing.ts). Two SLATES caps sit outside this file and are not model
+    // limits either: the MCP's 4,000-character prompt against fal's 32,000, and
+    // image quantity, which is a fan-out and has no provider ceiling at all.
+    'gpt-image-2-5-flare': {
         aspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
-        maxRefImages: 10,
+        maxRefImages: 16,
+    },
+    'gpt-image-2-5-sunburst': {
+        aspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
+        maxRefImages: 16,
     },
     'flux-2-max': {
         aspectRatios: FULL_ASPECT_RATIOS,
@@ -368,6 +406,17 @@ export const MODEL_CAPABILITIES = {
     },
     'minimax-h3-max': {
         aspectRatios: MINIMAX_H3_ASPECT_RATIOS,
+        // 🚨 ZERO, DECLARED — not omitted. `minimax/h3-max/reference-to-video`
+        // returns 404, so there is no transport for a reference of any modality.
+        // Leaving this undeclared does NOT mean "none": `getMaxRefImages` falls
+        // back to `?? 3` for the ingredients mode, which handed this row three
+        // reference slots it cannot send. Measured 2026-09-09 — a pinned image on
+        // an h3-max generation was accepted by the composer, dropped in transit,
+        // and the model rendered the prompt text alone, returning a different
+        // person than the reference. Frames (start/end) remain the ONLY image
+        // transport on this seat.
+        maxIngredientImages: 0,
+        maxRefImages: 0,
         // 480p/768p ONLY — fal's post-train of the open weights, and the 2K
         // upscaler was never open-sourced. Declaring the shorter ladder here IS the
         // whole Max-seat mechanism: `assertVideoCapabilities` refuses 2K/4K on this

package/dist/prompts/model-facts.js

@@ -146,12 +146,20 @@ export const MODEL_FACTS = [
         notes: 'HERO-FRAME / typography PREMIUM image tier. NB2 is about 95% of Pro — escalate only when spatial composition, cinematic lighting/skin, fine typography-in-scene or deep multi-element reasoning must be perfect, and say why.',
     },
     {
-        id: 'gpt-image-2',
+        id: 'gpt-image-2-5-flare',
         route: 'generate',
-        label: 'GPT Image 2',
+        label: 'GPT Image 2.5 Flare',
         kind: 'image',
-        ...caps('gpt-image-2'),
-        notes: 'TEXT / DIAGRAM / PANEL king — near-perfect character-level text, ordered panels, exact placement. Route here for character sheets, shot grids and text-bearing panels. ALSO THE PHOTOREAL FRONT-RUNNER (Eric, 2026-08-24): at quality high it beat both Nano Banana rails head-to-head on skin realism, so route photoreal people HERE rather than away. Banana still owns edit-heavy work and the largest reference ceiling. Its own content filter, distinct from Gemini\'s. Killed if a head-to-head at the intended crop goes the other way — re-run the evidence test, never carry this forward on reputation.',
+        ...caps('gpt-image-2-5-flare'),
+        notes: 'THE FAST GPT IMAGE SEAT — OpenAI\'s small model, optimized for SPEED, quality COMPARABLE to GPT Image 2 (not better) at roughly half the latency. Route here when speed matters: drafts, exploration, volume. TEXT / DIAGRAM / PANEL work — character sheets, shot grids, text-bearing panels. When quality outranks speed, escalate to Sunburst. Own content filter, distinct from Gemini\'s. Killed by a head-to-head at the intended crop going the other way.',
+    },
+    {
+        id: 'gpt-image-2-5-sunburst',
+        route: 'generate',
+        label: 'GPT Image 2.5 Sunburst',
+        kind: 'image',
+        ...caps('gpt-image-2-5-sunburst'),
+        notes: 'THE QUALITY GPT IMAGE SEAT — OpenAI\'s most capable image model, higher quality than GPT Image 2, same price as Flare, deliberately SLOWER. Route here whenever quality outranks speed: finals, hero frames, photoreal people, and multi-reference edits where every reference must survive into one frame — its widest lead. Not for drafts; you pay latency on every frame. Explore on Flare, finish on Sunburst.',
     },
     {
         id: 'flux-2-max',

package/dist/prompts/prompting-tips.js

@@ -83,8 +83,14 @@ const SEEDANCE = {
             },
             {
                 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.',
+                example: 'Marcus (image 1) performs the motion from video 1 and uses the voice timbre from 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. EACH MODALITY IS NUMBERED SEPARATELY, from 1 — two images and one clip are "image 1", "image 2" and "video 1", never a single running count, so an audio reference is "audio 1" no matter how many images sit in front of it.',
+                critical: true,
+            },
+            {
+                heading: 'Give a character a voice',
+                example: 'Sarah (image 1) uses the voice timbre from audio 1. She says, "We open in ten minutes."',
+                note: 'An audio reference can mean five different things to Seedance — music, dialogue, voice, tone or timbre — so SAY WHICH. Name it as the voice timbre and the clip supplies the voice while your prompt supplies the words; leave it unroled and the model falls back to dialogue, re-transcribes the clip and speaks ITS words instead (a real take came back as "a map called Slates" for "an app called Slates"). Bind each speaker in a sentence rather than by attachment order — position carries nothing: "Images 1-2 are Character 1 and correspond to Audio 1; Images 3-4 are Character 2 and correspond to Audio 2." Verbatim from ByteDance. Audio-alone works on 2.5; on 2.0 pair it with at least one image or video.',
                 critical: true,
             },
             {
@@ -613,7 +619,7 @@ const MINIMAX_H3 = {
             {
                 heading: 'Cite references by number',
                 example: 'Marcus (image 1) walks into the workshop (image 2)...',
-                note: `H3 takes references as typed slots and expects plain numbered prose — image 1, video 1, audio 1. Do not hand-write angle-bracket tags. ${PARTIALS['reference-tips-short']}`,
+                note: `H3 takes references as typed slots and expects plain numbered prose — image 1, video 1, audio 1, each modality counted separately from 1. fal's own prompt-field description: "Refer to reference assets by their modality and order in the reference lists: Image 1, Image 2, Video 1, Audio 1, and so on." Do not hand-write angle-bracket tags — MiniMax's guides use \`<Subject N>\` / \`<Audio N>\` as DOCUMENTATION notation and typing them puts literal brackets in the prompt. An audio reference binds as a voice timbre to a named speaker, the same primitive Seedance uses. ${PARTIALS['reference-tips-short']}`,
             },
             {
                 heading: 'Say how much of a reference survives',

package/dist/prompts/reference-composer.js

@@ -107,6 +107,20 @@ export function isHexColorToken(sigil, token) {
 }
 export function composeReferences(rawPrompt, groups, opts = {}) {
     // ── 1. Assign global numbers by walking the list in order ──
+    //
+    // 🚨 ONE COUNTER PER MODALITY, EACH STARTING AT 1 — never a single running
+    // count across the attachments. `audio 1` is the first AUDIO, however many
+    // images precede it. This is the vendors' scheme, not a convenience:
+    // BytePlus states it ("The numbering should correspond to the upload order of
+    // the assets, such as Image 1 / Video 1 / Audio 1") and PROVES it in a mixed
+    // example that numbers two audios 1 and 2 behind four images — a global
+    // counter would make them 5 and 6. fal says the same for MiniMax H3 in its
+    // own prompt-field description. Receipts and line refs:
+    // second-brain/business/projects/slates/research/model-prompting-research.md
+    // § 2026-09-09 Multimodal reference GRAMMAR.
+    //
+    // Collapsing these into one counter would renumber every citation the prompt
+    // makes, silently — the model would be told "audio 1" about an image.
     let imageNum = opts.startImageNumber ?? 0;
     let videoNum = opts.startVideoNumber ?? 0;
     let audioNum = opts.startAudioNumber ?? 0;

package/dist/prompts/shot-spec.d.ts

@@ -60,8 +60,15 @@ export interface ShotParams {
     imageResolution?: string;
     videoResolution?: string;
     quality?: string;
-    /** gpt-image-2's tier. Always sent explicitly: fal's own default is `high`. */
-    gptQuality?: 'medium' | 'high';
+    /** GPT Image 2.5's tier. Always sent explicitly: fal's own default is
+     *  `high`, which is the third of five rungs, not the top of two. */
+    gptQuality?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    /** GPT Image's alpha switch. `auto` is fal's default and ours; `transparent`
+     *  asks for a real alpha channel rather than a painted backdrop. Costs
+     *  nothing — fal prices this family on size × quality only, so it is NOT a
+     *  cost-key segment. Named `gptBackground` because `background` already
+     *  means "generate asynchronously" on every op that carries a Shot. */
+    gptBackground?: 'auto' | 'transparent' | 'opaque';
     duration?: number;
     imageQuantity?: number;
     gridMode?: 'off' | '2x2' | '3x3';
@@ -91,6 +98,15 @@ export interface ShotParams {
     audioLoop?: boolean;
     audioPromptInfluence?: number;
     audioMultilingual?: boolean;
+    /**
+     * The VOICE a text-to-speech Shot speaks in — exactly one of the three, the
+     * same three `slates_generate_audio` takes. A Shot that carried the words but
+     * not the voice would fire in whatever voice happened to be on the bar, which
+     * is not the recipe that was saved.
+     */
+    voiceId?: string;
+    voiceReferenceAssetId?: string;
+    voiceDescription?: string;
 }
 /** Prompt-owned identity — the entities the prompt text NAMES. */
 export interface ShotMentions {
@@ -174,14 +190,14 @@ export interface ShotSpec {
  * same failure as a column nothing renders.
  */
 export declare const SCRIPT_FIELD_DESCRIPTION: {
-    readonly speaker: "Who says the line — a character id, a bare name (a character that does not exist yet is fine), or \"VO\". Null for a shot with no words.";
-    readonly line: "What is SAID, verbatim. Never camera, scene or prompt language — this is the half a person reads aloud.";
-    readonly delivery: "The parenthetical: how it is said. \"(flat, exhausted)\"";
-    readonly action: "What happens in the shot, screenplay-style. One line covering everyone in frame.";
-    readonly prop: "The one readable object carrying the beat.";
-    readonly shotSize: "Framing, in your own words — \"wide\", \"long-lens CU, other head blurred\". FREE TEXT: it is bucketed for the variety count and never rejected or rewritten.";
-    readonly camera: "Camera move, in your own words — \"slow push in\", \"through the rearview, eyes only\". FREE TEXT, same rule as shotSize.";
-    readonly continues: "True when this row's line runs on from the previous row's — one sentence split across two cuts. The signature VO move; set it deliberately.";
+    readonly speaker: "Speaker: character id, bare name (including a new character), or \"VO\". Null when silent.";
+    readonly line: "Words spoken verbatim; no camera or scene instructions.";
+    readonly delivery: "Optional performance note. Leave null unless a specific direction is needed; do not fill every line with stock adjectives. Not sent to TTS: put supported inline cues in the spoken text using the selected model's prompting guide.";
+    readonly action: "Screenplay action covering everyone in frame.";
+    readonly prop: "The readable object carrying the beat.";
+    readonly shotSize: "Free-text framing, e.g. \"wide\" or \"long-lens CU, other head blurred\"; bucketed only for variety counts.";
+    readonly camera: "Free-text camera move, e.g. \"slow push in\"; never rejected or rewritten.";
+    readonly continues: "True when this line continues the previous row: one sentence across two cuts.";
 };
 /** The script fields, as a list. Sorted from the description map so the two
  *  cannot disagree — never a second hand-written array. */
@@ -223,6 +239,10 @@ export declare function effectivePrompt(spec: ShotSpec): string;
  *  overlays what it actually found, so a missing field is never `undefined`
  *  leaking into a request. */
 export declare function emptyShotSpec(): ShotSpec;
+/** The mutually exclusive TTS source fields, shared by readers and patch merging. */
+export declare const VOICE_SOURCE_FIELDS: readonly ["voiceId", "voiceReferenceAssetId", "voiceDescription"];
+/** Setting a voice replaces the previous source; unrelated parameter edits preserve it. */
+export declare function mergeShotParams(existing: ShotParams, patch: Record<string, unknown>): ShotParams;
 /**
  * Read a `ShotSpec` out of whatever is on disk — a row written by an older
  * build, a partial object from an op, `null`.

package/dist/prompts/shot-spec.js

@@ -46,14 +46,14 @@ export const ORDERED_ATTACHMENT_ROLES = Object.keys(ORDERED_ROLE_EMISSION).sort(
  * same failure as a column nothing renders.
  */
 export const SCRIPT_FIELD_DESCRIPTION = {
-    speaker: 'Who says the line — a character id, a bare name (a character that does not exist yet is fine), or "VO". Null for a shot with no words.',
-    line: 'What is SAID, verbatim. Never camera, scene or prompt language — this is the half a person reads aloud.',
-    delivery: 'The parenthetical: how it is said. "(flat, exhausted)"',
-    action: 'What happens in the shot, screenplay-style. One line covering everyone in frame.',
-    prop: 'The one readable object carrying the beat.',
-    shotSize: 'Framing, in your own words — "wide", "long-lens CU, other head blurred". FREE TEXT: it is bucketed for the variety count and never rejected or rewritten.',
-    camera: 'Camera move, in your own words — "slow push in", "through the rearview, eyes only". FREE TEXT, same rule as shotSize.',
-    continues: 'True when this row\'s line runs on from the previous row\'s — one sentence split across two cuts. The signature VO move; set it deliberately.',
+    speaker: 'Speaker: character id, bare name (including a new character), or "VO". Null when silent.',
+    line: 'Words spoken verbatim; no camera or scene instructions.',
+    delivery: 'Optional performance note. Leave null unless a specific direction is needed; do not fill every line with stock adjectives. Not sent to TTS: put supported inline cues in the spoken text using the selected model\'s prompting guide.',
+    action: 'Screenplay action covering everyone in frame.',
+    prop: 'The readable object carrying the beat.',
+    shotSize: 'Free-text framing, e.g. "wide" or "long-lens CU, other head blurred"; bucketed only for variety counts.',
+    camera: 'Free-text camera move, e.g. "slow push in"; never rejected or rewritten.',
+    continues: 'True when this line continues the previous row: one sentence across two cuts.',
 };
 /** The seven free-text script fields (everything but the `continues` flag) —
  *  the set an op accepts as `string | null` and a layer renders as text. */
@@ -151,6 +151,17 @@ export function emptyShotSpec() {
 }
 const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
 const strArray = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string' && x.length > 0) : [];
+/** The mutually exclusive TTS source fields, shared by readers and patch merging. */
+export const VOICE_SOURCE_FIELDS = ['voiceId', 'voiceReferenceAssetId', 'voiceDescription'];
+/** Setting a voice replaces the previous source; unrelated parameter edits preserve it. */
+export function mergeShotParams(existing, patch) {
+    const next = { ...existing };
+    if (VOICE_SOURCE_FIELDS.some((k) => typeof patch[k] === 'string' && patch[k].trim())) {
+        for (const k of VOICE_SOURCE_FIELDS)
+            delete next[k];
+    }
+    return readParams({ ...next, ...patch });
+}
 function readParams(v) {
     if (!v || typeof v !== 'object')
         return {};
@@ -175,6 +186,9 @@ function readParams(v) {
     s('audioLanguage');
     s('audioAccent');
     s('negativePrompt');
+    s('voiceId');
+    s('voiceReferenceAssetId');
+    s('voiceDescription');
     n('duration');
     n('imageQuantity');
     n('audioDurationSeconds');
@@ -185,8 +199,24 @@ function readParams(v) {
     b('multiShot');
     b('audioLoop');
     b('audioMultilingual');
-    if (raw.gptQuality === 'medium' || raw.gptQuality === 'high')
+    // Shape validation only. The pre-2026-09-09 tier MIGRATION deliberately does
+    // NOT live here: this file is a dependency-free leaf, and the migration's
+    // SSOT is `migrateGptQuality` in slate/src/shared/pricing.ts, applied in
+    // `transform` (slate/src/main/storage/shots.ts) — the one place a DB row
+    // becomes a `Shot`. NOT in `resolveShotSpec`: by the time a spec reaches that
+    // function its gate value (`gpt-image-2`) has already been rewritten, so a
+    // copy there could never fire. A stored value outside the union is dropped
+    // exactly as before — it just has five legal names now instead of two.
+    if (raw.gptQuality === 'low' ||
+        raw.gptQuality === 'medium' ||
+        raw.gptQuality === 'high' ||
+        raw.gptQuality === 'xhigh' ||
+        raw.gptQuality === 'max') {
         out.gptQuality = raw.gptQuality;
+    }
+    if (raw.gptBackground === 'auto' || raw.gptBackground === 'transparent' || raw.gptBackground === 'opaque') {
+        out.gptBackground = raw.gptBackground;
+    }
     if (raw.gridMode === 'off' || raw.gridMode === '2x2' || raw.gridMode === '3x3')
         out.gridMode = raw.gridMode;
     if (Array.isArray(raw.multiShotSegments)) {
@@ -276,6 +306,8 @@ export function shotAssetIds(spec) {
         ids.push(spec.firstFrameAssetId);
     if (spec.lastFrameAssetId)
         ids.push(spec.lastFrameAssetId);
+    if (spec.params.voiceReferenceAssetId)
+        ids.push(spec.params.voiceReferenceAssetId);
     return [...new Set(ids.filter(Boolean))];
 }
 /** Total attachment count — what a list row shows without composing anything. */