@slatesvideo/shared 0.6.9 → 0.6.11

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')