@slatesvideo/shared 0.5.5 → 0.5.7

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

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

package/dist/prompts/reference-composer.js

@@ -56,17 +56,28 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
     // ── 1. Assign global numbers by walking the list in order ──
     let imageNum = opts.startImageNumber ?? 0;
     let videoNum = opts.startVideoNumber ?? 0;
+    let audioNum = opts.startAudioNumber ?? 0;
     const orderedImagePaths = [];
     const orderedVideoPaths = [];
+    const orderedAudioPaths = [];
     const numbered = groups.map((g) => {
         const imageNums = [];
         const videoNums = [];
+        const audioNums = [];
         for (const m of g.media) {
-            if (m.mediaKind === 'video' && g.kind === 'video') {
+            // ONE video counter across the edit source and reference clips. They are
+            // mutually exclusive in practice, and a shared counter means a mixed
+            // state degrades to wrong-but-unambiguous rather than two "Video 1"s.
+            if (m.mediaKind === 'video' && (g.kind === 'video' || g.kind === 'video-ref')) {
                 videoNum += 1;
                 videoNums.push(videoNum);
                 orderedVideoPaths.push(m.path);
             }
+            else if (m.mediaKind === 'audio' && g.kind === 'audio-ref') {
+                audioNum += 1;
+                audioNums.push(audioNum);
+                orderedAudioPaths.push(m.path);
+            }
             else if (m.mediaKind === 'image' && isFreeRefImageKind(g.kind)) {
                 imageNum += 1;
                 imageNums.push(imageNum);
@@ -74,7 +85,7 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
             }
             // first-frame / last-frame media: not numbered, not in the free-ref pool.
         }
-        return { ...g, imageNums, videoNums };
+        return { ...g, imageNums, videoNums, audioNums };
     });
     // ── 2. Inline-name token groups in the prompt body ──
     // For each character/environment group whose token appears in the prompt, the
@@ -87,21 +98,40 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
         byNorm.set(normToken(g.token), g);
     const seenFirst = new Set();
     const matchedInPrompt = new Set();
+    // Every token that named nothing, recorded as authored and deduped by the
+    // same normalisation used for matching. This is what makes the deletion
+    // below reportable instead of silent — see ComposedReferences.unresolvedTokens.
+    const unresolvedTokens = [];
+    const unresolvedSeen = new Set();
+    const noteUnresolved = (sigil, tok) => {
+        const key = normToken(`${sigil}${tok}`);
+        if (unresolvedSeen.has(key))
+            return;
+        unresolvedSeen.add(key);
+        unresolvedTokens.push(`${sigil}${tok}`);
+    };
     // First strip "in/with the style of #tag" phrases so the style reads as a
-    // clean trailing clause, not a dangling preposition (legacy cleanPrompt behaviour).
-    let body = rawPrompt.replace(/\s+(with|in)\s+the\s+style\s+of\s+([@#])([\w-]+)/gi, (full, _prep, sigil, tok) => {
+    // clean trailing clause, not a dangling preposition (legacy cleanPrompt
+    // behaviour). An UNRESOLVED token in that phrase is stripped too: leaving the
+    // preposition behind ("…a portrait in the style of") was the worse half of the
+    // silent edit — the tag vanished a step later anyway and the sentence was left
+    // broken. Stripped or not, the token is reported.
+    let body = rawPrompt.replace(/\s+(with|in)\s+the\s+style\s+of\s+([@#])([\w-]+)/gi, (_full, _prep, sigil, tok) => {
         const g = byNorm.get(normToken(`${sigil}${tok}`));
         if (g && g.kind === 'style') {
             matchedInPrompt.add(normToken(`${sigil}${tok}`));
             return '';
         }
-        return full;
+        noteUnresolved(sigil, tok);
+        return '';
     });
     body = body.replace(/([@#])([\w-]+)/g, (_full, _sigil, tok) => {
         const key = normToken(`${_sigil}${tok}`);
         const g = byNorm.get(key);
         if (!g) {
             // Unresolved token. A #unknown vanishes; an @unknown humanizes to words.
+            // Both are edits the user never asked for, so both are reported.
+            noteUnresolved(_sigil, tok);
             return _sigil === '#' ? '' : humanizeToken(tok);
         }
         matchedInPrompt.add(key);
@@ -128,14 +158,52 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
             topKeys.push(`${noun} ${joinNums(g.videoNums)} ${verb} the motion source.`);
         }
     }
-    // Pinned/base references ("Image 1 is a provided reference.").
+    // Reference clips ("Video 2 is a provided reference."). This line SURVIVES
+    // the 2026-08-10 cull of null-role key lines because it is not one: the
+    // "motion source" wording above belongs to the edit path alone, so a video
+    // attachment has two possible roles and the sentence says which. The pinned
+    // IMAGE line had no such contrast partner and was deleted (see step 3).
+    for (const g of numbered) {
+        if (g.kind === 'video-ref' && g.videoNums.length > 0) {
+            const noun = g.videoNums.length === 1 ? 'Video' : 'Videos';
+            const tail = g.videoNums.length === 1 ? 'is a provided reference.' : 'are provided references.';
+            topKeys.push(`${noun} ${joinNums(g.videoNums)} ${tail}`);
+        }
+    }
+    // Reference audio ("Audio 1 is a provided reference.").
     for (const g of numbered) {
-        if (g.kind === 'pinned' && g.imageNums.length > 0) {
-            const noun = g.imageNums.length === 1 ? 'Image' : 'Images';
-            const tail = g.imageNums.length === 1 ? 'is a provided reference.' : 'are provided references.';
-            topKeys.push(`${noun} ${joinNums(g.imageNums)} ${tail}`);
+        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}`);
         }
     }
+    // 🚨 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
+    // IS a provided reference, so the sentence restated the transport. Its
+    // siblings all carry information — "is the motion source" contrasts with a
+    // reference clip, "is the subject" / "is Marcus" name the thing, the style
+    // clause assigns a job. This one was the null member of that set, and unlike
+    // video there is no competing numbered image role for it to disambiguate
+    // against (frames ride dedicated slots and are never numbered).
+    //
+    // It was also actively wrong for the case pinned-first exists to serve: the
+    // desktop's `referenceGroups.ts` orders these images FIRST for the
+    // edit/injection case (the movie still you paint over reads as image 1) —
+    // where image 1 is the CANVAS, not a reference, and the line asserted the
+    // opposite.
+    //
+    // Every vendor assigns roles inline in natural language instead. Google's own
+    // multi-reference example is "the attached napkin sketch as the structure and
+    // the attached fabric sample as the texture"; ByteDance's is "use @Image 2 as
+    // the dormitory scene style reference". Nobody declares a null role. Our own
+    // skills say the same thing: "the model does NOT infer a reference's role from
+    // its position; the NAME carries it" — and this line had no name to carry.
+    //
+    // Do not add it back. Attaching an image already means "here is an image"; if
+    // a reference needs a role, it gets one from a role badge or from the user's
+    // own words, both of which compose into real sentences above.
     // Token-less or not-in-prompt subjects/environments ("Image 1 is Marcus.").
     for (const g of numbered) {
         if ((g.kind === 'character' || g.kind === 'environment') && g.imageNums.length > 0) {
@@ -169,6 +237,8 @@ export function composeReferences(rawPrompt, groups, opts = {}) {
         prompt: parts.join('\n\n'),
         orderedImagePaths,
         orderedVideoPaths,
+        orderedAudioPaths,
+        unresolvedTokens,
     };
 }
 /** fal cap: max 4 combined element + style-image references per edit request. */

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

@@ -20,8 +20,25 @@ export declare const IDENTITY_LIGHTING = "flat, even, shadowless lighting";
  * crushes hair and wardrobe silhouettes.** A deep neutral grey holds both.
  */
 export declare const IDENTITY_PLATE_HEX = "#3a3a3c";
-export declare const IDENTITY_BACKGROUND = "a plain, deep neutral-grey background (#3a3a3c)";
-export declare const IDENTITY_LIGHTING_CLAUSE = "Render on a plain, deep neutral-grey background (#3a3a3c) with flat, even, shadowless lighting so the sheet captures the character's identity, not scene lighting.";
+/**
+ * 🚨 THE HEX IS EMITTED WITHOUT ITS `#` AND THAT IS LOAD-BEARING (2026-07-30).
+ *
+ * `#` is a REFERENCE-TOKEN SIGIL in the desktop's prompt composer
+ * (`slate/src/shared/promptComposition.ts` — `/([@#])([\w-]+)/g`), and an
+ * unresolved `#token` is SILENTLY DELETED. So `#3a3a3c` never survived to any
+ * model: fal echoed back `deep neutral-grey background ()` on a real 2026-07-30
+ * request. The plate value has been doing nothing since the composer shipped.
+ *
+ * Writing it bare keeps the value in the prompt. `IDENTITY_PLATE_HEX` keeps its
+ * `#` because it is a colour constant and may have non-prompt consumers.
+ *
+ * GENERAL RULE FOR THIS FILE: never emit `#` or `@` into prompt text. Both are
+ * sigils downstream and both mangle silently — no error, no log, just missing
+ * words. HOW YOU'D KNOW THIS IS BEATEN: the composer stops treating bare
+ * `#hex` as a token, or starts leaving unresolved tokens intact.
+ */
+export declare const IDENTITY_BACKGROUND: string;
+export declare const IDENTITY_LIGHTING_CLAUSE: string;
 /**
  * Craft clauses every identity reference wants — the eye and skin detail that
  * survives downstream, plus the two "reads literally" guards. Crushed-black

package/dist/prompts/reference-rules.js

@@ -96,7 +96,24 @@ export const IDENTITY_LIGHTING = 'flat, even, shadowless lighting';
  * crushes hair and wardrobe silhouettes.** A deep neutral grey holds both.
  */
 export const IDENTITY_PLATE_HEX = '#3a3a3c';
-export const IDENTITY_BACKGROUND = `a plain, deep neutral-grey background (${IDENTITY_PLATE_HEX})`;
+/**
+ * 🚨 THE HEX IS EMITTED WITHOUT ITS `#` AND THAT IS LOAD-BEARING (2026-07-30).
+ *
+ * `#` is a REFERENCE-TOKEN SIGIL in the desktop's prompt composer
+ * (`slate/src/shared/promptComposition.ts` — `/([@#])([\w-]+)/g`), and an
+ * unresolved `#token` is SILENTLY DELETED. So `#3a3a3c` never survived to any
+ * model: fal echoed back `deep neutral-grey background ()` on a real 2026-07-30
+ * request. The plate value has been doing nothing since the composer shipped.
+ *
+ * Writing it bare keeps the value in the prompt. `IDENTITY_PLATE_HEX` keeps its
+ * `#` because it is a colour constant and may have non-prompt consumers.
+ *
+ * GENERAL RULE FOR THIS FILE: never emit `#` or `@` into prompt text. Both are
+ * sigils downstream and both mangle silently — no error, no log, just missing
+ * words. HOW YOU'D KNOW THIS IS BEATEN: the composer stops treating bare
+ * `#hex` as a token, or starts leaving unresolved tokens intact.
+ */
+export const IDENTITY_BACKGROUND = `a plain, deep neutral-grey background (hex ${IDENTITY_PLATE_HEX.replace('#', '')})`;
 export const IDENTITY_LIGHTING_CLAUSE = `Render on ${IDENTITY_BACKGROUND} with ${IDENTITY_LIGHTING} so the sheet captures the character's identity, not scene lighting.`;
 /**
  * Craft clauses every identity reference wants — the eye and skin detail that