keyshot-mcp 0.2.1 → 0.4.2

package/README.md

@@ -61,26 +61,58 @@ This project does not include KeyShot, does not bypass licensing, and does not s
 
 ## Install
 
+### Install the published npm package
+
+```bash
+npm install -g keyshot-mcp
+```
+
+The current release line is `0.4.2`. The published package is the easiest option
+when you only want to use the MCP server. You still need KeyShot Studio and a
+local KeyShot license.
+
+### Install from source
+
 ```bash
 npm install
 npm run build
 ```
 
+### Three MCP configuration options
+
+Use exactly one of these approaches:
+
+**Global npm installation** (`npm install -g keyshot-mcp`):
+
+```json
+{"mcpServers":{"keyshot":{"command":"keyshot-mcp","env":{"KEYSHOT_HEADLESS_EXE":"/absolute/path/to/keyshot_headless"}}}}
+```
+
+**No installation, run with npx**:
+
+```json
+{"mcpServers":{"keyshot":{"command":"npx","args":["-y","keyshot-mcp@0.4.2"],"env":{"KEYSHOT_HEADLESS_EXE":"/absolute/path/to/keyshot_headless"}}}}
+```
+
+**Run from a cloned source directory** (after `npm install && npm run build`):
+
+```json
+{"mcpServers":{"keyshot":{"command":"node","args":["/absolute/path/to/keyshot-mcp/dist/index.js"],"env":{"KEYSHOT_HEADLESS_EXE":"/absolute/path/to/keyshot_headless"}}}}
+```
+
 ## Copy-Paste Setup Prompt for an Agent
 
 If you use Codex or another coding agent, you can copy this prompt and let the agent install the MCP server for you:
 
 ```text
-Install the KeyShot MCP server from https://github.com/truman-t3/keyshot-mcp.
+Install KeyShot MCP 0.4.2 from npm and configure it in my MCP client.
 
 Please:
-1. Clone the repository or use my local copy if it already exists.
-2. Run npm install and npm run build.
-3. Find my KeyShot headless executable path.
-4. Add a keyshot MCP server entry to my MCP client configuration.
-5. Set KEYSHOT_HEADLESS_EXE to the detected keyshot_headless path.
-6. Test the setup by running the keyshot_status tool.
-7. Tell me the exact config that was added and whether the status check passed.
+1. Find my KeyShot headless executable path.
+2. Add a keyshot MCP server using npx -y keyshot-mcp@0.4.2.
+3. Set KEYSHOT_HEADLESS_EXE to the detected keyshot_headless path.
+4. Test the setup by running the keyshot_status tool.
+5. Tell me the exact config that was added and whether the status check passed.
 
 Do not store license keys or account passwords. Use my existing local KeyShot license configuration.
 ```
@@ -165,25 +197,58 @@ Import the model file at /path/to/model.step, apply a brushed metal material to
 Inspect this KeyShot scene and summarize the available objects, cameras, materials, and renderable outputs.
 ```
 
+```text
+List the cameras in this KeyShot scene, create or update a camera named "Hero",
+save the scene to a new file, and render one preview from that camera.
+```
+
 ## Environment Variables
 
 - `KEYSHOT_HEADLESS_EXE`: path to `keyshot_headless` or `keyshot_headless.exe`.
 - `KEYSHOT_OUTPUT_DIR`: default output folder for renders.
 - `KEYSHOT_LICENSE_ARGS`: optional KeyShot headless license arguments. Empty by default.
 - `KEYSHOT_TIMEOUT_MS`: operation timeout in milliseconds. Default: `600000`.
+- `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS`: allow output paths outside `KEYSHOT_OUTPUT_DIR`. Default: `false`.
+
+By default every output file must stay inside `KEYSHOT_OUTPUT_DIR`. Relative paths
+are placed there automatically. Set the compatibility switch to `true` only when
+an external output location is intentional; input scenes and models are unrestricted.
+
+`samples` and `maxTimeSeconds` select different KeyShot render modes. Provide one
+or the other, not both.
 
 ## MCP Tools
 
 - `keyshot_status`
 - `keyshot_inspect_scene`
+- `keyshot_list_cameras`: list available camera names in a scene (handy before batch rendering)
 - `keyshot_render`: render a single image
 - `keyshot_batch_render`
+- `keyshot_render_queue`: run several render jobs sequentially (stops at first failure unless `continueOnError`)
 - `keyshot_import_model`
 - `keyshot_apply_material`
+- `keyshot_list_material_presets`: list presets from the material preset library
+- `keyshot_apply_material_preset`: apply a named preset from the library to an object
 - `keyshot_set_camera`
 - `keyshot_set_environment`
 - `keyshot_save_scene`
 
+### Material preset library
+
+`keyshot_apply_material_preset` reads a small JSON registry so you can reuse named
+looks instead of remembering exact KeyShot material names. Default location:
+`presets/materials.json` (override with the `KEYSHOT_MATERIAL_PRESETS` env var).
+
+```json
+{
+  "Brushed Steel": { "materialName": "Steel Brushed", "description": "metal parts" },
+  "Clear Glass": { "materialPath": "C:/materials/glass_clear.mtl" }
+}
+```
+
+Each preset must have a `materialName` or a `materialPath`. Use
+`keyshot_list_material_presets` to see what is available.
+
 ## MCP Prompts and Resources
 
 - Prompt: `keyshot_product_render`
@@ -205,13 +270,24 @@ KeyShot's Python `lux` API changes across versions. This server keeps the MCP in
 ## Roadmap
 
 - [ ] Auto-discover and batch render all cameras in a scene
-- [ ] Material preset library
+- [x] Material preset library
 - [ ] Camera preset templates
-- [ ] Render queue status
-- [ ] Safer output directory restrictions
+- [x] Sequential render queue
+- [x] Safer output directory restrictions
 - [ ] More tested KeyShot versions
 - [ ] macOS compatibility verification
-- [ ] Claude Desktop / Cursor / Codex config examples
+- [x] Claude Desktop / Cursor / Codex config examples
+
+## Real KeyShot demo
+
+![KeyShot MCP generated cube demo](assets/demo/keyshot-mcp-demo.png)
+
+The demo uses only the generated geometry in `examples/demo`. To reproduce the
+status, import, inspect, camera, save, and PNG-render workflow locally:
+
+```bash
+npm run smoke:keyshot
+```
 
 ## License
 
@@ -278,26 +354,57 @@ MIT
 
 ## 安装
 
+### 安装已发布的 npm 包
+
+```bash
+npm install -g keyshot-mcp
+```
+
+当前发布版本为 `0.4.2`。如果你只是想使用 MCP 服务，直接安装 npm 包最简单。
+电脑仍需要安装 KeyShot Studio，并且已经配置好本地 KeyShot 授权。
+
+### 从源码安装
+
 ```bash
 npm install
 npm run build
 ```
 
+### 三种独立配置方式
+
+下面三种方式选择一种即可：
+
+**全局 npm 安装**（先运行 `npm install -g keyshot-mcp`）：
+
+```json
+{"mcpServers":{"keyshot":{"command":"keyshot-mcp","env":{"KEYSHOT_HEADLESS_EXE":"C:/KeyShot/bin/keyshot_headless.exe"}}}}
+```
+
+**免安装，直接使用 npx**：
+
+```json
+{"mcpServers":{"keyshot":{"command":"npx","args":["-y","keyshot-mcp@0.4.2"],"env":{"KEYSHOT_HEADLESS_EXE":"C:/KeyShot/bin/keyshot_headless.exe"}}}}
+```
+
+**使用本地源码**（先运行 `npm install && npm run build`）：
+
+```json
+{"mcpServers":{"keyshot":{"command":"node","args":["C:/path/to/keyshot-mcp/dist/index.js"],"env":{"KEYSHOT_HEADLESS_EXE":"C:/KeyShot/bin/keyshot_headless.exe"}}}}
+```
+
 ## 复制给 Agent 的安装提示词
 
 如果你使用 Codex 或其他编程 Agent，可以复制下面这段话，让 Agent 帮你安装和配置 MCP：
 
 ```text
-请帮我安装 KeyShot MCP Server：https://github.com/truman-t3/keyshot-mcp。
+请帮我安装 KeyShot MCP 0.4.2，并添加到我的 MCP 客户端。
 
 请你：
-1. 克隆这个仓库；如果本地已有，就使用本地版本。
-2. 运行 npm install 和 npm run build。
-3. 查找我电脑上的 KeyShot headless 可执行文件路径。
-4. 把 keyshot MCP server 添加到我的 MCP 客户端配置里。
-5. 把 KEYSHOT_HEADLESS_EXE 设置为检测到的 keyshot_headless 路径。
-6. 用 keyshot_status 工具测试是否配置成功。
-7. 最后告诉我实际添加的配置，以及状态检查是否通过。
+1. 查找我电脑上的 KeyShot headless 可执行文件路径。
+2. 使用 npx -y keyshot-mcp@0.4.2 添加 keyshot MCP server。
+3. 把 KEYSHOT_HEADLESS_EXE 设置为检测到的 keyshot_headless 路径。
+4. 用 keyshot_status 工具测试是否配置成功。
+5. 最后告诉我实际添加的配置，以及状态检查是否通过。
 
 不要保存许可证密钥、账号密码或授权信息。直接使用我电脑上已有的 KeyShot 本地授权配置。
 ```
@@ -382,25 +489,56 @@ examples/codex.example.json
 检查当前 KeyShot 场景，并总结场景中的对象、相机、材质和可渲染输出。
 ```
 
+```text
+列出当前 KeyShot 场景中的相机，创建或更新一个名为“Hero”的相机，
+把场景保存为新文件，并用这个相机渲染一张预览图。
+```
+
 ## 环境变量
 
 - `KEYSHOT_HEADLESS_EXE`：`keyshot_headless` 或 `keyshot_headless.exe` 的路径。
 - `KEYSHOT_OUTPUT_DIR`：默认渲染输出文件夹。
 - `KEYSHOT_LICENSE_ARGS`：可选的 KeyShot 无界面许可证参数，默认留空。
 - `KEYSHOT_TIMEOUT_MS`：单次操作超时时间，单位毫秒，默认 `600000`。
+- `KEYSHOT_MATERIAL_PRESETS`：材质预设库 JSON 文件路径，默认 `presets/materials.json`。
+- `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS`：是否允许写到默认输出目录之外，默认 `false`。
+
+默认情况下，所有输出图片和场景都必须写入 `KEYSHOT_OUTPUT_DIR`，相对路径会自动放入该目录。
+只有确实需要写到外部目录时才设置为 `true`；输入场景和模型路径不受此限制。
+
+`samples` 和 `maxTimeSeconds` 是两种不同的 KeyShot 渲染模式，请二选一，不要同时传入。
 
 ## MCP 工具
 
 - `keyshot_status`：检查 KeyShot 是否能启动。
 - `keyshot_inspect_scene`：检查场景内容。
+- `keyshot_list_cameras`：列出场景中所有相机名称（批量渲染前很有用）。
 - `keyshot_render`：渲染单张图片。
 - `keyshot_batch_render`：批量渲染多个相机视角。
+- `keyshot_render_queue`：顺序执行多个渲染任务（默认遇错即停，设置 `continueOnError` 可继续）。
 - `keyshot_import_model`：导入模型。
 - `keyshot_apply_material`：替换材质。
+- `keyshot_list_material_presets`：列出材质预设库中的预设。
+- `keyshot_apply_material_preset`：把预设库中的某个命名材质应用到物体上。
 - `keyshot_set_camera`：设置相机。
 - `keyshot_set_environment`：设置环境。
 - `keyshot_save_scene`：保存场景。
 
+### 材质预设库
+
+`keyshot_apply_material_preset` 会读取一个小的 JSON 注册表，让你用"好记的名字"复用材质，
+而不必记住 KeyShot 里精确的材质名。默认位置：`presets/materials.json`
+（可用环境变量 `KEYSHOT_MATERIAL_PRESETS` 覆盖）。
+
+```json
+{
+  "拉丝钢": { "materialName": "Steel Brushed", "description": "金属件默认材质" },
+  "透明玻璃": { "materialPath": "C:/materials/glass_clear.mtl" }
+}
+```
+
+每个预设必须包含 `materialName` 或 `materialPath`。用 `keyshot_list_material_presets` 查看有哪些预设。
+
 ## MCP 提示词和资源
 
 - 提示词：`keyshot_product_render`
@@ -422,13 +560,41 @@ KeyShot 的 Python `lux` API 会随版本变化。这个 MCP 会尽量保持对
 ## 路线图
 
 - [ ] 自动发现并批量渲染场景中的所有相机
-- [ ] 材质预设库
+- [x] 材质预设库
 - [ ] 相机预设模板
-- [ ] 渲染队列状态
-- [ ] 更安全的输出目录限制
+- [x] 顺序渲染队列
+- [x] 更安全的输出目录限制
 - [ ] 测试更多 KeyShot 版本
 - [ ] 验证 macOS 兼容性
-- [ ] 补充 Claude Desktop / Cursor / Codex 配置示例
+- [x] 补充 Claude Desktop / Cursor / Codex 配置示例
+
+## 真实 KeyShot Demo
+
+![KeyShot MCP 自动生成的立方体 Demo](assets/demo/keyshot-mcp-demo.png)
+
+Demo 只使用 `examples/demo` 中项目自己生成的几何体，不包含客户模型或第三方素材。
+设置好 `KEYSHOT_HEADLESS_EXE` 后可复现状态检查、导入、检查场景、创建相机、保存和真实 PNG 渲染：
+
+```bash
+npm run smoke:keyshot
+```
+
+## 测试
+
+项目带了两套测试，不依赖真实的 KeyShot 也能跑：
+
+- **TypeScript 测试（Vitest）**：覆盖配置读取、参数校验（schemas）、结果封装，以及用"假 KeyShot"跑通一次成功路径并验证 `work/tmp` 临时文件会被清理。
+
+  ```bash
+  npm install
+  npm test
+  ```
+
+- **Python bridge 测试（unittest）**：用假的 `lux` 对象验证 `import_model` 会真正打开基础场景、`set_camera` 在拿不到相机对象时不会崩溃并回退到 `lux` 级 API。
+
+  ```bash
+  python tests/test_bridge.py
+  ```
 
 ## 开源协议
 

package/dist/config.js

@@ -9,12 +9,17 @@ export function getConfig() {
         projectRoot,
         keyshotHeadlessExe: process.env.KEYSHOT_HEADLESS_EXE ?? DEFAULT_KEYSHOT_EXE,
         keyshotOutputDir,
+        keyshotAllowExternalOutputs: parseBoolean(process.env.KEYSHOT_ALLOW_EXTERNAL_OUTPUTS),
         keyshotLicenseArgs: splitWindowsArgs(process.env.KEYSHOT_LICENSE_ARGS ?? ""),
         keyshotTimeoutMs: parsePositiveInt(process.env.KEYSHOT_TIMEOUT_MS, DEFAULT_TIMEOUT_MS),
         tmpDir: path.join(projectRoot, "work", "tmp"),
         bridgeScriptPath: path.join(projectRoot, "scripts", "keyshot_bridge.py"),
+        materialPresetsPath: path.resolve(process.env.KEYSHOT_MATERIAL_PRESETS ?? path.join(projectRoot, "presets", "materials.json")),
     };
 }
+function parseBoolean(value) {
+    return ["1", "true", "yes", "on"].includes((value ?? "").trim().toLowerCase());
+}
 function parsePositiveInt(value, fallback) {
     if (!value)
         return fallback;

package/dist/index.js

@@ -2,14 +2,20 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { getConfig } from "./config.js";
-import { toolResponse } from "./result.js";
+import { toolResponse, localFailure } from "./result.js";
 import { runKeyShotSerialized } from "./runner.js";
-import { applyMaterialSchema, applyMaterialInputSchema, batchRenderSchema, importModelSchema, renderSchema, saveSceneSchema, scenePathSchema, setCameraSchema, setEnvironmentSchema, } from "./schemas.js";
+import { runRenderQueue } from "./queue.js";
+import { loadMaterialPresets, findMaterialPreset } from "./presets.js";
+import { VERSION } from "./version.js";
+import { applyMaterialSchema, applyMaterialInputSchema, applyMaterialPresetInputSchema, applyMaterialPresetSchema, batchRenderSchema, batchRenderInputSchema, importModelSchema, listCamerasSchema, listMaterialPresetsSchema, renderQueueSchema, renderQueueInputSchema, renderSchema, renderInputSchema, saveSceneSchema, scenePathSchema, setCameraSchema, setEnvironmentSchema, } from "./schemas.js";
 const config = getConfig();
 const server = new McpServer({
     name: "keyshot-mcp",
-    version: "0.2.1",
+    version: VERSION,
 });
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 server.registerResource("keyshot-workflow", "keyshot://workflow", {
     title: "KeyShot MCP Workflow",
     description: "How this MCP server connects AI agents to KeyShot headless scripting.",
@@ -53,17 +59,67 @@ server.registerPrompt("keyshot_product_render", {
 }));
 server.tool("keyshot_status", "Check KeyShot headless availability and script startup.", {}, async () => toolResponse(await runKeyShotSerialized(config, { operation: "status" })));
 server.tool("keyshot_inspect_scene", "Open a KeyShot scene and return available objects, cameras, materials and scene metadata.", scenePathSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "inspect_scene", ...args })));
-server.tool("keyshot_render", "Render a KeyShot scene to an image file.", renderSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "render", ...args })));
-server.tool("keyshot_batch_render", "Render multiple named cameras from one KeyShot scene into an output directory.", batchRenderSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "batch_render", ...args })));
+server.tool("keyshot_list_cameras", "Open a KeyShot scene and return the list of available camera names (useful before batch rendering).", listCamerasSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "list_cameras", ...args })));
+server.tool("keyshot_render", "Render a KeyShot scene to an image file.", renderSchema.shape, async (args) => {
+    const parsed = renderInputSchema.parse(args);
+    return toolResponse(await runKeyShotSerialized(config, { operation: "render", ...parsed }));
+});
+server.tool("keyshot_render_queue", "Render several jobs sequentially. Stops at the first failure unless continueOnError is set.", renderQueueSchema.shape, async (args) => {
+    const parsed = renderQueueInputSchema.parse(args);
+    return toolResponse(await runRenderQueue(config, parsed.jobs, { continueOnError: parsed.continueOnError ?? false }));
+});
+server.tool("keyshot_batch_render", "Render multiple named cameras from one KeyShot scene into an output directory.", batchRenderSchema.shape, async (args) => {
+    const parsed = batchRenderInputSchema.parse(args);
+    return toolResponse(await runKeyShotSerialized(config, { operation: "batch_render", ...parsed }));
+});
 server.tool("keyshot_import_model", "Import a model into an optional base scene and save the resulting scene.", importModelSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, {
     operation: "import_model",
-    scenePath: args.baseScenePath,
     ...args,
 })));
 server.tool("keyshot_apply_material", "Apply a material by name or material file to a scene object and save the resulting scene.", applyMaterialInputSchema.shape, async (args) => {
     const parsed = applyMaterialSchema.parse(args);
     return toolResponse(await runKeyShotSerialized(config, { operation: "apply_material", ...parsed }));
 });
+server.tool("keyshot_list_material_presets", "List material presets from the local preset library (presets/materials.json or KEYSHOT_MATERIAL_PRESETS).", listMaterialPresetsSchema.shape, async () => {
+    try {
+        const presets = await loadMaterialPresets(config);
+        return toolResponse({
+            ok: true,
+            data: { presets, count: presets.length, source: config.materialPresetsPath },
+            outputFiles: [],
+            warnings: presets.length === 0 ? ["No material presets found. Create presets/materials.json to add some."] : [],
+            keyshotStdoutTail: "",
+            error: null,
+        });
+    }
+    catch (error) {
+        return toolResponse(localFailure(errorMessage(error)));
+    }
+});
+server.tool("keyshot_apply_material_preset", "Apply a named material preset (from the preset library) to a scene object and save the resulting scene.", applyMaterialPresetInputSchema.shape, async (args) => {
+    const parsed = applyMaterialPresetSchema.parse(args);
+    let presets;
+    try {
+        presets = await loadMaterialPresets(config);
+    }
+    catch (error) {
+        return toolResponse(localFailure(errorMessage(error)));
+    }
+    const preset = findMaterialPreset(presets, parsed.presetName);
+    if (!preset) {
+        const available = presets.map((entry) => entry.name).join(", ") || "(none)";
+        return toolResponse(localFailure(`Material preset not found: "${parsed.presetName}". Available: ${available}`));
+    }
+    return toolResponse(await runKeyShotSerialized(config, {
+        operation: "apply_material",
+        scenePath: parsed.scenePath,
+        objectName: parsed.objectName,
+        objectPath: parsed.objectPath,
+        materialName: preset.materialName,
+        materialPath: preset.materialPath,
+        outputScenePath: parsed.outputScenePath,
+    }));
+});
 server.tool("keyshot_set_camera", "Create or update a camera from position/look-at vectors and save the resulting scene.", setCameraSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "set_camera", ...args })));
 server.tool("keyshot_set_environment", "Set a scene environment by name or file when supported by KeyShot headless scripting.", setEnvironmentSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "set_environment", ...args })));
 server.tool("keyshot_save_scene", "Save a KeyShot scene to a new path.", saveSceneSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "save_scene", ...args })));

package/dist/output-paths.js

@@ -0,0 +1,55 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const OUTPUT_FIELDS = ["outputPath", "outputDir", "outputScenePath"];
+export async function normalizeOutputPaths(config, request) {
+    await fs.mkdir(config.keyshotOutputDir, { recursive: true });
+    const normalized = { ...request };
+    for (const field of OUTPUT_FIELDS) {
+        const value = request[field];
+        if (typeof value !== "string" || value.length === 0)
+            continue;
+        normalized[field] = await normalizeOutputPath(config, value);
+    }
+    return normalized;
+}
+export async function normalizeOutputPath(config, value) {
+    const candidate = path.resolve(config.keyshotOutputDir, value);
+    if (config.keyshotAllowExternalOutputs)
+        return candidate;
+    const outputRoot = await realpathWithMissingTail(config.keyshotOutputDir);
+    const resolvedCandidate = await realpathWithMissingTail(candidate);
+    if (!isWithin(outputRoot, resolvedCandidate)) {
+        throw new Error(`Output path must stay inside KEYSHOT_OUTPUT_DIR (${config.keyshotOutputDir}): ${value}. ` +
+            "Set KEYSHOT_ALLOW_EXTERNAL_OUTPUTS=true only if external writes are intentional.");
+    }
+    return candidate;
+}
+async function realpathWithMissingTail(inputPath) {
+    let current = path.resolve(inputPath);
+    const missing = [];
+    while (!(await exists(current))) {
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        missing.unshift(path.basename(current));
+        current = parent;
+    }
+    const realBase = await fs.realpath(current);
+    return path.resolve(realBase, ...missing);
+}
+function isWithin(root, candidate) {
+    const relative = path.relative(normalizeCase(root), normalizeCase(candidate));
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+function normalizeCase(value) {
+    return process.platform === "win32" ? value.toLowerCase() : value;
+}
+async function exists(value) {
+    try {
+        await fs.lstat(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/presets.js

@@ -0,0 +1,67 @@
+import fs from "node:fs/promises";
+/**
+ * Load the material preset library from disk.
+ *
+ * The registry file (see config.materialPresetsPath, overridable with the
+ * KEYSHOT_MATERIAL_PRESETS env var) may use either of two shapes:
+ *
+ *   1. Object keyed by preset name:
+ *      { "Brushed Steel": { "materialName": "Steel Brushed", "description": "..." } }
+ *
+ *   2. Array of presets:
+ *      [ { "name": "Brushed Steel", "materialName": "Steel Brushed" } ]
+ *
+ * A missing file is treated as an empty library (not an error), so the feature
+ * works out of the box before the user creates any presets.
+ */
+export async function loadMaterialPresets(config) {
+    let raw;
+    try {
+        raw = await fs.readFile(config.materialPresetsPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Material presets file is not valid JSON: ${config.materialPresetsPath}`);
+    }
+    return normalizePresets(parsed);
+}
+export function normalizePresets(parsed) {
+    const entries = [];
+    if (Array.isArray(parsed)) {
+        for (const item of parsed) {
+            if (item && typeof item === "object") {
+                const record = item;
+                const name = typeof record.name === "string" ? record.name : undefined;
+                if (name)
+                    entries.push(toPreset(name, record));
+            }
+        }
+    }
+    else if (parsed && typeof parsed === "object") {
+        for (const [name, value] of Object.entries(parsed)) {
+            if (value && typeof value === "object") {
+                entries.push(toPreset(name, value));
+            }
+        }
+    }
+    return entries.filter((preset) => preset.materialName || preset.materialPath);
+}
+function toPreset(name, record) {
+    return {
+        name,
+        materialName: typeof record.materialName === "string" ? record.materialName : undefined,
+        materialPath: typeof record.materialPath === "string" ? record.materialPath : undefined,
+        description: typeof record.description === "string" ? record.description : undefined,
+    };
+}
+export function findMaterialPreset(presets, name) {
+    const lower = name.toLowerCase();
+    return (presets.find((preset) => preset.name === name) ??
+        presets.find((preset) => preset.name.toLowerCase() === lower));
+}

package/dist/queue.js

@@ -0,0 +1,70 @@
+import { runKeyShotSerialized } from "./runner.js";
+/**
+ * Run several render jobs one after another.
+ *
+ * Jobs execute sequentially (the underlying runner is already serialized, and a
+ * single KeyShot instance cannot render in parallel). By default the queue stops
+ * at the first failure; pass continueOnError to render every remaining job and
+ * collect all outcomes. Jobs that are skipped after an early stop are reported
+ * with skipped: true so the caller can see exactly what ran.
+ */
+export async function runRenderQueue(config, jobs, options = {}, runFn = runKeyShotSerialized) {
+    const continueOnError = options.continueOnError ?? false;
+    const results = [];
+    const outputFiles = [];
+    const warnings = [];
+    let succeeded = 0;
+    let failed = 0;
+    let stopped = false;
+    for (let index = 0; index < jobs.length; index += 1) {
+        const job = jobs[index];
+        if (stopped) {
+            results.push({
+                index,
+                scenePath: job.scenePath,
+                camera: job.camera,
+                ok: false,
+                outputFiles: [],
+                error: null,
+                skipped: true,
+            });
+            continue;
+        }
+        const result = await runFn(config, { operation: "render", ...job });
+        results.push({
+            index,
+            scenePath: job.scenePath,
+            camera: job.camera,
+            ok: result.ok,
+            outputFiles: result.outputFiles ?? [],
+            error: result.error ?? null,
+        });
+        if (result.ok) {
+            succeeded += 1;
+            outputFiles.push(...(result.outputFiles ?? []));
+        }
+        else {
+            failed += 1;
+            if (result.error)
+                warnings.push(`Job ${index} failed: ${result.error}`);
+            if (!continueOnError)
+                stopped = true;
+        }
+    }
+    const skipped = results.filter((entry) => entry.skipped).length;
+    return {
+        ok: failed === 0,
+        data: {
+            total: jobs.length,
+            succeeded,
+            failed,
+            skipped,
+            continueOnError,
+            results,
+        },
+        outputFiles,
+        warnings,
+        keyshotStdoutTail: "",
+        error: failed === 0 ? null : `${failed} of ${jobs.length} render job(s) failed.`,
+    };
+}