@slatesvideo/shared 0.6.1 → 0.6.3

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/index.d.ts

@@ -4,7 +4,9 @@ export { SlatesDesktopClient, type DesktopHealth } from './clients/desktop.js';
 export { SKILLS } from './skills/content.js';
 export * as operations from './operations/index.js';
 export { ALL_OPERATIONS, VIDEO_MODELS, AUDIO_MODELS, defaultContext, type Operation, type OperationContext, type OperationResult } from './operations/index.js';
-export { MODEL_FACTS, getModelFact, multimodalRefSummary, multimodalRefModels, SEEDANCE_TASK_INTENT_WORDS, seedanceTaskIntentWords, type ModelFact, } from './prompts/model-facts.js';
+export { MODEL_FACTS, getModelFact, multimodalRefSummary, multimodalRefModels, describeRouting, SEEDANCE_TASK_INTENT_WORDS, seedanceTaskIntentWords, type ModelFact, } from './prompts/model-facts.js';
 export { MODEL_CAPABILITIES, ALL_ASPECT_RATIOS, AGENT_ROUTE_PROVIDER, getModelCapability, aspectRatiosFor, videoResolutionsFor, defaultVideoResolutionFor, durationsFor, durationValuesFor, aspectRatioUnion, videoResolutionUnion, durationBounds, checkAspectRatio, checkVideoResolution, checkDuration, describeAspectRatios, describeVideoResolutions, describeDurations, describeReferenceImageCaps, type AspectRatio, type VideoResolution, type ModelCapability, type DurationCapability, type VideoResolutionCapability, } from './prompts/model-capabilities.js';
+export { buildAgentDoctrine, type AgentSurface } from './prompts/agent-doctrine.js';
+export { BANNED_PROMPT_TOKENS, describeBannedTokens, findBannedTokens, bannedTokenWarning, type BannedToken, type BannedTokenScope, } from './prompts/banned-tokens.js';
 export { PROMPTING_TIPS, getPromptingTips, type PromptingTipsEntry, type PromptingTipCard, type PromptingTipsKey } from './prompts/prompting-tips.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -8,6 +8,9 @@ export { ALL_OPERATIONS, VIDEO_MODELS, AUDIO_MODELS, defaultContext } from './op
 // prompt derives its MODEL ROUTING doctrine from (kind: image | video | audio,
 // default/premium/niche notes). Edit model-facts.ts, never prose copies.
 export { MODEL_FACTS, getModelFact, multimodalRefSummary, multimodalRefModels, 
+// THE routing renderer — the system prompt, the MCP instructions and the
+// generate ops all call this one function, so routing prose exists once.
+describeRouting, 
 // Mirrored in slate/src/shared/pricing.ts — see the constant's own header for
 // why the mirror exists and why it must never drive a prompt rewrite.
 SEEDANCE_TASK_INTENT_WORDS, seedanceTaskIntentWords, } from './prompts/model-facts.js';
@@ -17,6 +20,29 @@ SEEDANCE_TASK_INTENT_WORDS, seedanceTaskIntentWords, } from './prompts/model-fac
 // the op surface validates against them and GENERATES its `.describe()` prose
 // from them. Never hand-type a capability fact an LLM will read.
 export { MODEL_CAPABILITIES, ALL_ASPECT_RATIOS, AGENT_ROUTE_PROVIDER, getModelCapability, aspectRatiosFor, videoResolutionsFor, defaultVideoResolutionFor, durationsFor, durationValuesFor, aspectRatioUnion, videoResolutionUnion, durationBounds, checkAspectRatio, checkVideoResolution, checkDuration, describeAspectRatios, describeVideoResolutions, describeDurations, describeReferenceImageCaps, } from './prompts/model-capabilities.js';
+// 🚨 AGENT GUIDANCE SSOT — the working method, the hard rules and the guide
+// index, as ONE string both surfaces consume: the desktop Studio Agent's whole
+// system prompt (slate/src/main/studio-agent/context.ts) and the MCP server's
+// `instructions`. Neither may author doctrine prose of its own; the guidance
+// layer drifted for exactly as long as it had no single home.
+//
+// Exported from the ROOT barrel only, never from ./prompts — that subpath is
+// bundled by the desktop RENDERER and must stay small and Node-free, and this
+// module pulls in the whole embedded SKILLS record.
+// Only what a CONSUMER calls. `buildSkillIndex`, `WORKING_METHOD` and
+// `HARD_RULES` are used inside agent-doctrine.ts and by nothing else, so they
+// stay off the public surface — an export nothing calls is an export nothing
+// keeps honest, which is why `buildModelRouting` was deleted rather than left
+// here "in case".
+export { buildAgentDoctrine } from './prompts/agent-doctrine.js';
+// Banned prompt tokens — EXTRACTED from the skills' own never-use lists and
+// inlined into the generate ops' descriptions. Enforcement of "load the guide"
+// that the model cannot skip, because a description is always in context.
+export { 
+// BANNED_PROMPT_TOKENS + describeBannedTokens: the lockstep checker and the
+// ops. findBannedTokens: the eval harness scorer. bannedTokenWarning: the ops.
+// `bannedTokensFor` is internal to the module and stays there.
+BANNED_PROMPT_TOKENS, describeBannedTokens, findBannedTokens, bannedTokenWarning, } from './prompts/banned-tokens.js';
 // Per-model prompting tips — the SSOT for the desktop "See prompting tips"
 // modals. The desktop renders these; it never hand-writes tips content.
 export { PROMPTING_TIPS, getPromptingTips } from './prompts/prompting-tips.js';

package/dist/operations/index.d.ts

@@ -29,7 +29,7 @@ export declare const getCreditBalance: Operation<Record<string, never>>;
 export declare const listAvailableModels: Operation<{
     filter?: string;
 }>;
-export declare const VIDEO_MODELS: readonly ["kling-v3.0-std", "kling-v3.0-pro", "kling-v3.0-omni", "veo-3.1-fast", "veo-3.1-standard", "seedance-2", "seedance-2.5", "omni-flash", "minimax-h3", "minimax-h3-max"];
+export declare const VIDEO_MODELS: readonly ["kling-v3.0-std", "kling-v3.0-pro", "kling-v3.0-omni", "veo-3.1-fast", "veo-3.1-standard", "seedance-2", "seedance-2.5", "omni-flash", "minimax-h3", "minimax-h3-max", "ltx-2-5", "ltx-2-5-pro"];
 type VideoModel = (typeof VIDEO_MODELS)[number];
 /** The exact `model` ids `slates_edit_video` accepts. Edit rows are deliberately
  *  NOT in VIDEO_MODELS — they take a source clip, not frames. */
@@ -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