@slatesvideo/shared 0.6.1 → 0.6.2

package/dist/clients/blender.d.ts

@@ -0,0 +1,50 @@
+export declare const RENDER_TIMEOUT_MS: number;
+/**
+ * Where the add-on comes from, and how to switch it on. ONE string.
+ *
+ * 🚨 IT WAS TWO, AND THAT IS ALWAYS A DRIFT. The op layer had its own
+ * differently-worded copy naming the same URL, so a moved download page or a
+ * renamed panel button would have had to be found in two files by someone who
+ * remembered both existed. Same fact, same sentence, one home.
+ *
+ * `slates.video/blender` is a real page as of 2026-08-28 (`slates-web`
+ * `src/app/blender/page.tsx`), and it is the ONLY thing that tells a stuck user
+ * where the add-on comes from. It is a hard dependency of this string, not a
+ * nice-to-have: keep the path or 301 it.
+ */
+export declare const BLENDER_SETUP_HINT: string;
+export declare class BlenderNotRunningError extends Error {
+    constructor();
+}
+/** Raised when Blender executed the code and Python threw. Carries the traceback. */
+export declare class BlenderExecError extends Error {
+    readonly stdout: string;
+    readonly stderr: string;
+    constructor(message: string, stdout?: string, stderr?: string);
+}
+export declare class BlenderBridgeClient {
+    /**
+     * Execute Python in Blender and return whatever the code assigned to
+     * `result`. `strict_json` is false so a stray Blender object comes back as
+     * its repr instead of failing the whole call — the agent can then correct
+     * itself, which it cannot do if the error is about serialization.
+     */
+    execute(code: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        result: unknown;
+        stdout: string;
+        stderr: string;
+    }>;
+    /**
+     * Execute code with the add-on package bound to `_slates`, so ops can call
+     * the shipped helpers (`_slates.previs`, `_slates.scene`, `_slates.docs`)
+     * instead of re-implementing them as inline Python string blobs.
+     */
+    call(body: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    /** True when a Blender with the add-on is reachable. Never throws. */
+    isReachable(): Promise<boolean>;
+}
+//# sourceMappingURL=blender.d.ts.map

package/dist/clients/blender.js

@@ -0,0 +1,195 @@
+import net from 'node:net';
+// Thin client for the Slates Blender add-on's localhost execution bridge.
+//
+// Wire protocol (matches the add-on's `bridge/server.py`, which is Blender
+// Lab's `blender_mcp` protocol):
+//
+//   -> {"type":"execute","code":"...","strict_json":false}\0
+//   <- {"status":"ok","result":{...},"stdout":"...","stderr":"..."}\0
+//   <- {"status":"error","message":"<traceback>"}\0
+//
+// Requests and responses are NUL-delimited JSON over a plain TCP socket. The
+// add-on executes on Blender's main thread via a timer, so a request is
+// serviced within a tick rather than immediately — the socket stays open until
+// the reply lands, and long jobs (renders) hold it open for as long as they
+// take. That is why the timeout here is generous and configurable per call
+// rather than a single global value.
+const HOST = '127.0.0.1';
+// The add-on binds the first free port in this range, so a second Blender (or
+// a stale process holding 9876) shifts it forward instead of failing. We probe
+// the same range in the same order.
+const BASE_PORT = 9876;
+const PORT_FALLBACKS = 3;
+const DEFAULT_TIMEOUT_MS = 60_000;
+// Renders are the one call that legitimately runs for minutes.
+export const RENDER_TIMEOUT_MS = 15 * 60_000;
+const CONNECT_TIMEOUT_MS = 1_500;
+/**
+ * Where the add-on comes from, and how to switch it on. ONE string.
+ *
+ * 🚨 IT WAS TWO, AND THAT IS ALWAYS A DRIFT. The op layer had its own
+ * differently-worded copy naming the same URL, so a moved download page or a
+ * renamed panel button would have had to be found in two files by someone who
+ * remembered both existed. Same fact, same sentence, one home.
+ *
+ * `slates.video/blender` is a real page as of 2026-08-28 (`slates-web`
+ * `src/app/blender/page.tsx`), and it is the ONLY thing that tells a stuck user
+ * where the add-on comes from. It is a hard dependency of this string, not a
+ * nice-to-have: keep the path or 301 it.
+ */
+export const BLENDER_SETUP_HINT = 'Install the Slates add-on from https://slates.video/blender, then in the 3D ' +
+    'viewport sidebar (press N) open the Slates tab and click Start Bridge.';
+const NOT_RUNNING_MESSAGE = 'No Blender with the Slates add-on is listening on ' +
+    `${HOST}:${BASE_PORT}-${BASE_PORT + PORT_FALLBACKS}. ` +
+    BLENDER_SETUP_HINT;
+export class BlenderNotRunningError extends Error {
+    constructor() {
+        super(NOT_RUNNING_MESSAGE);
+        this.name = 'BlenderNotRunningError';
+    }
+}
+/** Raised when Blender executed the code and Python threw. Carries the traceback. */
+export class BlenderExecError extends Error {
+    stdout;
+    stderr;
+    constructor(message, stdout = '', stderr = '') {
+        super(message);
+        this.name = 'BlenderExecError';
+        this.stdout = stdout;
+        this.stderr = stderr;
+    }
+}
+/**
+ * Resolve the installed add-on package regardless of what Blender named it.
+ *
+ * Extensions are imported as `bl_ext.<repo>.slates_blender`, and the repo
+ * segment depends on where the user installed from — so the name cannot be
+ * hardcoded. Scanning `sys.modules` for the root package is the only stable
+ * handle. Submodules (`...slates_blender.bridge`) do not match the suffix, so
+ * the generator yields exactly the root.
+ */
+const PRELUDE = `
+import sys as _sys
+from importlib import import_module as _import_module
+_slates = next(
+    (m for n, m in list(_sys.modules.items())
+     if n.endswith('slates_blender') and m is not None),
+    None,
+)
+if _slates is None:
+    raise RuntimeError(
+        'The Slates Blender add-on is not loaded in this Blender. '
+        'Enable it in Edit > Preferences > Add-ons.'
+    )
+
+def _mod(_name):
+    """Import a submodule of the add-on by short name.
+
+    The root package only imports \`bridge\` at load time — everything else is
+    lazy so enabling the add-on stays cheap — so \`_slates.previs\` is not
+    reliably an attribute. Go through importlib rather than assuming it is.
+    """
+    return _import_module(_slates.__name__ + '.' + _name)
+`.trim();
+function connect(port) {
+    return new Promise((resolve, reject) => {
+        const socket = new net.Socket();
+        const onError = (err) => {
+            socket.destroy();
+            reject(err);
+        };
+        socket.setTimeout(CONNECT_TIMEOUT_MS, () => onError(new Error('connect timeout')));
+        socket.once('error', onError);
+        socket.connect(port, HOST, () => {
+            socket.setTimeout(0);
+            socket.removeListener('error', onError);
+            resolve(socket);
+        });
+    });
+}
+async function connectAny() {
+    for (let port = BASE_PORT; port <= BASE_PORT + PORT_FALLBACKS; port++) {
+        try {
+            return await connect(port);
+        }
+        catch {
+            // Try the next port in the range.
+        }
+    }
+    throw new BlenderNotRunningError();
+}
+function request(socket, payload, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let buffer = '';
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            fn();
+        };
+        const timer = setTimeout(() => finish(() => reject(new Error(`Blender did not respond within ${Math.round(timeoutMs / 1000)}s. ` +
+            'It may be busy with a modal operator — check the Blender window.'))), timeoutMs);
+        socket.setEncoding('utf8');
+        socket.on('data', (chunk) => {
+            buffer += chunk;
+            const end = buffer.indexOf('\0');
+            if (end === -1)
+                return;
+            const raw = buffer.slice(0, end);
+            finish(() => {
+                try {
+                    resolve(JSON.parse(raw));
+                }
+                catch (err) {
+                    reject(new Error(`Malformed reply from Blender: ${err.message}`));
+                }
+            });
+        });
+        socket.on('error', (err) => finish(() => reject(err)));
+        socket.on('close', () => finish(() => reject(new Error('Blender closed the connection before replying.'))));
+        socket.write(payload + '\0');
+    });
+}
+export class BlenderBridgeClient {
+    /**
+     * Execute Python in Blender and return whatever the code assigned to
+     * `result`. `strict_json` is false so a stray Blender object comes back as
+     * its repr instead of failing the whole call — the agent can then correct
+     * itself, which it cannot do if the error is about serialization.
+     */
+    async execute(code, opts) {
+        const socket = await connectAny();
+        const payload = JSON.stringify({ type: 'execute', code, strict_json: false });
+        const res = await request(socket, payload, opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        const stdout = res.stdout ?? '';
+        const stderr = res.stderr ?? '';
+        if (res.status !== 'ok') {
+            throw new BlenderExecError(res.message ?? 'Blender reported an error', stdout, stderr);
+        }
+        return { result: res.result, stdout, stderr };
+    }
+    /**
+     * Execute code with the add-on package bound to `_slates`, so ops can call
+     * the shipped helpers (`_slates.previs`, `_slates.scene`, `_slates.docs`)
+     * instead of re-implementing them as inline Python string blobs.
+     */
+    async call(body, opts) {
+        const { result } = await this.execute(`${PRELUDE}\n${body}`, opts);
+        return result;
+    }
+    /** True when a Blender with the add-on is reachable. Never throws. */
+    async isReachable() {
+        try {
+            const socket = await connectAny();
+            socket.destroy();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=blender.js.map

package/dist/operations/index.d.ts

@@ -277,6 +277,7 @@ export declare const generateVideo: Operation<{
     videoReferenceAssetIds?: string[];
     videoReferenceSecondsEach?: number[];
     audioReferenceAssetIds?: string[];
+    audioReferenceSpokenText?: string[];
     sound?: boolean;
     audioLanguage?: 'EN' | 'ZH' | 'JA' | 'KO' | 'ES';
     generateMusic?: boolean;
@@ -538,6 +539,29 @@ export declare const deleteFrame: Operation<{
 export declare const getPromptingGuide: Operation<{
     topic: string;
 }>;
+export declare const blenderStatus: Operation<Record<string, never>>;
+export declare const blenderExecute: Operation<{
+    code: string;
+    timeoutSeconds?: number;
+}>;
+export declare const blenderScene: Operation<Record<string, never>>;
+export declare const blenderDocs: Operation<{
+    identifier: string;
+}>;
+export declare const blenderSearchDocs: Operation<{
+    query: string;
+    scope?: 'api' | 'manual';
+    maxResults?: number;
+}>;
+export declare const blenderRenderBlocking: Operation<{
+    projectId?: string;
+    resolutionX?: number;
+    resolutionY?: number;
+    fps?: number;
+    frameStart?: number;
+    frameEnd?: number;
+    basename?: string;
+}>;
 export declare const ALL_OPERATIONS: ReadonlyArray<Operation<unknown>>;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/operations/index.js

@@ -12,6 +12,7 @@
 import { z } from 'zod';
 import { SlatesCloudClient } from '../clients/cloud.js';
 import { SlatesDesktopClient } from '../clients/desktop.js';
+import { BlenderBridgeClient, BLENDER_SETUP_HINT, RENDER_TIMEOUT_MS } from '../clients/blender.js';
 import { SKILLS } from '../skills/content.js';
 // Reference-capacity prose is DERIVED, never hand-typed — root CLAUDE.md:
 // "never hand-type a fact an LLM will read". These helpers read MODEL_FACTS.
@@ -1813,6 +1814,33 @@ function resolveVideoModel(raw) {
     }
     return null;
 }
+/**
+ * Pair each reference-audio asset id with the words spoken in it.
+ *
+ * 🚨 THE MODEL RE-TRANSCRIBES A SUPPLIED TAKE. Seedance does not consume
+ * reference audio verbatim — it re-synthesises something close to it, and a
+ * 2026-08-28 field test heard "an app called Slates" come back as "a map called
+ * Slates". The clip carries the voice, the accent and the timing; only text
+ * carries the words. This is the text, and without it every generation with a
+ * voice take has its line guessed.
+ *
+ * Positional in, KEYED out: the desktop route merges its deprecated singular
+ * `audioReferenceAssetId` onto the END of the plural list, so an index would
+ * address different clips depending on which shape the caller used. Blank
+ * entries are dropped rather than sent as empty strings — a clip with no
+ * speech has no line, which is not the same as a line that is empty.
+ */
+function spokenTextByAssetId(assetIds, spoken) {
+    if (!assetIds?.length || !spoken?.length)
+        return undefined;
+    const out = {};
+    assetIds.forEach((id, i) => {
+        const text = spoken[i]?.trim();
+        if (id && text)
+            out[id] = text;
+    });
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 // Maps a video model id to its bundled prompting skill (frontmatter `name:`),
 // so guidance text points at a skill that actually exists. Deriving the name
 // via model.split('-')[0] produced 'slates-prompting-kling' / '...-veo', which
@@ -1877,6 +1905,7 @@ export const generateVideo = {
         videoReferenceAssetIds: z.array(z.string()).optional().describe(`Reference VIDEOS (UUIDs or badge codes) read alongside the images and audio in the same generation — own-footage restyle, MOTION TRANSFER ("the character from image 1 performs the motion from video 1"), or dialogue conditioning. Cited in the prompt as "video 1", "video 2"… in the order given. ${multimodalRefModels().join(' / ')} only; ignored elsewhere. ${multimodalRefSummary('seedance-2')} ${multimodalRefSummary('seedance-2.5')} Billing switches to combined input+output seconds (the vref key) — pass videoReferenceSecondsEach so the quote is right. If any clip contains a human/AI character, pair with seedanceFace=true (the default Seedance route blocks people). Over the cap is REFUSED, never trimmed: a dropped clip would already have been priced in.`),
         videoReferenceSecondsEach: z.array(z.number()).optional().describe('REQUIRED with videoReferenceAssetIds, same order and length: each reference clip\'s duration in seconds (from the asset listing). Feeds the vref cost key — the bill is Σceil(each) + output seconds. The server re-derives this by probing every uploaded clip, so an understated value just gets corrected upward.'),
         audioReferenceAssetIds: z.array(z.string()).optional().describe(`Reference AUDIO clips (UUIDs or badge codes) read alongside the images and video — e.g. lip-sync a character to a line ("the character in image 1 speaks the dialogue from audio 1"). Cited as "audio 1", "audio 2"… in the order given. No billing surcharge (Seedance audio is included). ${multimodalRefSummary('seedance-2')} ${multimodalRefSummary('seedance-2.5')}`),
+        audioReferenceSpokenText: z.array(z.string()).optional().describe('STRONGLY RECOMMENDED whenever a reference clip contains SPEECH. Same order and length as audioReferenceAssetIds; use "" for a clip with no words (music, ambience, room tone). The model RE-TRANSCRIBES a supplied take rather than using it verbatim — a field test heard "an app called Slates" come back as "a map called Slates" — so the audio decides the VOICE, the ACCENT and the TIMING while only text decides the WORDS. Give the exact line here and it is quoted into the prompt beside the citation. Omit it and the words are a guess. Pairs with the plural audioReferenceAssetIds; the deprecated singular audioReferenceAssetId carries no text.'),
         sound: z.boolean().optional().describe('Kling Omni / Veo / Seedance: enable audio generation. Default true.'),
         audioLanguage: z.enum(['EN', 'ZH', 'JA', 'KO', 'ES']).optional().describe('Kling Omni only — language for dialogue.'),
         generateMusic: z.boolean().optional().describe('Kling Omni only — auto-generate background music.'),
@@ -2033,6 +2062,20 @@ export const generateVideo = {
                     message: `${input.model} takes at most ${maxTotal} reference files across all modalities (you passed ${refImages + refMedia}).`,
                 });
             }
+            // A misaligned spoken-text array would attach one clip's line to another
+            // and send the model the wrong words with nothing on screen to say so.
+            // Refuse rather than truncate: the whole point of the field is that the
+            // WORDS are exact.
+            if (input.audioReferenceSpokenText &&
+                input.audioReferenceSpokenText.length !== (input.audioReferenceAssetIds?.length ?? 0)) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [],
+                    message: `audioReferenceSpokenText must be the same length as audioReferenceAssetIds ` +
+                        `(${input.audioReferenceSpokenText.length} vs ${input.audioReferenceAssetIds?.length ?? 0}) ` +
+                        `— it pairs by position. Use "" for a clip with no speech.`,
+                });
+            }
             // fal: "Audio cannot be the only reference input; provide at least one
             // reference image or video with it."
             const audioRefs = (input.audioReferenceAssetIds?.length ?? 0) + (input.audioReferenceAssetId ? 1 : 0);
@@ -2269,6 +2312,13 @@ export const generateVideo = {
             audioReferenceAssetId: input.audioReferenceAssetId,
             videoReferenceAssetIds: input.videoReferenceAssetIds,
             audioReferenceAssetIds: input.audioReferenceAssetIds,
+            // The route keys this by ASSET ID, not by position, because its own
+            // singular/plural merge appends to the END of the list — an index would
+            // mean different clips depending on which shape the caller used. The op
+            // takes the friendlier positional array and re-keys it here, AFTER
+            // `rids()` has resolved badge codes, so the keys are the ids the route
+            // will resolve. A blank entry is dropped rather than sent as "".
+            audioReferenceSpokenText: spokenTextByAssetId(input.audioReferenceAssetIds, input.audioReferenceSpokenText),
             sound: input.sound,
             audioLanguage: input.audioLanguage,
             generateMusic: input.generateMusic,
@@ -3472,6 +3522,33 @@ function resolveGuideTopic(topic) {
     if (t === 'slates-character-turnaround' || t === 'character-turnaround') {
         return 'slates-character-identity';
     }
+    // ⚠️ Previs aliases sit HIGH, before the model-prefix rules below. `dialogue`
+    // already resolves to the Seed Audio guide, and `style`/`camera` words are a
+    // hair away from the style-prompting and model blocks — anchoring these here
+    // keeps a previs ask out of an audio guide.
+    if (t === 'previs' ||
+        t === 'pre-vis' ||
+        t === 'previz' ||
+        t === 'blocking' ||
+        t === 'blockout' ||
+        t === 'greybox' ||
+        t === 'grey-box' ||
+        t === 'graybox' ||
+        t === 'blender') {
+        return 'slates-previs-blocking';
+    }
+    if (t === 'camera' || t === 'camera-moves' || t === 'camera moves' || t === 'shot-list' || t === 'shot list') {
+        return 'slates-camera-language';
+    }
+    if (t === 'blocking-to-prompt' || t === 'previs-prompt' || t === 'reference-video' || t === 'video-to-video' || t === 'v2v') {
+        return 'slates-blocking-to-prompt';
+    }
+    if (t === 'dialogue-blocking' || t === 'dialogue blocking' || t === '180-rule' || t === 'eyelines' || t === 'seating') {
+        return 'slates-dialogue-blocking';
+    }
+    if (t === 'restyle' || t === 're-style' || t === 'style-swap' || t === 'style swap' || t === 'style-variants') {
+        return 'slates-restyle-from-blocking';
+    }
     if (t === 'model-selection' ||
         t === 'model selection' ||
         t === 'which-model' ||
@@ -3560,7 +3637,7 @@ export const getPromptingGuide = {
         topic: z
             .string()
             .min(1)
-            .describe('Guide name, model id, or style name. Guides: slates-model-selection (which model for which job — read before choosing any model), slates-cost-discipline, slates-content-policy, slates-style-prompting, slates-prompting-nano-banana-2, slates-prompting-veo-3, slates-prompting-kling-v3, slates-prompting-seedance, slates-prompting-seed-audio, slates-prompting-elevenlabs, slates-prompting-lip-sync, slates-prompting-motion-transfer, slates-prompting-flux-2-max, slates-prompting-seedream-5-lite, slates-edit-and-iterate, slates-vision-feedback-loop, slates-character-identity, slates-storyboard-from-script, slates-direct-response-ad, slates-one-prompt-film. Style names (photoreal, anime, painterly, 3d-render) resolve to slates-style-prompting.'),
+            .describe('Guide name, model id, or style name. Guides: slates-model-selection (which model for which job — read before choosing any model), slates-cost-discipline, slates-content-policy, slates-style-prompting, slates-prompting-nano-banana-2, slates-prompting-veo-3, slates-prompting-kling-v3, slates-prompting-seedance, slates-prompting-seed-audio, slates-prompting-elevenlabs, slates-prompting-lip-sync, slates-prompting-motion-transfer, slates-prompting-flux-2-max, slates-prompting-seedream-5-lite, slates-edit-and-iterate, slates-vision-feedback-loop, slates-character-identity, slates-storyboard-from-script, slates-direct-response-ad, slates-one-prompt-film. Blender previs (3D-blocked camera control): slates-previs-blocking (start here), slates-camera-language, slates-blocking-to-prompt, slates-dialogue-blocking, slates-restyle-from-blocking. Style names (photoreal, anime, painterly, 3d-render) resolve to slates-style-prompting.'),
     }),
     async run(input) {
         const resolved = resolveGuideTopic(input.topic);
@@ -3574,6 +3651,159 @@ export const getPromptingGuide = {
         };
     },
 };
+// ── Blender previs ──────────────────────────────────────────────
+//
+// The only ops that talk to a third transport: a localhost socket into a
+// running Blender carrying the Slates add-on. They exist to produce ONE
+// artifact — a grey-box blocking clip whose asset id goes straight into
+// `slates_generate_video`'s `videoReferenceAssetIds`, so the model renders a
+// world around a camera path instead of inventing one.
+//
+// 🚨 There is deliberately no camera-move library here. Camera work is written
+// as `bpy` by the agent through `slates_blender_execute`, against the Blender
+// API reference the add-on ships. A fixed menu of moves would cap the workflow
+// at whatever we thought of; code execution plus real docs does not.
+// The setup sentence and the download URL live in `clients/blender.ts`, beside
+// the port range they belong to — one home, so a moved page is one edit.
+const BLENDER_UNAVAILABLE_HINT = `Blender previs needs the Slates Blender add-on running. ${BLENDER_SETUP_HINT}`;
+export const blenderStatus = {
+    id: 'slates_blender_status',
+    description: 'Check whether a Blender running the Slates add-on is reachable, and if so return its scene summary (timing, camera, collection tree). Call this FIRST in any previs workflow — every other Blender op fails with the same setup message when the bridge is down, and knowing the frame range and fps up front is what keeps the blocking and the prompt timings in agreement.',
+    input: z.object({}),
+    async run() {
+        const client = new BlenderBridgeClient();
+        if (!(await client.isReachable())) {
+            return ok({ connected: false, hint: BLENDER_UNAVAILABLE_HINT });
+        }
+        return ok({ connected: true, scene: await client.call('result = _mod("scene").summary()') });
+    },
+};
+export const blenderExecute = {
+    id: 'slates_blender_execute',
+    description: 'Run Python (`bpy`) inside the connected Blender and return whatever the code assigns to a dict named `result`. This is how blocking gets built: primitives, empties, constraints, camera rigs, keyframes, markers. Anything Blender can do, this can do. Assign a dict to `result` to get data back (e.g. `result = {"camera": cam.name}`); print() output comes back separately as stdout. On an exception you get the full traceback — read it, fix the code, retry. Before writing an unfamiliar call, look up its real signature with slates_blender_docs rather than guessing: the add-on ships the Blender 5.1 API reference precisely so you do not have to recall it.',
+    input: z.object({
+        code: z
+            .string()
+            .min(1)
+            .describe('Python source. Assign a JSON-serialisable dict to `result` to return data.'),
+        timeoutSeconds: z
+            .number()
+            .int()
+            .min(5)
+            .max(900)
+            .optional()
+            .describe('How long to wait for Blender (default 60). Raise it for heavy geometry.'),
+    }),
+    async run(input) {
+        const client = new BlenderBridgeClient();
+        const { result, stdout, stderr } = await client.execute(input.code, {
+            timeoutMs: input.timeoutSeconds ? input.timeoutSeconds * 1000 : undefined,
+        });
+        return ok({ result, ...(stdout ? { stdout } : {}), ...(stderr ? { stderr } : {}) });
+    },
+};
+export const blenderScene = {
+    id: 'slates_blender_scene',
+    description: 'Scene summary from the connected Blender: frame range, fps, duration, render resolution, the active camera with its keyframe times in both frames and seconds, and the full collection/object tree with transforms and constraints. Cheap — call it freely between edits. The camera keyframe times ARE the cut structure, so read them before writing any shot-by-shot prompt.',
+    input: z.object({}),
+    async run() {
+        return ok(await new BlenderBridgeClient().call('result = _mod("scene").summary()'));
+    },
+};
+export const blenderDocs = {
+    id: 'slates_blender_docs',
+    description: 'Look up a dotted Blender Python API identifier in the bundled 5.1 reference — e.g. "bpy.ops.object", "bpy.types.Camera", "bpy.types.FollowPathConstraint". Pass "*" for top-level modules or "bpy.ops.*" to list a namespace. Use this instead of recalling a signature from memory: invented operator names and wrong enum values are the most common way previs code fails, and they fail silently often enough to be worth the lookup.',
+    input: z.object({
+        identifier: z.string().min(1).describe('Dotted identifier, or a namespace wildcard like "bpy.ops.*".'),
+    }),
+    async run(input) {
+        const code = `result = _mod("docs").lookup(${JSON.stringify(input.identifier)})`;
+        return ok(await new BlenderBridgeClient().call(code));
+    },
+};
+export const blenderSearchDocs = {
+    id: 'slates_blender_search_docs',
+    description: 'Full-text search of the bundled Blender documentation for when you do not know the identifier yet. scope "api" searches the Python reference; "manual" searches the user manual for concepts and workflow ("how does Follow Path work", "bezier interpolation handles"). Use slates_blender_docs when you know the name and this when you do not.',
+    input: z.object({
+        query: z.string().min(2),
+        scope: z.enum(['api', 'manual']).optional().describe('Default "api".'),
+        maxResults: z.number().int().min(1).max(20).optional().describe('Default 8.'),
+    }),
+    async run(input) {
+        const args = [
+            JSON.stringify(input.query),
+            JSON.stringify(input.scope ?? 'api'),
+            String(input.maxResults ?? 8),
+        ].join(', ');
+        return ok(await new BlenderBridgeClient().call(`result = _mod("docs").search(${args})`));
+    },
+};
+export const blenderRenderBlocking = {
+    id: 'slates_blender_render_blocking',
+    description: "Render the connected Blender scene camera to a grey-box mp4 — the blocking clip that locks camera motion for generation — and, when projectId is given, import it into that Slates project as a video asset in the same call. The returned asset id goes into slates_generate_video's videoReferenceAssetIds and the returned durationSeconds into videoReferenceSecondsEach. Renders through the SCENE camera using scene render settings, never the user's viewport, so output does not depend on where they left their mouse. Untextured is correct: the clip supplies camera path and timing, the references supply the look. Colour in the blocking is NOTATION, not look — a distinct viewport colour per character is what binds a proxy to its reference image across cuts, and a marked face encodes which way a featureless proxy is facing. State every such mapping in the generation prompt AND state that the colours themselves are not inherited, or the model renders a literally red person. See the slates-previs-blocking and slates-blocking-to-prompt skills. Keep it at or under 30s — seedance-2.5 accepts reference videos up to 30s, the other reference-video models up to 15s.",
+    input: z.object({
+        projectId: z
+            .string()
+            .uuid()
+            .optional()
+            .describe('Import the clip into this project and return its asset. Omit to just get a file path.'),
+        resolutionX: z.number().int().min(256).max(4096).optional().describe('Default 1920.'),
+        resolutionY: z.number().int().min(256).max(4096).optional().describe('Default 1080.'),
+        fps: z.number().int().min(1).max(120).optional().describe('Default 24. Match what the shot list assumes.'),
+        frameStart: z.number().int().optional().describe("Default: the scene's own frame_start."),
+        frameEnd: z.number().int().optional().describe("Default: the scene's own frame_end."),
+        basename: z.string().min(1).max(64).optional().describe('Filename stem. Default "blocking".'),
+    }),
+    async run(input, ctx) {
+        const kwargs = [];
+        if (input.resolutionX !== undefined)
+            kwargs.push(`resolution_x=${input.resolutionX}`);
+        if (input.resolutionY !== undefined)
+            kwargs.push(`resolution_y=${input.resolutionY}`);
+        if (input.fps !== undefined)
+            kwargs.push(`fps=${input.fps}`);
+        if (input.frameStart !== undefined)
+            kwargs.push(`frame_start=${input.frameStart}`);
+        if (input.frameEnd !== undefined)
+            kwargs.push(`frame_end=${input.frameEnd}`);
+        if (input.basename !== undefined)
+            kwargs.push(`basename=${JSON.stringify(input.basename)}`);
+        // 🚨 THE RENDER IS DEFERRED, AND THAT IS WHY THIS IS NOT ONE LINE.
+        // In an interactive Blender `render_blocking` INVOKES the render rather
+        // than executing it — a synchronous animation render driven from the
+        // bridge's own `bpy.app.timers` callback would re-enter the main loop
+        // running it. So it hands back a `check_is_finished` callable instead of
+        // the clip, and assigning that to `check_is_finished` is the bridge's
+        // documented convention for "hold the socket open and answer when the job
+        // lands" (see the add-on's `bridge/deferred.py`). The deferred path wraps
+        // the eventual dict in the SAME `{status, result}` envelope, so everything
+        // downstream of this call is identical either way. Headless Blender has no
+        // job system to poll, renders synchronously, and takes the `else`.
+        const render = (await new BlenderBridgeClient().call(`_previs_result = _mod("previs").render_blocking(${kwargs.join(', ')})\n` +
+            'if callable(_previs_result):\n' +
+            '    check_is_finished = _previs_result\n' +
+            'else:\n' +
+            '    result = _previs_result\n', { timeoutMs: RENDER_TIMEOUT_MS }));
+        if (!input.projectId) {
+            return ok({
+                ...render,
+                next: 'Pass projectId to import this into a Slates project, or call slates_upload_reference_image with type "video".',
+            });
+        }
+        // The same desktop route slates_upload_reference_image uses — the file is
+        // probed on ingest, so duration and dimensions are known immediately.
+        const uploaded = await ctx.desktop().post('/agent/assets/upload', {
+            projectId: input.projectId,
+            filePath: render.filePath,
+            type: 'video',
+        });
+        return ok({
+            ...render,
+            asset: uploaded.asset ?? uploaded,
+            next: "Pass the asset's id in slates_generate_video videoReferenceAssetIds, with videoReferenceSecondsEach set to durationSeconds.",
+        });
+    },
+};
 // ── Aggregation ─────────────────────────────────────────────────
 export const ALL_OPERATIONS = [
     getWorkspaceState,
@@ -3652,5 +3882,18 @@ export const ALL_OPERATIONS = [
     batchUpdateFrames,
     deleteFrame,
     getPromptingGuide,
+    // ── Blender previs, LAST and deliberately ────────────────────────────
+    // This order is not cosmetic: `slate/src/main/studio-agent/ops.ts` maps this
+    // array straight into the Anthropic `tools` array, and that block sits inside
+    // the desktop Studio Agent's PROMPT-CACHED PREFIX. These six landed at the
+    // TOP, which put a third transport nobody without Blender can reach ahead of
+    // `slates_get_workspace_state` in every conversation the app has. They are a
+    // niche lane off the end of the surface, and the list should read that way.
+    blenderStatus,
+    blenderExecute,
+    blenderScene,
+    blenderDocs,
+    blenderSearchDocs,
+    blenderRenderBlocking,
 ];
 //# sourceMappingURL=index.js.map

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

@@ -16,6 +16,24 @@ export interface ReferenceGroup {
     kind: ReferenceKind;
     /** A group can carry several images for workflows that genuinely need them. */
     media: ReferenceMedia[];
+    /**
+     * What is SAID in this group's reference audio, typed by the user.
+     * `audio-ref` groups only; every other kind ignores it.
+     *
+     * 🚨 THE MODEL RE-TRANSCRIBES REFERENCE AUDIO AND GUESSES THE WORDS.
+     * Seedance does not consume a supplied take verbatim — it re-synthesises
+     * something very close to it, and a field test on 2026-08-28 heard "an app
+     * called Slates" come back as "a map called Slates". The audio carries the
+     * voice, the accent and the timing; only TEXT carries the words. Composing
+     * this line is the whole fix, and every user who attached a voice take since
+     * v1.5.2 was exposed to silent mistranscription without it.
+     *
+     * It is USER-AUTHORED and optional. Nothing transcribes the clip and fills
+     * this in: a second model in the request path silently rewriting the prompt
+     * is exactly what the prompt-transparency invariant forbids. An empty value
+     * composes byte-identically to before this field existed.
+     */
+    spokenText?: string;
 }
 export interface ComposedReferences {
     /** The composed prompt: user's words lead, references cited inline as "image N". */
@@ -61,6 +79,45 @@ export interface ComposeOptions {
     startAudioNumber?: number;
 }
 export declare function composeReferences(rawPrompt: string, groups: ReferenceGroup[], opts?: ComposeOptions): ComposedReferences;
+/** One character's voice sample, in the order it is attached. */
+export interface VoiceCitation {
+    /**
+     * The mention this voice answers to — '@sarah', or null when the character
+     * is attached without being mentioned.
+     *
+     * Matched through `normToken`, so '@Big Red', '@big_red' and '@big-red' are
+     * the same token. It is therefore NOT guaranteed byte-equal to what the
+     * prompt authored: the desktop builds it from the character's NAME while the
+     * agent passes the token as typed, and both resolve identically. Do not echo
+     * it back to a user as "what they wrote".
+     */
+    token: string | null;
+    /** 'Sarah' — the character's name, used verbatim. */
+    name: string;
+}
+/**
+ * Translate `@character` mentions into Seed Audio's OWN `@AudioN` notation.
+ *
+ * 🚨 AN ADAPTER, NOT A SECOND COMPOSER — the same relationship
+ * `composeKlingEdit` has to `composeReferences`. Seed Audio does not read
+ * "audio 1"; it reads `@Audio1`-`@Audio3`, and a clip the prompt never cites is
+ * a clip the model ignores. Attaching a voice without citing it would be the
+ * silent-drop failure this repo catalogues by name: attach the reference, get
+ * no error, get no warning, and get a request that does nothing with it.
+ *
+ * It emits the SAME grammar the image composer uses — the first mention
+ * becomes `Sarah (@Audio1)`, later ones stay `Sarah` — so the NAME still
+ * carries the identity and the citation carries the slot. A voice that is
+ * attached but never mentioned gets one short key line instead, exactly as an
+ * unmentioned character's image does.
+ *
+ * Everything else is left as authored: an `@token` that is not one of these
+ * voices is not ours to touch.
+ *
+ * A `null` slot means "this position is a clip the caller cites itself" — it
+ * holds its @AudioN number and is otherwise ignored.
+ */
+export declare function composeVoiceCitations(rawPrompt: string, voices: Array<VoiceCitation | null>): string;
 export interface KlingEditElement {
     /** Frontal image path/URL (element primary view) */
     frontal: string;