@slatesvideo/shared 0.6.9 → 0.6.10

package/dist/prompts/model-capabilities.js

@@ -100,6 +100,105 @@ const MINIMAX_H3_ASPECT_RATIOS = ['21:9', '16:9', '4:3', '1:1', '3:4', '9:16'];
  * to lose track of what was actually generated.
  */
 const LTX_2_5_ASPECT_RATIOS = ['16:9', '9:16'];
+export const GPT_QUALITY_TIERS = ['low', 'medium', 'high', 'xhigh', 'max'];
+export const GPT_BACKGROUNDS = ['auto', 'transparent', 'opaque'];
+// Product output sizes; schema bounds and metering receipt live in the GPT harvest.
+export const GPT_IMAGE_25_SIZES = {
+    '1k': {
+        '1:1': { width: 1024, height: 1024 },
+        '16:9': { width: 1360, height: 768 },
+        '9:16': { width: 768, height: 1360 },
+        '4:3': { width: 1168, height: 880 },
+        '3:4': { width: 880, height: 1168 },
+    },
+    '2k': {
+        '1:1': { width: 1440, height: 1440 },
+        '16:9': { width: 1920, height: 1080 },
+        '9:16': { width: 1080, height: 1920 },
+        '4:3': { width: 1664, height: 1248 },
+        '3:4': { width: 1248, height: 1664 },
+    },
+    '3k': {
+        '1:1': { width: 1920, height: 1920 },
+        '16:9': { width: 2560, height: 1440 },
+        '9:16': { width: 1440, height: 2560 },
+        '4:3': { width: 2224, height: 1664 },
+        '3:4': { width: 1664, height: 2224 },
+    },
+    '4k': {
+        // 1:1 and 16:9 sit EXACTLY on the 8,294,400 ceiling — 3840×2160 is one of
+        // fal's own priced sizes, so the bound is inclusive. 4:3 / 3:4 are the two
+        // that had to move; see the constraint note above.
+        '1:1': { width: 2880, height: 2880 },
+        '16:9': { width: 3840, height: 2160 },
+        '9:16': { width: 2160, height: 3840 },
+        '4:3': { width: 3264, height: 2448 },
+        '3:4': { width: 2448, height: 3264 },
+    },
+};
+/**
+ * fal's named ~1MP presets per aspect ratio, with custom dims where fal has no
+ * preset. The `1k` rung of every non-GPT image model resolves through this.
+ */
+export const FAL_1MP_SIZES = {
+    '1:1': 'square_hd',
+    '4:3': 'landscape_4_3',
+    '3:4': 'portrait_4_3',
+    '16:9': 'landscape_16_9',
+    '9:16': 'portrait_16_9',
+    '2:3': { width: 832, height: 1248 },
+    '3:2': { width: 1248, height: 832 },
+    '4:5': { width: 896, height: 1120 },
+    '5:4': { width: 1120, height: 896 },
+    '21:9': { width: 1344, height: 576 },
+};
+/** Pixel dims for a megapixel target at an aspect ratio, rounded to multiples of 8. */
+export function computeFalDimensions(aspectRatio, targetMP) {
+    const parts = aspectRatio.split(':').map(Number);
+    const w = parts[0] || 16;
+    const h = parts[1] || 9;
+    const ratio = w / h;
+    const targetPixels = targetMP * 1_000_000;
+    return {
+        width: Math.round(Math.sqrt(targetPixels * ratio) / 8) * 8,
+        height: Math.round(Math.sqrt(targetPixels / ratio) / 8) * 8,
+    };
+}
+/**
+ * The `image_size` a non-GPT fal image request carries, for one model × aspect ×
+ * resolution rung.
+ *
+ * 🚨 THIS IS A BILLING INPUT, WHICH IS WHY IT LIVES HERE (moved out of
+ * slate/src/main/api/fal.ts, 2026-09-10). The resolution rung is a segment of
+ * every image cost key, and nothing in the REQUEST names it — fal is told pixel
+ * dimensions, not "2k". The proxy therefore recovers the rung by running this
+ * function over the model's declared `imageResolutions` × `aspectRatios` and
+ * matching the body's `image_size`, exactly as it recovers a GPT Image rung from
+ * `GPT_IMAGE_25_SIZES`. A second copy of this arithmetic would mean the desktop
+ * and the server could disagree about what a request is worth, silently.
+ *
+ * GPT Image does NOT come through here — that family carries explicit pixel
+ * classes in `GPT_IMAGE_25_SIZES` and an explicit `quality` rung.
+ */
+export function falImageSize(model, aspectRatio, resolution) {
+    const ar = aspectRatio || '16:9';
+    const isSeedream5 = model === 'seedream-5-lite';
+    const res = resolution || (isSeedream5 ? '2k' : '1k');
+    // 1K (~1MP): fal's named presets, or small custom dims where there is none.
+    if (res === '1k') {
+        return FAL_1MP_SIZES[ar] || 'landscape_16_9';
+    }
+    // Seedream 5 Lite: custom dims must be ≥3.69MP (2560×1440) and ≤9.44MP
+    // (3072×3072), so its three rungs target 4 / 7 / 9 MP — all inside that band.
+    if (isSeedream5) {
+        if (res === '4k')
+            return computeFalDimensions(ar, 9);
+        return res === '3k' ? computeFalDimensions(ar, 7) : computeFalDimensions(ar, 4);
+    }
+    if (res === '2k')
+        return computeFalDimensions(ar, 2);
+    return computeFalDimensions(ar, 4);
+}
 /**
  * The provider every AGENT generation actually lands on for Kling and Veo.
  *
@@ -122,14 +221,22 @@ export const AGENT_ROUTE_PROVIDER = 'fal';
 export const MODEL_CAPABILITIES = {
     // ── Image models ───────────────────────────────────────────────────────────
     'nano-banana-2': {
+        imageResolutions: ['1k', '2k', '4k'],
+        // fal's nano-banana-2 schema caps `num_images` at 4 (read 2026-09-09). This
+        // is the ONLY model that batches: the MCP's headless path (no projectId) asks
+        // fal for one batch, and every other route — desktop and agent alike — fires
+        // N separate single-image generations. The proxy bills the batch size.
+        maxBatchImages: 4,
         aspectRatios: FULL_ASPECT_RATIOS,
         maxRefImages: 14,
     },
     'nano-banana-2-lite': {
+        imageResolutions: ['1k'],
         aspectRatios: FULL_ASPECT_RATIOS,
         maxRefImages: 4, // fal edit endpoint caps input images at 4
     },
     'nano-banana-pro': {
+        imageResolutions: ['1k', '2k', '4k'],
         aspectRatios: FULL_ASPECT_RATIOS,
         maxRefImages: 14,
     },
@@ -169,18 +276,22 @@ export const MODEL_CAPABILITIES = {
     // 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': {
+        imageResolutions: ['2k', '3k', '4k'],
         aspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
         maxRefImages: 16,
     },
     'gpt-image-2-5-sunburst': {
+        imageResolutions: ['2k', '3k', '4k'],
         aspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4'],
         maxRefImages: 16,
     },
     'flux-2-max': {
+        imageResolutions: ['1k', '2k', '4k'],
         aspectRatios: FULL_ASPECT_RATIOS,
         maxRefImages: 4,
     },
     'seedream-5-lite': {
+        imageResolutions: ['2k', '3k', '4k'],
         aspectRatios: FULL_ASPECT_RATIOS,
         maxRefImages: 10,
     },
@@ -377,6 +488,9 @@ export const MODEL_CAPABILITIES = {
     // the base row's branch — a different ladder AND a different price at the one
     // tier they share. Every lookup downstream is an exact-id map, not a prefix.
     'minimax-h3': {
+        // fal reference-to-video schema, 2026-09-09: each audio clip is 2-15s.
+        referenceAudioDuration: { min: 2, max: 15 },
+        referenceVideoDuration: { min: 2, max: 15 },
         aspectRatios: MINIMAX_H3_ASPECT_RATIOS,
         // The full ladder. 480p/768p are NATIVE generation modes; 2K and 4K upscale
         // a 768p base result through H3-Regenerate-2K, which is API-only and not in
@@ -408,6 +522,9 @@ export const MODEL_CAPABILITIES = {
         maxReferenceAudioSeconds: 15,
     },
     'minimax-h3-max': {
+        // fal reference-to-video schema, 2026-09-09: each audio clip is 2-15s.
+        referenceAudioDuration: { min: 2, max: 15 },
+        referenceVideoDuration: { min: 2, max: 15 },
         aspectRatios: MINIMAX_H3_ASPECT_RATIOS,
         // 🚨 REFERENCES LANDED 2026-09-09, AFTER A FALSE CLAIM WAS RETIRED. This row
         // shipped from v1.5.5 declaring zero reference capacity because a comment
@@ -431,15 +548,7 @@ export const MODEL_CAPABILITIES = {
         // arms — quoted off this endpoint, not inherited.
         maxReferenceVideoSeconds: 15,
         maxReferenceAudioSeconds: 15,
-        // 1080P IS REAL ON THIS ROW and was missing until 2026-09-09. The schema's
-        // resolution enum is ["480P","768P","1080P"] on all three h3-max endpoints.
-        // 2K/4K genuinely are absent: the H3-Regenerate-2K upscaler is API-only and
-        // is not in the open weights fal self-hosts, which is the actual mechanism
-        // behind the shorter ladder — 1080p was never part of that story.
-        //
-        // DEFAULT stays 768p: it is the tier the model natively generates, and
-        // 1080p is a 2x price step ($0.160/s against $0.080/s).
-        videoResolution: { options: ['480p', '768p', '1080p'], default: '768p' },
+        videoResolution: { options: ['480p', '768p'], default: '768p' },
         duration: { min: 5, max: 15, mode: 'continuous' },
     },
     // ── LTX-2.5 (both seats on fal — added 2026-08-29) ─────────────────────────
@@ -817,4 +926,28 @@ export function describeReferenceImageCaps(models) {
         return n === 0 ? '0 (prompt + source clip only)' : String(n);
     });
 }
+/** H3 Max reference accounting, fal's worked tables read 2026-09-09.
+ * https://fal.ai/models/minimax/h3-max/reference-to-video
+ * 1080p video-reference pricing is unpublished; never infer it from output rates.
+ */
+export const MINIMAX_MAX_REFERENCE = {
+    freeTokens: 4096,
+    imagePixelsPerToken: 1024,
+    normalizedImageEdge: 1024,
+    audioTokensPerSecond: 80,
+    videoTokensPerSecond: { '480p': 2886, '768p': 7459.2 },
+};
+export function minimaxMaxReferenceTokens(input) {
+    const rate = MINIMAX_MAX_REFERENCE.videoTokensPerSecond[input.resolution];
+    if (input.videoSeconds > 0 && rate === undefined) {
+        throw new Error(`H3 Max video-reference pricing is unavailable at ${input.resolution}; choose a priced resolution.`);
+    }
+    for (const n of [input.imagePixels, input.videoSeconds, input.audioSeconds]) {
+        if (!Number.isFinite(n) || n < 0)
+            throw new Error('Reference metadata must be finite and nonnegative');
+    }
+    return Math.max(0, Math.ceil(input.imagePixels / MINIMAX_MAX_REFERENCE.imagePixelsPerToken +
+        input.videoSeconds * (rate ?? 0) + input.audioSeconds * MINIMAX_MAX_REFERENCE.audioTokensPerSecond -
+        MINIMAX_MAX_REFERENCE.freeTokens));
+}
 //# sourceMappingURL=model-capabilities.js.map

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

@@ -14,7 +14,21 @@ export interface ReferenceGroup {
     /** Display + citation name: 'Marcus' | 'the cafe' | 'noir'. Used verbatim. */
     name: string;
     kind: ReferenceKind;
-    /** A group can carry several images for workflows that genuinely need them. */
+    /**
+     * A group can carry several images for workflows that genuinely need them.
+     *
+     * 🚨 A `character` GROUP MAY ALSO CARRY ONE `audio` MEDIUM — that character's
+     * assigned VOICE (2026-09-09). It is the same idea as the identity image, on
+     * the other axis of identity: the mention attaches what the character IS, and
+     * a voice is part of that. The audio takes its number from the audio counter,
+     * so adding one renumbers no image, and it is cited INLINE beside her name
+     * ("Sarah (image 1, voice timbre from audio 1)") rather than as the neutral
+     * `audio-ref` sentence — step 3e holds the receipt for why that is legal.
+     *
+     * A character group with a voice and NO identity image is a real state, not a
+     * defect: `voice-without-photo` is legal on any model that reads audio alone
+     * (Seedance 2.5). It cites no image and the timbre line carries the binding.
+     */
     media: ReferenceMedia[];
     /**
      * What is SAID in this group's reference audio, typed by the user.

package/dist/prompts/reference-composer.js

@@ -37,6 +37,23 @@ function citeImages(nums) {
     const noun = nums.length === 1 ? 'image' : 'images';
     return `${noun} ${joinNums(nums)}`;
 }
+/**
+ * "voice timbre from audio 1" — a character's VOICE, cited inline beside her
+ * name (lowercase, for inline use, exactly like `citeImages`).
+ *
+ * 🚨 THE ROLE WORDS ARE THE LOAD-BEARING HALF, not decoration. A bare
+ * "(image 1, audio 1)" would be the UNROLED state: BytePlus's capability table
+ * gives an audio reference five possible jobs — "music, dialogue, voice, tone,
+ * or timbre" — and an unroled clip falls back to DIALOGUE, so the model
+ * transcribes it and speaks ITS words instead of the prompt's. That is the
+ * shipped defect where a supplied take came back as "a map called Slates" for
+ * "an app called Slates" (2026-08-28). "voice timbre" is the vendor's own
+ * phrase for the half we want: the sound of her, not her words.
+ */
+function citeVoice(nums) {
+    const noun = nums.length === 1 ? 'audio' : 'audios';
+    return `voice timbre from ${noun} ${joinNums(nums)}`;
+}
 function joinNums(nums) {
     if (nums.length === 1)
         return String(nums[0]);
@@ -140,7 +157,12 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
                 videoNums.push(videoNum);
                 orderedVideoPaths.push(m.path);
             }
-            else if (m.mediaKind === 'audio' && g.kind === 'audio-ref') {
+            else if (m.mediaKind === 'audio' && (g.kind === 'audio-ref' || g.kind === 'character')) {
+                // ONE audio counter across hand-attached clips and a CHARACTER'S VOICE,
+                // for the same reason the video counter is shared: the two are the same
+                // numbered space on the wire, and a second counter would emit two
+                // "Audio 1"s the moment a request carried both. Which SENTENCE names
+                // the clip is what differs (step 3 vs step 3e), never the number.
                 audioNum += 1;
                 audioNums.push(audioNum);
                 orderedAudioPaths.push(m.path);
@@ -208,7 +230,30 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
             return ''; // styles never inline — trailing clause only
         if (!seenFirst.has(key)) {
             seenFirst.add(key);
-            return `${g.name} (${citeImages(g.imageNums)})`;
+            // 🚨 ONE BINDING SITE PER ENTITY, CARRYING EVERY MEDIUM SHE OWNS
+            // (2026-09-09). The mention attaches her face AND her voice, so both are
+            // cited where her name appears rather than one inline and the other in a
+            // preamble sentence above the user's own words. That split was the first
+            // shape this shipped in, and it read backwards: a two-speaker prompt made
+            // you hold two name→audio mappings in your head before you reached the
+            // sentence, and a character with a voice and no photo said her name twice
+            // while citing nothing.
+            //
+            // It is also closer to the vendor, not further. BytePlus's binding
+            // example is ONE sentence covering both media — "Image 1 depicts the
+            // protagonist John and uses the voice timbre from Audio 1." — and the
+            // preamble form had already split it in half.
+            //
+            // 🚨 EMPTY MEANS OMITTED, NEVER AN EMPTY PARENTHESIS. A voice-only
+            // character has no `imageNums` and `citeImages([])` would compose the
+            // literal "images " — a citation pointing at nothing, inside the one
+            // function whose whole job is that citations point at what is sent.
+            const cites = [];
+            if (g.imageNums.length > 0)
+                cites.push(citeImages(g.imageNums));
+            if (g.audioNums.length > 0)
+                cites.push(citeVoice(g.audioNums));
+            return cites.length > 0 ? `${g.name} (${cites.join(', ')})` : g.name;
         }
         return g.name;
     });
@@ -239,25 +284,6 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
             topKeys.push(`${noun} ${joinNums(g.videoNums)} ${tail}`);
         }
     }
-    // Reference audio ("Audio 1 is a provided reference."), plus THE WORDS when
-    // the user has typed them — see ReferenceGroup.spokenText for why the words
-    // have to travel as text as well as audio.
-    for (const g of numbered) {
-        if (g.kind === 'audio-ref' && g.audioNums.length > 0) {
-            const noun = g.audioNums.length === 1 ? 'Audio' : 'Audios';
-            const tail = g.audioNums.length === 1 ? 'is a provided reference.' : 'are provided references.';
-            topKeys.push(`${noun} ${joinNums(g.audioNums)} ${tail}`);
-            // Trimmed, never rewritten: the words between the quotes are the user's
-            // exactly as typed. The delimiters are CURLY on purpose — a straight
-            // quote inside the user's own line then sits beside them without
-            // colliding, so nothing has to be escaped and nothing is edited.
-            const spoken = (g.spokenText ?? '').trim();
-            if (spoken) {
-                const lower = g.audioNums.length === 1 ? 'audio' : 'audios';
-                topKeys.push(`The words spoken in ${lower} ${joinNums(g.audioNums)} are exactly: “${spoken}”`);
-            }
-        }
-    }
     // 🚨 A PINNED REFERENCE IMAGE GETS NO KEY LINE, DELIBERATELY (2026-08-10).
     // It used to emit "Image 1 is a provided reference." — the only branch here
     // that assigns NO role, and therefore says nothing: every image in the request
@@ -295,6 +321,104 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
             }
         }
     }
+    // ── Every AUDIO line, in one pass, in audio-NUMBER order ────────────────
+    //
+    // 🚨 AFTER the subject lines, deliberately. A key line that names a subject
+    // ("Image 1 is Marcus.") has to come before a line that gives that subject's
+    // media a job, or the prompt describes a voice before it says whose face it
+    // belongs to. Binding is carried by the SENTENCE rather than by adjacency —
+    // the vendor states that outright — so nothing on the wire depends on this;
+    // what depends on it is whether the composed preview can be read top to
+    // bottom, and that preview is the surface the transparency invariant rests
+    // on.
+    //
+    // 🚨 ONE LOOP OVER THE GROUPS, NOT ONE LOOP PER KIND, AND THAT IS THE WHOLE
+    // POINT OF ITS SHAPE. There are two audio sentences — a hand-attached clip's
+    // neutral "Audio N is a provided reference." and a character's roled
+    // "Sarah uses the voice timbre from Audio N." — and they draw their numbers
+    // from the SAME counter walking THIS list. Emitting them in two passes
+    // printed them in kind order instead of number order, so a request with two
+    // voices and one room-tone clip opened with "Audio 3 is a provided
+    // reference." and named Audio 1 and Audio 2 after it. Nothing was wrong on
+    // the wire — binding is carried by the sentence, not by adjacency, which the
+    // vendor states outright — but a prompt that counts backwards is a prompt
+    // nobody can proofread, and the composed preview is the surface the whole
+    // transparency invariant rests on. One pass over `numbered` IS number order,
+    // because the numbers were assigned by the same walk.
+    for (const g of numbered) {
+        if (g.audioNums.length === 0)
+            continue;
+        const noun = g.audioNums.length === 1 ? 'Audio' : 'Audios';
+        if (g.kind === 'character') {
+            // A CHARACTER'S VOICE. When her token appears in the prompt the binding
+            // rides INLINE on her name (step 2) and there is nothing to say up here.
+            // This is the same duality her IMAGE already has — "Sarah (image 1)"
+            // inline versus "Image 1 is Sarah." when the prompt never names her — so
+            // it is the existing pattern rather than a second grammar.
+            //
+            // Emitted from THIS pass, not from a block of its own, so it keeps its
+            // place in audio-NUMBER order among the neutral lines. See the header.
+            const namedInPrompt = g.token && matchedInPrompt.has(normToken(g.token));
+            if (!namedInPrompt) {
+                topKeys.push(`${g.name} uses the ${citeVoice(g.audioNums)}.`);
+            }
+            continue;
+        }
+        if (g.kind !== 'audio-ref')
+            continue;
+        // A clip the user dragged on declared no role, so it keeps the neutral
+        // line, plus THE WORDS when the user has typed them — see
+        // ReferenceGroup.spokenText for why the words have to travel as text as
+        // well as audio.
+        const tail = g.audioNums.length === 1 ? 'is a provided reference.' : 'are provided references.';
+        topKeys.push(`${noun} ${joinNums(g.audioNums)} ${tail}`);
+        // Trimmed, never rewritten: the words between the quotes are the user's
+        // exactly as typed. The delimiters are CURLY on purpose — a straight
+        // quote inside the user's own line then sits beside them without
+        // colliding, so nothing has to be escaped and nothing is edited.
+        const spoken = (g.spokenText ?? '').trim();
+        if (spoken) {
+            const lower = g.audioNums.length === 1 ? 'audio' : 'audios';
+            topKeys.push(`The words spoken in ${lower} ${joinNums(g.audioNums)} are exactly: “${spoken}”`);
+        }
+    }
+    // ── 3e. WHY A CHARACTER'S VOICE GETS A ROLE AT ALL (2026-09-09) ──────────
+    //
+    // The binding itself is composed INLINE beside her name (step 2), or as a
+    // fallback line in the audio pass above when the prompt never names her.
+    // This is the receipt for why composing a role is legal at all.
+    //
+    // 🚨 AUDIO IS THE ONE MODALITY WHERE THE NEUTRAL LINE UNDER-SPECIFIES, and
+    // this is the sentence that closes it. An image is definitionally a
+    // reference and a video has two possible roles, so both are settled by a
+    // neutral line. An audio attachment has FIVE — BytePlus's own capability
+    // table lists "music, dialogue, voice, tone, or timbre" — so
+    // "Audio 1 is a provided reference." distinguishes a clip from nothing while
+    // leaving four roles open, and an unroled clip falls back to DIALOGUE: the
+    // model re-transcribes it and speaks ITS words. That is the shipped defect
+    // where a supplied take came back as "a map called Slates" for "an app
+    // called Slates" (2026-08-28).
+    //
+    // The wording is the vendor's, not ours. BytePlus's own binding sentence is
+    // "Image 1 depicts the protagonist John and uses the voice timbre from
+    // Audio 1."; MiniMax builds the same primitive into H3's notation
+    // ("<Audio 1> is the voice-timbre reference for <Subject 1>"). Two vendors,
+    // independently. The DIALOGUE therefore comes from the prompt and the clip
+    // carries only the voice — receipts and line refs:
+    // second-brain/business/projects/slates/research/model-prompting-research.md
+    // § 2026-09-09 Multimodal reference GRAMMAR, facts 2 and 3.
+    //
+    // 🚨 IT IS LEGAL COMPOSITION ONLY BECAUSE THE ROLE WAS DECLARED. Assigning a
+    // voice to a character IS the declaration; a clip dragged onto the rail is
+    // not, and keeps the neutral line above. Inferring a role nobody declared
+    // stays forbidden (`slate/.claude/rules/prompt-surface.md`).
+    //
+    // The citation is lowercase (`voice timbre from audio 1`) like every other
+    // inline citation this composer emits. An earlier draft capitalised it to
+    // match the vendor's example verbatim, which left a single capitalised
+    // `Audio 1` sitting mid-sentence among lowercase `image 1`s; moving the
+    // binding inline removed the reason for the exception along with the
+    // exception.
     // ── 4. Style trailing clause (one, at the end — style reads best last) ──
     const styleNums = [];
     for (const g of numbered) {

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

@@ -1,3 +1,4 @@
+import { type GptQuality, type GptBackground } from './model-capabilities.js';
 /**
  * Role an attachment carries in the composer tray. User-set, never inferred.
  *
@@ -62,13 +63,15 @@ export interface ShotParams {
     quality?: string;
     /** 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';
+    gptQuality?: GptQuality;
     /** 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';
+    gptBackground?: GptBackground;
+    /** Character voices explicitly removed from this recipe. */
+    detachedVoiceCharacterIds?: string[];
     duration?: number;
     imageQuantity?: number;
     gridMode?: 'off' | '2x2' | '3x3';

package/dist/prompts/shot-spec.js

@@ -1,22 +1,4 @@
-// The Shot — the prompt bar, serialized.
-//
-// THE PRINCIPLE: a generation's full recipe already exists (the desktop writes
-// `referenceGroups` into every `settings_json`), but only as a byproduct of
-// spending money on it. This module gives that structure a NAME, so it can be
-// listed, forked, agent-authored and restored without loss — before anything
-// has been generated.
-//
-// This is the canonical implementation. It is mirrored byte-for-byte into the
-// desktop app's `slate/src/shared/shotSpec.ts` (the desktop installs the
-// published @slatesvideo/shared from npm and cannot file-import this source, so
-// the mirror carries a header pointing here — the same rule
-// `reference-composer.ts` follows). `slate/scripts/composer-mirror-check.mjs`
-// asserts the two agree; do not invent a second sync mechanism.
-//
-// 🚨 KEEP THIS A DEPENDENCY-FREE LEAF. It imports nothing, in either repo. The
-// desktop's renderer bundles its mirror, the desktop's MAIN process reads it,
-// and the op surface here builds Zod schemas from it — a single `node:` import
-// would break the first of those.
+import { GPT_BACKGROUNDS } from './model-capabilities.js';
 /**
  * Emission ORDER of the ordered roles — the order `buildReferenceGroups` pushes
  * them in, which is the order the composer numbers them in, which is the order
@@ -214,7 +196,10 @@ function readParams(v) {
         raw.gptQuality === 'max') {
         out.gptQuality = raw.gptQuality;
     }
-    if (raw.gptBackground === 'auto' || raw.gptBackground === 'transparent' || raw.gptBackground === 'opaque') {
+    if (Array.isArray(raw.detachedVoiceCharacterIds)) {
+        out.detachedVoiceCharacterIds = strArray(raw.detachedVoiceCharacterIds);
+    }
+    if (GPT_BACKGROUNDS.includes(raw.gptBackground)) {
         out.gptBackground = raw.gptBackground;
     }
     if (raw.gridMode === 'off' || raw.gridMode === '2x2' || raw.gridMode === '3x3')