@slatesvideo/shared 0.6.0 → 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.
@@ -294,7 +295,7 @@ export const estimateGenerationCost = {
         sound: z.boolean().optional().describe('Veo only — audio flag changes the cost key.'),
         seedanceFace: z.boolean().optional().describe('Seedance AI-face route (pricier key).'),
         seedanceRealFace: z.boolean().optional().describe('Seedance consented real-face route (premium key).'),
-        referenceImages: z.number().int().min(0).optional().describe(`minimax-h3 only — how many reference IMAGES the generation will carry. The first ${MINIMAX_FREE_REF_IMAGES} are free and each one after that is a paid dimension of the cost key, so a quote that omits this UNDER-REPORTS a reference-heavy job. Ignored by every other model (minimax-h3-max takes no references at all).`),
+        referenceImages: z.number().int().min(0).optional().describe(`minimax-h3 only — how many reference IMAGES the generation will carry. The first ${MINIMAX_FREE_REF_IMAGES} are free and each one after that is a paid dimension of the cost key, so a quote that omits this UNDER-REPORTS a reference-heavy job. Ignored by every other model — including minimax-h3-max, which has no reference endpoint (its start/end frames are free and are not reference images).`),
     }),
     async run(input, ctx) {
         const registry = await ctx.cloud().get('/api/agent/models');
@@ -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
@@ -1848,7 +1876,7 @@ export const generateVideo = {
         // "seedance-2.5 480p/720p" were both stated here AND there, and the two
         // copies disagreed — and the second of those went stale on 2026-08-24 when
         // 2.5 gained 1080p, which is exactly the failure mode generating it fixes.
-        model: z.string().describe(`One of: ${VIDEO_MODELS.join(' | ')}. Pass the BASE id — duration and videoResolution are separate params (registry cost keys like "kling-v3-standard-8s" auto-resolve). Route per the slates-model-selection skill: Kling std = general-purpose DEFAULT, Seedance 2 = premium physics/effects/hero tier, seedance-2.5 = a SECOND SEAT beside it (longer takes, far more references, audio-only refs — but no 4K, and dearer than seedance-2 at every shared resolution, so stay on seedance-2 unless length or reference count is the point), Veo = native-synced-audio niche only, never the default, omni-flash = cheap tier with audio included (t2v, single-start-frame i2v, or reference images; no last frame, no video/audio refs), minimax-h3 = the AUTHORED-AUDIO seat (dialogue, scene sound and score directed as three separate layers in one pass, plus declared reference relationships; reference images past the fifth are a PAID key dimension — pass referenceImages when quoting), minimax-h3-max = the same model post-trained by fal for SPEED, capped at 768p, no references of any kind, and DEARER than minimax-h3 at the tier they share — a deliberate pick, never a default and never the cheap H3. All are VIDEO-only. Each model's legal aspect ratios, durations and resolutions are in those params' own descriptions — read them there, not from memory. For per-call cost, call slates_estimate_generation_cost.`),
+        model: z.string().describe(`One of: ${VIDEO_MODELS.join(' | ')}. Pass the BASE id — duration and videoResolution are separate params (registry cost keys like "kling-v3-standard-8s" auto-resolve). Route per the slates-model-selection skill: Kling std = general-purpose DEFAULT, Seedance 2 = premium physics/effects/hero tier, seedance-2.5 = a SECOND SEAT beside it (longer takes, far more references, audio-only refs — but no 4K, and dearer than seedance-2 at every shared resolution, so stay on seedance-2 unless length or reference count is the point), Veo = native-synced-audio niche only, never the default, omni-flash = cheap tier with audio included (t2v, single-start-frame i2v, or reference images; no last frame, no video/audio refs), minimax-h3 = the AUTHORED-AUDIO seat (dialogue, scene sound and score directed as three separate layers in one pass, plus declared reference relationships; reference images past the fifth are a PAID key dimension — pass referenceImages when quoting), minimax-h3-max = the same model post-trained by fal for SPEED, capped at 768p, and DEARER than minimax-h3 at the tier they share — a deliberate pick, never a default and never the cheap H3; it still takes firstFrameAssetId/lastFrameAssetId, but has no reference endpoint, so the reference set is minimax-h3 only. All are VIDEO-only. Each model's legal aspect ratios, durations and resolutions are in those params' own descriptions — read them there, not from memory. For per-call cost, call slates_estimate_generation_cost.`),
         projectId: z.string().uuid().optional().describe('Save into this Slates project. Strongly recommended — the desktop UI shows a progress card live and the asset appears when complete.'),
         // 🚨 THESE THREE DESCRIPTIONS ARE GENERATED FROM `MODEL_CAPABILITIES`.
         // Never hand-write a ratio, resolution or duration into them again — every
@@ -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/model-facts.js

@@ -235,7 +235,7 @@ export const MODEL_FACTS = [
         // No reference caps: fal publishes no reference-to-video endpoint for this
         // row, so `caps()` returns nulls and the composer refuses references.
         ...caps('minimax-h3-max'),
-        notes: 'THE SPEED SEAT, and the EXPENSIVE one at the tier they share — never the cheap H3 and never the default. fal\'s own post-train of the open H3 weights, self-hosted. 🚨 MEASURED 2026-08-27, same prompt and params on both rows: a 5s 768p text-to-video took **4.8 seconds** on Max against **57 seconds** on base H3 — **about 12x faster**, queue to finished file. That is the seat\'s whole case and it is now our own number, not fal\'s (fal claims under 3s; the literal claim did not hold at 4.8s wall-clock, the order of magnitude did). It also carries a thin quality edge on the with-audio Arena boards (1,204 vs 1,184 image-to-video, 1,235 vs 1,226 text-to-video — real, but 20 and 9 ELO, and vendor-reported). It gives up everything above 768p (no 2K, no 4K — the upscaler is not in the open weights) and takes NO references of any kind (no reference-to-video endpoint exists). It costs $0.080/s at 768p against base H3\'s $0.060/s: 33% more for a shorter ladder. So route here when a fast turnaround on a 480p/768p text-to-video or start-frame shot is worth the premium, and to base H3 for resolution, references, or the same tier cheaper. Same native audio, same 5-15s window, same six aspect ratios.',
+        notes: 'THE SPEED SEAT, and the EXPENSIVE one at the tier they share — never the cheap H3 and never the default. fal\'s own post-train of the open H3 weights, self-hosted. 🚨 MEASURED 2026-08-27, same prompt and params on both rows: a 5s 768p text-to-video took **4.8 seconds** on Max against **57 seconds** on base H3 — **about 12x faster**, queue to finished file. That is the seat\'s whole case and it is now our own number, not fal\'s (fal claims under 3s; the literal claim did not hold at 4.8s wall-clock, the order of magnitude did). It also carries a thin quality edge on the with-audio Arena boards (1,204 vs 1,184 image-to-video, 1,235 vs 1,226 text-to-video — real, but 20 and 9 ELO, and vendor-reported). It gives up everything above 768p (no 2K, no 4K — the upscaler is not in the open weights). 🚨 FRAMES ARE UNAFFECTED — it takes a start frame and an end frame exactly like base H3, on `minimax/h3-max/image-to-video`, which is the route the image-to-video Arena score above is measured on. What it lacks is the REFERENCE endpoint (`minimax/h3-max/reference-to-video` 404s), so the omni-reference set — up to 9 identity/style/environment images plus reference video and audio — is base-H3 only. Never describe this row as taking no image input: an image-to-video shot is one of the two things it is FOR. It costs $0.080/s at 768p against base H3\'s $0.060/s: 33% more for a shorter ladder. So route here when a fast turnaround on a 480p/768p text-to-video or start-frame shot is worth the premium, and to base H3 for resolution, references, or the same tier cheaper. Same native audio, same 5-15s window, same six aspect ratios.',
     },
     {
         id: 'seed-audio',

package/dist/prompts/prompting-tips.js

@@ -583,7 +583,7 @@ const MINIMAX_H3 = {
     label: 'MiniMax H3',
     intro: [
         'MiniMax H3 generates picture and sound in one pass — 24fps, 32kHz stereo, 5-15 seconds, 11 stably-supported languages. It is the only video model in Slates where audio is AUTHORED rather than switched on: synchronised dialogue and action sounds go in the body of the prompt, ambience goes in a soundscape section, and audience-only music goes in a score section. Put a sound in the wrong section and it is dropped, doubled, or attributed to the wrong source.',
-        'Two seats. Base H3 runs 480p / 768p / 2K / 4K and reads up to 9 reference images plus 3 video and 3 audio clips. H3 Max is fal\'s faster post-train: 768p ceiling, no references at all, and dearer than base H3 at 768p — a deliberate speed pick, never the cheap one. 768p is the default on both because it is the tier the model natively generates; 2K and 4K are upscales of a 768p base.',
+        'Two seats. Base H3 runs 480p / 768p / 2K / 4K and reads up to 9 reference images plus 3 video and 3 audio clips. H3 Max is fal\'s faster post-train: 768p ceiling, and dearer than base H3 at 768p — a deliberate speed pick, never the cheap one. It still animates a start frame and an end frame; what it does not have is the reference set (the extra identity, style, environment, video and audio references), which is base-H3 only. 768p is the default on both because it is the tier the model natively generates; 2K and 4K are upscales of a 768p base.',
     ],
     columns: [
         [