@imgly/codesign-mcp 0.1.6 → 0.1.8

package/dist/tools/engine.d.ts

@@ -1,12 +1,83 @@
 import type CreativeEngine from '@cesdk/engine';
+/**
+ * The shape both engine packages expose: `module.exports` is the CreativeEngine
+ * class itself, with `.default` aliased to the same class.
+ */
+type EngineModule = {
+    default?: typeof CreativeEngine;
+};
+/** A CJS-style `require`, injected so the selection logic is unit-testable. */
+type Loader = (pkg: string) => unknown;
+/** Which engine package actually loaded, and via what path. */
+export type EngineFlavor = 'native' | 'wasm' | 'wasm-fallback';
+/**
+ * Which engine flavor actually loaded on the first `ensureHeadlessEngine`
+ * call — `undefined` until the engine has booted at least once. Surfaced by
+ * the `diagnostics` tool (`status.config.engineResolved`) so a user can tell
+ * whether they're getting native GPU rasterization or the WASM fallback.
+ */
+export declare function resolvedEngineFlavor(): EngineFlavor | undefined;
+/**
+ * Choose and load the engine package per `IMGLY_CESDK_ENGINE`, with
+ * context-aware fallback:
+ *
+ *   - unset / "" (default) → WASM (TEMPORARY — native is NOT the default because
+ *                            registering a URI resolver breaks all resource
+ *                            loading on @cesdk/node-native, and the MCP server
+ *                            always registers one). Remove `isDefault ||` in the
+ *                            body to restore the native default (CODE-7) once the
+ *                            engine fixes the resolver; the native-load and
+ *                            WASM-fallback paths below stay in place, dormant.
+ *   - "native" (explicit)  → native; if it fails to load, throw — a deliberate
+ *                            request must not silently degrade to slow WASM.
+ *   - "wasm" (explicit)    → WASM; native is never attempted.
+ *   - any other value      → throw (guards typos like "natve").
+ *
+ * Native ships prebuilt binaries for darwin-arm64/darwin-x64/linux-x64 only.
+ *
+ * `load` is injected (the real `createRequire(...)` in production, a stub in
+ * tests). `warn` defaults to `console.warn`, which is stderr-safe: in stdio mode
+ * `redirectConsoleToStderr()` remaps it to stderr so it never corrupts the
+ * JSON-RPC channel; in http mode Node's console.warn already writes to stderr.
+ */
+export declare function resolveEngineModule(env: string | undefined, load: Loader, warn?: (msg: string) => void): {
+    module: EngineModule;
+    flavor: EngineFlavor;
+};
+/**
+ * Resolve the engine module, then initialize it — adding init-time fallback on
+ * top of `resolveEngineModule`'s load-time fallback.
+ *
+ * The native addon (`@cesdk/node-native`) dlopens its GStreamer/GL dependencies
+ * LAZILY, inside `init()` — not at `require()` time. So a native module can
+ * resolve successfully (flavor 'native') and still fail to boot, e.g. on a
+ * Linux host missing system libraries. `resolveEngineModule` alone can't catch
+ * that; this function does, applying the same context-aware policy:
+ *
+ *   - default (env unset/'') + native resolved but init rejects → warn, load
+ *     and init WASM instead, flavor 'wasm-fallback'. If WASM init ALSO
+ *     rejects, that rejection propagates as-is (no further fallback).
+ *   - explicit "native" + init rejects → rejects with a clearer wrapped
+ *     message + `{ cause }`, mirroring `resolveEngineModule`'s load-time throw.
+ *   - explicit "wasm", or already-fallback WASM (flavor !== 'native') + init
+ *     rejects → propagates unchanged.
+ *
+ * `load` and `initEngine` are injected so this stays unit-testable without a
+ * real engine binary; `ensureHeadlessEngine` supplies the real `createRequire`
+ * loader and a real `Ctor.init({ license })` call.
+ */
+export declare function initEngineModule(env: string | undefined, load: Loader, initEngine: (mod: EngineModule) => Promise<CreativeEngine>, warn?: (msg: string) => void): Promise<{
+    engine: CreativeEngine;
+    flavor: EngineFlavor;
+}>;
 /**
  * Initialize a headless CreativeEngine once and share it across calls.
  *
  * Only ever called on node — the browser surface passes `cesdk.engine` directly
  * to the design tools, so this code path is dead in the browser bundle. To keep
- * it that way, both `node:module` and `@cesdk/node` are loaded via async
- * dynamic import inside the function — Vite leaves dynamic imports of node
- * builtins as runtime errors only if executed, not at module init.
+ * it that way, `node:module` is loaded via async dynamic import inside the
+ * function — Vite leaves dynamic imports of node builtins as runtime errors only
+ * if executed, not at module init.
  *
  * Both `@cesdk/node` (WASM) and `@cesdk/node-native` (N-API) are loaded through
  * `createRequire` (CJS-shaped) rather than ESM dynamic import. `@cesdk/node`'s
@@ -15,17 +86,24 @@ import type CreativeEngine from '@cesdk/engine';
  * `ReferenceError: Worker is not defined`. The native package is also CJS-shaped
  * so the same load strategy works for both.
  *
- * Set `IMGLY_CESDK_ENGINE=native` to select the N-API native engine
- * (`@cesdk/node-native`). The default is the WASM engine (`@cesdk/node`).
- *
- * Native vs WASM init API:
- *   - Both packages export `CreativeEngine` as `module.exports` (the class
- *     itself) with `module.exports.default` aliased to the same class.
- *   - Both expose `static init(config?: Partial<Configuration>): Promise<Engine>`
- *     and accept `{ license }` as config.
- *   - The native `Configuration` adds an optional `device: 'auto'|'cpu'|'gpu'`
- *     field (ignored by WASM). We pass only `{ license }` here so both paths
- *     default to `device: 'auto'` (Metal/EGL → CPU fallback on native).
+ * Both packages expose `static init(config?): Promise<Engine>` and accept
+ * `{ license }`. The native `Configuration` adds an optional
+ * `device: 'auto'|'cpu'|'gpu'` field (ignored by WASM); we pass only `{ license }`
+ * so both default to `device: 'auto'` (Metal/EGL → CPU fallback on native).
  */
 export declare function ensureHeadlessEngine(license: string): Promise<CreativeEngine>;
+/**
+ * Dispose the process-wide headless engine if one was created, and reset the
+ * cache so a subsequent `ensureHeadlessEngine` re-initializes from scratch.
+ *
+ * Idempotent and safe to call when no engine was ever initialized (a no-op that
+ * never imports `@cesdk/node`) or while an init is still in flight — it awaits
+ * the pending init first so we dispose a fully-constructed engine, never a
+ * half-built one. A rejected init produced no engine, so that case is swallowed.
+ *
+ * `CreativeEngine.dispose()` is synchronous; this wrapper is async only because
+ * it may await an in-flight `init()`.
+ */
+export declare function disposeHeadlessEngine(): Promise<void>;
+export {};
 //# sourceMappingURL=engine.d.ts.map

package/dist/tools/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/tools/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,cAAc,MAAM,eAAe,CAAC;AAIhD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAmC7E"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/tools/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,cAAc,MAAM,eAAe,CAAC;AAIhD;;;GAGG;AACH,KAAK,YAAY,GAAG;IAClB,OAAO,CAAC,EAAE,OAAO,cAAc,CAAC;CACjC,CAAC;AAEF,+EAA+E;AAC/E,KAAK,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;AAEvC,+DAA+D;AAC/D,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,eAAe,CAAC;AAO/D;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,YAAY,GAAG,SAAS,CAE/D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAmB,GACzC;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAkChD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,cAAc,CAAC,EAC1D,IAAI,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAmB,GACzC,OAAO,CAAC;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC,CA2B3D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAmC7E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAa3D"}

package/dist/tools/engine.js

@@ -1,12 +1,118 @@
 let cached;
+const NATIVE_PKG = '@cesdk/node-native';
+const WASM_PKG = '@cesdk/node';
+let resolvedFlavor;
+/**
+ * Which engine flavor actually loaded on the first `ensureHeadlessEngine`
+ * call — `undefined` until the engine has booted at least once. Surfaced by
+ * the `diagnostics` tool (`status.config.engineResolved`) so a user can tell
+ * whether they're getting native GPU rasterization or the WASM fallback.
+ */
+export function resolvedEngineFlavor() {
+    return resolvedFlavor;
+}
+/**
+ * Choose and load the engine package per `IMGLY_CESDK_ENGINE`, with
+ * context-aware fallback:
+ *
+ *   - unset / "" (default) → WASM (TEMPORARY — native is NOT the default because
+ *                            registering a URI resolver breaks all resource
+ *                            loading on @cesdk/node-native, and the MCP server
+ *                            always registers one). Remove `isDefault ||` in the
+ *                            body to restore the native default (CODE-7) once the
+ *                            engine fixes the resolver; the native-load and
+ *                            WASM-fallback paths below stay in place, dormant.
+ *   - "native" (explicit)  → native; if it fails to load, throw — a deliberate
+ *                            request must not silently degrade to slow WASM.
+ *   - "wasm" (explicit)    → WASM; native is never attempted.
+ *   - any other value      → throw (guards typos like "natve").
+ *
+ * Native ships prebuilt binaries for darwin-arm64/darwin-x64/linux-x64 only.
+ *
+ * `load` is injected (the real `createRequire(...)` in production, a stub in
+ * tests). `warn` defaults to `console.warn`, which is stderr-safe: in stdio mode
+ * `redirectConsoleToStderr()` remaps it to stderr so it never corrupts the
+ * JSON-RPC channel; in http mode Node's console.warn already writes to stderr.
+ */
+export function resolveEngineModule(env, load, warn = console.warn) {
+    const isDefault = env === undefined || env === '';
+    if (!isDefault && env !== 'native' && env !== 'wasm') {
+        throw new Error(`Invalid IMGLY_CESDK_ENGINE "${env}": expected "native" or "wasm"`);
+    }
+    // Default (unset/empty) or explicit "wasm": load WASM. The `isDefault ||` is a
+    // temporary revert of the native default — native breaks all resource loading
+    // under a URI resolver (see the doc comment). Remove it to make native the
+    // default again (CODE-7) once the engine fixes the resolver.
+    if (isDefault || env === 'wasm') {
+        return { module: load(WASM_PKG), flavor: 'wasm' };
+    }
+    // Explicit "native" only (the default no longer reaches here): try native.
+    const explicitNative = env === 'native';
+    try {
+        return { module: load(NATIVE_PKG), flavor: 'native' };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        if (explicitNative) {
+            throw new Error(`IMGLY_CESDK_ENGINE=native but the native engine failed to load: ${detail}`, { cause: err });
+        }
+        warn(`native engine (${NATIVE_PKG}) unavailable on this platform; ` +
+            `falling back to WASM (${WASM_PKG}): ${detail}`);
+        return { module: load(WASM_PKG), flavor: 'wasm-fallback' };
+    }
+}
+/**
+ * Resolve the engine module, then initialize it — adding init-time fallback on
+ * top of `resolveEngineModule`'s load-time fallback.
+ *
+ * The native addon (`@cesdk/node-native`) dlopens its GStreamer/GL dependencies
+ * LAZILY, inside `init()` — not at `require()` time. So a native module can
+ * resolve successfully (flavor 'native') and still fail to boot, e.g. on a
+ * Linux host missing system libraries. `resolveEngineModule` alone can't catch
+ * that; this function does, applying the same context-aware policy:
+ *
+ *   - default (env unset/'') + native resolved but init rejects → warn, load
+ *     and init WASM instead, flavor 'wasm-fallback'. If WASM init ALSO
+ *     rejects, that rejection propagates as-is (no further fallback).
+ *   - explicit "native" + init rejects → rejects with a clearer wrapped
+ *     message + `{ cause }`, mirroring `resolveEngineModule`'s load-time throw.
+ *   - explicit "wasm", or already-fallback WASM (flavor !== 'native') + init
+ *     rejects → propagates unchanged.
+ *
+ * `load` and `initEngine` are injected so this stays unit-testable without a
+ * real engine binary; `ensureHeadlessEngine` supplies the real `createRequire`
+ * loader and a real `Ctor.init({ license })` call.
+ */
+export async function initEngineModule(env, load, initEngine, warn = console.warn) {
+    const { module: mod, flavor } = resolveEngineModule(env, load, warn);
+    try {
+        return { engine: await initEngine(mod), flavor };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        const isDefault = env === undefined || env === '';
+        if (flavor === 'native' && !isDefault) {
+            throw new Error(`IMGLY_CESDK_ENGINE=native but the native engine failed to initialize: ${detail}`, { cause: err });
+        }
+        if (flavor !== 'native') {
+            throw err; // explicit wasm, or already-fallback wasm: no further fallback
+        }
+        // Default mode, native resolved but failed to INIT: fall back to WASM,
+        // same breadcrumb-and-degrade policy as a native load-time failure.
+        warn(`native engine loaded but failed to initialize; falling back to WASM (${WASM_PKG}): ${detail}` +
+            ` — if this is Linux, the native engine needs system libraries (see @cesdk/node-native README, 'Linux runtime dependencies')`);
+        const wasmMod = load(WASM_PKG);
+        return { engine: await initEngine(wasmMod), flavor: 'wasm-fallback' };
+    }
+}
 /**
  * Initialize a headless CreativeEngine once and share it across calls.
  *
  * Only ever called on node — the browser surface passes `cesdk.engine` directly
  * to the design tools, so this code path is dead in the browser bundle. To keep
- * it that way, both `node:module` and `@cesdk/node` are loaded via async
- * dynamic import inside the function — Vite leaves dynamic imports of node
- * builtins as runtime errors only if executed, not at module init.
+ * it that way, `node:module` is loaded via async dynamic import inside the
+ * function — Vite leaves dynamic imports of node builtins as runtime errors only
+ * if executed, not at module init.
  *
  * Both `@cesdk/node` (WASM) and `@cesdk/node-native` (N-API) are loaded through
  * `createRequire` (CJS-shaped) rather than ESM dynamic import. `@cesdk/node`'s
@@ -15,29 +121,22 @@ let cached;
  * `ReferenceError: Worker is not defined`. The native package is also CJS-shaped
  * so the same load strategy works for both.
  *
- * Set `IMGLY_CESDK_ENGINE=native` to select the N-API native engine
- * (`@cesdk/node-native`). The default is the WASM engine (`@cesdk/node`).
- *
- * Native vs WASM init API:
- *   - Both packages export `CreativeEngine` as `module.exports` (the class
- *     itself) with `module.exports.default` aliased to the same class.
- *   - Both expose `static init(config?: Partial<Configuration>): Promise<Engine>`
- *     and accept `{ license }` as config.
- *   - The native `Configuration` adds an optional `device: 'auto'|'cpu'|'gpu'`
- *     field (ignored by WASM). We pass only `{ license }` here so both paths
- *     default to `device: 'auto'` (Metal/EGL → CPU fallback on native).
+ * Both packages expose `static init(config?): Promise<Engine>` and accept
+ * `{ license }`. The native `Configuration` adds an optional
+ * `device: 'auto'|'cpu'|'gpu'` field (ignored by WASM); we pass only `{ license }`
+ * so both default to `device: 'auto'` (Metal/EGL → CPU fallback on native).
  */
 export function ensureHeadlessEngine(license) {
     if (!cached) {
         cached = (async () => {
             const { createRequire } = await import('node:module');
             const require = createRequire(import.meta.url);
-            const pkg = process.env.IMGLY_CESDK_ENGINE === 'native'
-                ? '@cesdk/node-native'
-                : '@cesdk/node';
-            const mod = require(pkg);
-            const Ctor = mod.default ?? mod;
-            const engine = await Ctor.init({ license });
+            const initEngine = (mod) => {
+                const Ctor = mod.default ?? mod;
+                return Ctor.init({ license });
+            };
+            const { engine, flavor } = await initEngineModule(process.env.IMGLY_CESDK_ENGINE, require, initEngine);
+            resolvedFlavor = flavor;
             // CE.SDK's default design unit is "Inch", which makes setTextFontSize
             // + setWidth/Height with numeric pixel-looking values render at ~2.5×
             // the agent's expected size. Patch scene.create so every new scene
@@ -56,4 +155,32 @@ export function ensureHeadlessEngine(license) {
     }
     return cached;
 }
+/**
+ * Dispose the process-wide headless engine if one was created, and reset the
+ * cache so a subsequent `ensureHeadlessEngine` re-initializes from scratch.
+ *
+ * Idempotent and safe to call when no engine was ever initialized (a no-op that
+ * never imports `@cesdk/node`) or while an init is still in flight — it awaits
+ * the pending init first so we dispose a fully-constructed engine, never a
+ * half-built one. A rejected init produced no engine, so that case is swallowed.
+ *
+ * `CreativeEngine.dispose()` is synchronous; this wrapper is async only because
+ * it may await an in-flight `init()`.
+ */
+export async function disposeHeadlessEngine() {
+    const pending = cached;
+    if (!pending)
+        return;
+    // Clear the cache first so no concurrent caller receives the engine we are
+    // about to dispose; a later `ensureHeadlessEngine` builds a fresh one.
+    cached = undefined;
+    let engine;
+    try {
+        engine = await pending;
+    }
+    catch {
+        return; // init never produced an engine — nothing to dispose
+    }
+    engine.dispose();
+}
 //# sourceMappingURL=engine.js.map

package/dist/tools/engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/tools/engine.ts"],"names":[],"mappings":"AAEA,IAAI,MAA2C,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,CAAC,KAAK,IAAI,EAAE;YACnB,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;YACtD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC/C,MAAM,GAAG,GACP,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,QAAQ;gBACzC,CAAC,CAAC,oBAAoB;gBACtB,CAAC,CAAC,aAAa,CAAC;YACpB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAGtB,CAAC;YACF,MAAM,IAAI,GACR,GAAG,CAAC,OAAO,IAAK,GAAwC,CAAC;YAC3D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;YAC5C,sEAAsE;YACtE,sEAAsE;YACtE,mEAAmE;YACnE,qDAAqD;YACrD,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACzD,MAAM,CAAC,KAAyD,CAAC,MAAM;gBACtE,CAAC,CAAC,MAAgB,EAAE,EAAE;oBACpB,MAAM,OAAO,GAAG,UAAU,CACxB,MAA0C,CAC3C,CAAC;oBACF,gEAAgE;oBAChE,8DAA8D;oBAC9D,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;oBACpC,OAAO,OAAO,CAAC;gBACjB,CAAC,CAA+B,CAAC;YACnC,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC,EAAE,CAAC;IACP,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import type CreativeEngine from '@cesdk/engine';\n\nlet cached: Promise<CreativeEngine> | undefined;\n\n/**\n * Initialize a headless CreativeEngine once and share it across calls.\n *\n * Only ever called on node — the browser surface passes `cesdk.engine` directly\n * to the design tools, so this code path is dead in the browser bundle. To keep\n * it that way, both `node:module` and `@cesdk/node` are loaded via async\n * dynamic import inside the function — Vite leaves dynamic imports of node\n * builtins as runtime errors only if executed, not at module init.\n *\n * Both `@cesdk/node` (WASM) and `@cesdk/node-native` (N-API) are loaded through\n * `createRequire` (CJS-shaped) rather than ESM dynamic import. `@cesdk/node`'s\n * emscripten/wasm runtime spawns Workers that resolve relative to the package's\n * `__dirname`; ESM dynamic import + vitest pre-bundling break that path with\n * `ReferenceError: Worker is not defined`. The native package is also CJS-shaped\n * so the same load strategy works for both.\n *\n * Set `IMGLY_CESDK_ENGINE=native` to select the N-API native engine\n * (`@cesdk/node-native`). The default is the WASM engine (`@cesdk/node`).\n *\n * Native vs WASM init API:\n *   - Both packages export `CreativeEngine` as `module.exports` (the class\n *     itself) with `module.exports.default` aliased to the same class.\n *   - Both expose `static init(config?: Partial<Configuration>): Promise<Engine>`\n *     and accept `{ license }` as config.\n *   - The native `Configuration` adds an optional `device: 'auto'|'cpu'|'gpu'`\n *     field (ignored by WASM). We pass only `{ license }` here so both paths\n *     default to `device: 'auto'` (Metal/EGL → CPU fallback on native).\n */\nexport function ensureHeadlessEngine(license: string): Promise<CreativeEngine> {\n  if (!cached) {\n    cached = (async () => {\n      const { createRequire } = await import('node:module');\n      const require = createRequire(import.meta.url);\n      const pkg =\n        process.env.IMGLY_CESDK_ENGINE === 'native'\n          ? '@cesdk/node-native'\n          : '@cesdk/node';\n      const mod = require(pkg) as {\n        default?: typeof CreativeEngine;\n        init?: typeof CreativeEngine.init;\n      };\n      const Ctor: typeof CreativeEngine =\n        mod.default ?? (mod as unknown as typeof CreativeEngine);\n      const engine = await Ctor.init({ license });\n      // CE.SDK's default design unit is \"Inch\", which makes setTextFontSize\n      // + setWidth/Height with numeric pixel-looking values render at ~2.5×\n      // the agent's expected size. Patch scene.create so every new scene\n      // starts in Pixel — the agent never has to remember.\n      const origCreate = engine.scene.create.bind(engine.scene);\n      (engine.scene as unknown as { create(layout?: unknown): number }).create =\n        ((layout?: unknown) => {\n          const sceneId = origCreate(\n            layout as Parameters<typeof origCreate>[0]\n          );\n          // @cesdk/node setDesignUnit takes only the unit; it operates on\n          // the current scene, which is the one create() just returned.\n          engine.scene.setDesignUnit('Pixel');\n          return sceneId;\n        }) as typeof engine.scene.create;\n      return engine;\n    })();\n  }\n  return cached;\n}\n"]}
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/tools/engine.ts"],"names":[],"mappings":"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","sourcesContent":["import type CreativeEngine from '@cesdk/engine';\n\nlet cached: Promise<CreativeEngine> | undefined;\n\n/**\n * The shape both engine packages expose: `module.exports` is the CreativeEngine\n * class itself, with `.default` aliased to the same class.\n */\ntype EngineModule = {\n  default?: typeof CreativeEngine;\n};\n\n/** A CJS-style `require`, injected so the selection logic is unit-testable. */\ntype Loader = (pkg: string) => unknown;\n\n/** Which engine package actually loaded, and via what path. */\nexport type EngineFlavor = 'native' | 'wasm' | 'wasm-fallback';\n\nconst NATIVE_PKG = '@cesdk/node-native';\nconst WASM_PKG = '@cesdk/node';\n\nlet resolvedFlavor: EngineFlavor | undefined;\n\n/**\n * Which engine flavor actually loaded on the first `ensureHeadlessEngine`\n * call — `undefined` until the engine has booted at least once. Surfaced by\n * the `diagnostics` tool (`status.config.engineResolved`) so a user can tell\n * whether they're getting native GPU rasterization or the WASM fallback.\n */\nexport function resolvedEngineFlavor(): EngineFlavor | undefined {\n  return resolvedFlavor;\n}\n\n/**\n * Choose and load the engine package per `IMGLY_CESDK_ENGINE`, with\n * context-aware fallback:\n *\n *   - unset / \"\" (default) → WASM (TEMPORARY — native is NOT the default because\n *                            registering a URI resolver breaks all resource\n *                            loading on @cesdk/node-native, and the MCP server\n *                            always registers one). Remove `isDefault ||` in the\n *                            body to restore the native default (CODE-7) once the\n *                            engine fixes the resolver; the native-load and\n *                            WASM-fallback paths below stay in place, dormant.\n *   - \"native\" (explicit)  → native; if it fails to load, throw — a deliberate\n *                            request must not silently degrade to slow WASM.\n *   - \"wasm\" (explicit)    → WASM; native is never attempted.\n *   - any other value      → throw (guards typos like \"natve\").\n *\n * Native ships prebuilt binaries for darwin-arm64/darwin-x64/linux-x64 only.\n *\n * `load` is injected (the real `createRequire(...)` in production, a stub in\n * tests). `warn` defaults to `console.warn`, which is stderr-safe: in stdio mode\n * `redirectConsoleToStderr()` remaps it to stderr so it never corrupts the\n * JSON-RPC channel; in http mode Node's console.warn already writes to stderr.\n */\nexport function resolveEngineModule(\n  env: string | undefined,\n  load: Loader,\n  warn: (msg: string) => void = console.warn\n): { module: EngineModule; flavor: EngineFlavor } {\n  const isDefault = env === undefined || env === '';\n  if (!isDefault && env !== 'native' && env !== 'wasm') {\n    throw new Error(\n      `Invalid IMGLY_CESDK_ENGINE \"${env}\": expected \"native\" or \"wasm\"`\n    );\n  }\n\n  // Default (unset/empty) or explicit \"wasm\": load WASM. The `isDefault ||` is a\n  // temporary revert of the native default — native breaks all resource loading\n  // under a URI resolver (see the doc comment). Remove it to make native the\n  // default again (CODE-7) once the engine fixes the resolver.\n  if (isDefault || env === 'wasm') {\n    return { module: load(WASM_PKG) as EngineModule, flavor: 'wasm' };\n  }\n\n  // Explicit \"native\" only (the default no longer reaches here): try native.\n  const explicitNative = env === 'native';\n  try {\n    return { module: load(NATIVE_PKG) as EngineModule, flavor: 'native' };\n  } catch (err) {\n    const detail = err instanceof Error ? err.message : String(err);\n    if (explicitNative) {\n      throw new Error(\n        `IMGLY_CESDK_ENGINE=native but the native engine failed to load: ${detail}`,\n        { cause: err }\n      );\n    }\n    warn(\n      `native engine (${NATIVE_PKG}) unavailable on this platform; ` +\n        `falling back to WASM (${WASM_PKG}): ${detail}`\n    );\n    return { module: load(WASM_PKG) as EngineModule, flavor: 'wasm-fallback' };\n  }\n}\n\n/**\n * Resolve the engine module, then initialize it — adding init-time fallback on\n * top of `resolveEngineModule`'s load-time fallback.\n *\n * The native addon (`@cesdk/node-native`) dlopens its GStreamer/GL dependencies\n * LAZILY, inside `init()` — not at `require()` time. So a native module can\n * resolve successfully (flavor 'native') and still fail to boot, e.g. on a\n * Linux host missing system libraries. `resolveEngineModule` alone can't catch\n * that; this function does, applying the same context-aware policy:\n *\n *   - default (env unset/'') + native resolved but init rejects → warn, load\n *     and init WASM instead, flavor 'wasm-fallback'. If WASM init ALSO\n *     rejects, that rejection propagates as-is (no further fallback).\n *   - explicit \"native\" + init rejects → rejects with a clearer wrapped\n *     message + `{ cause }`, mirroring `resolveEngineModule`'s load-time throw.\n *   - explicit \"wasm\", or already-fallback WASM (flavor !== 'native') + init\n *     rejects → propagates unchanged.\n *\n * `load` and `initEngine` are injected so this stays unit-testable without a\n * real engine binary; `ensureHeadlessEngine` supplies the real `createRequire`\n * loader and a real `Ctor.init({ license })` call.\n */\nexport async function initEngineModule(\n  env: string | undefined,\n  load: Loader,\n  initEngine: (mod: EngineModule) => Promise<CreativeEngine>,\n  warn: (msg: string) => void = console.warn\n): Promise<{ engine: CreativeEngine; flavor: EngineFlavor }> {\n  const { module: mod, flavor } = resolveEngineModule(env, load, warn);\n  try {\n    return { engine: await initEngine(mod), flavor };\n  } catch (err) {\n    const detail = err instanceof Error ? err.message : String(err);\n    const isDefault = env === undefined || env === '';\n\n    if (flavor === 'native' && !isDefault) {\n      throw new Error(\n        `IMGLY_CESDK_ENGINE=native but the native engine failed to initialize: ${detail}`,\n        { cause: err }\n      );\n    }\n    if (flavor !== 'native') {\n      throw err; // explicit wasm, or already-fallback wasm: no further fallback\n    }\n\n    // Default mode, native resolved but failed to INIT: fall back to WASM,\n    // same breadcrumb-and-degrade policy as a native load-time failure.\n    warn(\n      `native engine loaded but failed to initialize; falling back to WASM (${WASM_PKG}): ${detail}` +\n        ` — if this is Linux, the native engine needs system libraries (see @cesdk/node-native README, 'Linux runtime dependencies')`\n    );\n    const wasmMod = load(WASM_PKG) as EngineModule;\n    return { engine: await initEngine(wasmMod), flavor: 'wasm-fallback' };\n  }\n}\n\n/**\n * Initialize a headless CreativeEngine once and share it across calls.\n *\n * Only ever called on node — the browser surface passes `cesdk.engine` directly\n * to the design tools, so this code path is dead in the browser bundle. To keep\n * it that way, `node:module` is loaded via async dynamic import inside the\n * function — Vite leaves dynamic imports of node builtins as runtime errors only\n * if executed, not at module init.\n *\n * Both `@cesdk/node` (WASM) and `@cesdk/node-native` (N-API) are loaded through\n * `createRequire` (CJS-shaped) rather than ESM dynamic import. `@cesdk/node`'s\n * emscripten/wasm runtime spawns Workers that resolve relative to the package's\n * `__dirname`; ESM dynamic import + vitest pre-bundling break that path with\n * `ReferenceError: Worker is not defined`. The native package is also CJS-shaped\n * so the same load strategy works for both.\n *\n * Both packages expose `static init(config?): Promise<Engine>` and accept\n * `{ license }`. The native `Configuration` adds an optional\n * `device: 'auto'|'cpu'|'gpu'` field (ignored by WASM); we pass only `{ license }`\n * so both default to `device: 'auto'` (Metal/EGL → CPU fallback on native).\n */\nexport function ensureHeadlessEngine(license: string): Promise<CreativeEngine> {\n  if (!cached) {\n    cached = (async () => {\n      const { createRequire } = await import('node:module');\n      const require = createRequire(import.meta.url);\n      const initEngine = (mod: EngineModule): Promise<CreativeEngine> => {\n        const Ctor: typeof CreativeEngine =\n          mod.default ?? (mod as unknown as typeof CreativeEngine);\n        return Ctor.init({ license });\n      };\n      const { engine, flavor } = await initEngineModule(\n        process.env.IMGLY_CESDK_ENGINE,\n        require,\n        initEngine\n      );\n      resolvedFlavor = flavor;\n      // CE.SDK's default design unit is \"Inch\", which makes setTextFontSize\n      // + setWidth/Height with numeric pixel-looking values render at ~2.5×\n      // the agent's expected size. Patch scene.create so every new scene\n      // starts in Pixel — the agent never has to remember.\n      const origCreate = engine.scene.create.bind(engine.scene);\n      (engine.scene as unknown as { create(layout?: unknown): number }).create =\n        ((layout?: unknown) => {\n          const sceneId = origCreate(\n            layout as Parameters<typeof origCreate>[0]\n          );\n          // @cesdk/node setDesignUnit takes only the unit; it operates on\n          // the current scene, which is the one create() just returned.\n          engine.scene.setDesignUnit('Pixel');\n          return sceneId;\n        }) as typeof engine.scene.create;\n      return engine;\n    })();\n  }\n  return cached;\n}\n\n/**\n * Dispose the process-wide headless engine if one was created, and reset the\n * cache so a subsequent `ensureHeadlessEngine` re-initializes from scratch.\n *\n * Idempotent and safe to call when no engine was ever initialized (a no-op that\n * never imports `@cesdk/node`) or while an init is still in flight — it awaits\n * the pending init first so we dispose a fully-constructed engine, never a\n * half-built one. A rejected init produced no engine, so that case is swallowed.\n *\n * `CreativeEngine.dispose()` is synchronous; this wrapper is async only because\n * it may await an in-flight `init()`.\n */\nexport async function disposeHeadlessEngine(): Promise<void> {\n  const pending = cached;\n  if (!pending) return;\n  // Clear the cache first so no concurrent caller receives the engine we are\n  // about to dispose; a later `ensureHeadlessEngine` builds a fresh one.\n  cached = undefined;\n  let engine: CreativeEngine;\n  try {\n    engine = await pending;\n  } catch {\n    return; // init never produced an engine — nothing to dispose\n  }\n  engine.dispose();\n}\n"]}

package/dist/tools/export.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/tools/export.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAoEpB,MAAM,WAAW,uBAAuB,CAAC,CAAC,GAAG,OAAO;IAClD,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B,8EAA8E;IAC9E,UAAU,EAAE,gBAAgB,CAAC;IAC7B,gFAAgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yHAAyH;IACzH,UAAU,EAAE,KAAK,CAAC;IAClB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1C,IAAI,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAC/B,2BAA2B,CAyK7B"}
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/tools/export.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAoEpB,MAAM,WAAW,uBAAuB,CAAC,CAAC,GAAG,OAAO;IAClD,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B,8EAA8E;IAC9E,UAAU,EAAE,gBAAgB,CAAC;IAC7B,gFAAgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yHAAyH;IACzH,UAAU,EAAE,KAAK,CAAC;IAClB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1C,IAAI,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAC/B,2BAA2B,CA0M7B"}

package/dist/tools/export.js

@@ -70,6 +70,7 @@ export function createExportTool(opts) {
             let result;
             let threw;
             let revision;
+            let exportError;
             try {
                 result = await (async () => {
                     const args = (rawArgs ?? {});
@@ -141,16 +142,41 @@ export function createExportTool(opts) {
                     // load-into-engine then export reads the shared engine across awaits —
                     // serialize against any concurrent engine-touching tool call.
                     const beforeLock = performance.now();
-                    const bytes = await engineLock.runExclusive(async () => {
+                    const rendered = await engineLock.runExclusive(async () => {
                         rec.add('lock_wait', performance.now() - beforeLock);
                         const slot = await rec.time('engine_scene_load', async () => {
                             await session.populate(revId, sceneBytes);
                             return session.acquire(revId);
                         });
                         const eng = slot.engine;
-                        const blob = await rec.time('engine_execute', () => eng.block.export(blockId, mime, {}));
-                        return new Uint8Array(await blob.arrayBuffer());
+                        // We loaded `revId` under the lock just above, so the correct scene
+                        // is current. If the render throws, `blockId` genuinely isn't in
+                        // this revision's scene (a wrong or removed id) — return a legible
+                        // tool error the model can act on (mirroring `edit`'s dirty-on-throw
+                        // path) instead of rethrowing into an opaque MCP -32603.
+                        try {
+                            const blob = await rec.time('engine_execute', () => eng.block.export(blockId, mime, {}));
+                            return { bytes: new Uint8Array(await blob.arrayBuffer()) };
+                        }
+                        catch (err) {
+                            return { error: err };
+                        }
                     });
+                    if ('error' in rendered) {
+                        exportError = rendered.error;
+                        return {
+                            isError: true,
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `export: could not render block ${blockId} in revision ${revId}. That block id isn't in this revision's scene — double-check the id (use \`inspect\` to see the revision's structure), or it may have been removed in this revision. ${rendered.error instanceof Error
+                                        ? (rendered.error.stack ?? rendered.error.message)
+                                        : String(rendered.error)}`
+                                }
+                            ]
+                        };
+                    }
+                    const bytes = rendered.bytes;
                     const shard = args.revision.slice(0, 2);
                     const rest = args.revision.slice(2);
                     const ext = FORMAT_EXT[args.format];
@@ -208,7 +234,11 @@ export function createExportTool(opts) {
                     args: rawArgs,
                     ...(result !== undefined ? { result: summarizeResult(result) } : {}),
                     ...(revision ? { revision } : {}),
-                    ...(threw ? { error: toErrorShape(threw) } : {})
+                    ...(threw
+                        ? { error: toErrorShape(threw) }
+                        : exportError
+                            ? { error: toErrorShape(exportError) }
+                            : {})
                 });
             }
         }

package/dist/tools/export.js.map

@@ -1 +1 @@
-{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/tools/export.ts"],"names":[],"mappings":"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","sourcesContent":["// packages/codesign-mcp/src/tools/export.ts\n//\n// `export` — spec §6.2. Writes a revision-pinned artifact into\n// `exports/<shard>/<rev>/<format>.<ext>` and returns a workspace URI envelope:\n// `uri` (the durable `workspace://` handle) plus `httpUrl` (the `/r/` fetch\n// link). `path` (an absolute disk path) is returned ONLY when the caller\n// passes an explicit `outPath` — a normal workspace export never discloses\n// the workspace's on-disk location.\n//\n// `target=video` is deferred to Phase 4.\nimport { promises as nodeFs } from 'node:fs';\nimport { dirname } from 'node:path';\nimport { performance } from 'node:perf_hooks';\nimport type { Mutex } from '../engine/mutex.js';\nimport type { EngineSession } from '../engine/session.js';\nimport type { RevisionStore } from '../revisions/store.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\nimport type { ViewerUrlBuilder } from '../viewer/url-builder.js';\nimport type { WorkspaceFS } from '../workspace/types.js';\nimport {\n  NOOP_TELEMETRY_SINK,\n  SpanRecorder,\n  summarizeResult,\n  toErrorShape,\n  type TelemetrySink\n} from './spans.js';\n\ntype Target = 'pdf' | 'image' | 'video';\ntype Format = 'pdf' | 'png' | 'jpeg' | 'webp' | 'mp4';\n\ninterface MinimalEngine {\n  block: {\n    export(blockId: number, mimeType: string, options?: unknown): Promise<Blob>;\n  };\n}\n\ninterface ExportArgs {\n  target: Target;\n  format: Format;\n  revision: string;\n  blockId?: number;\n  outPath?: string;\n}\n\nconst TARGET_MIME: Record<'pdf' | 'image', Record<string, string>> = {\n  pdf: { pdf: 'application/pdf' },\n  image: { png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp' }\n};\n\nconst FORMAT_EXT: Record<Format, string> = {\n  pdf: 'pdf',\n  png: 'png',\n  jpeg: 'jpg',\n  webp: 'webp',\n  mp4: 'mp4'\n};\n\nconst DESCRIPTION = [\n  'Export a revision to pdf/image. Renders `blockId` and writes the result into the workspace under `exports/<shard>/<rev>/<target>.<ext>` (revision-pinned, deterministic).',\n  '',\n  'Returns JSON: `{ uri, httpUrl?, path?, bytes, format, revision }`. `uri` (a `workspace://` URI) is the durable handle. `httpUrl` is a fetch link for opening the artifact now — present for workspace exports, tied to this process. `path` (absolute disk path) is returned ONLY when you passed `outPath`.',\n  '',\n  '`target=video` is deferred to Phase 4.'\n].join('\\n');\n\n// The schema is built per-backend: `outPath` is advertised ONLY when the\n// backend honours it (Local). On Hosted the property is omitted entirely, so\n// an agent never sees an affordance it can't use — it can't try a local path\n// and hit a runtime rejection. The runtime guard in `call` stays as a backstop.\nfunction buildExportInputSchema(allowOutPath: boolean) {\n  const properties: Record<string, unknown> = {\n    target: { enum: ['pdf', 'image', 'video'] },\n    format: { enum: ['pdf', 'png', 'jpeg', 'webp', 'mp4'] },\n    revision: { type: 'string' as const },\n    blockId: {\n      type: 'integer' as const,\n      description: 'Required for pdf and image targets.'\n    }\n  };\n  if (allowOutPath) {\n    properties.outPath = {\n      type: 'string' as const,\n      description: 'Local-only escape hatch; absolute path.'\n    };\n  }\n  return {\n    type: 'object' as const,\n    properties,\n    required: ['target', 'format', 'revision'],\n    additionalProperties: false\n  };\n}\n\nexport interface CreateExportToolOptions<E = unknown> {\n  fs: WorkspaceFS;\n  store: RevisionStore;\n  session: EngineSession<E>;\n  /** Builds the `httpUrl` for workspace-written artifacts (the `/r/` route). */\n  urlBuilder: ViewerUrlBuilder;\n  /** Whether to honour an `outPath` argument (Local: yes; Hosted/sandbox: no). */\n  allowOutPath?: boolean;\n  /** Guards the shared engine — load-then-export must not interleave with another session's edit (see engine/mutex.ts). */\n  engineLock: Mutex;\n  /** Diagnostics telemetry port. Absent → no-op (no timing overhead beyond a few clocks). */\n  telemetry?: TelemetrySink;\n}\n\nexport function createExportTool<E = unknown>(\n  opts: CreateExportToolOptions<E>\n): CodesignMcpToolRegistration {\n  const {\n    fs,\n    store,\n    session,\n    urlBuilder,\n    allowOutPath = false,\n    engineLock\n  } = opts;\n  const telemetry = opts.telemetry ?? NOOP_TELEMETRY_SINK;\n  return {\n    name: 'export',\n    description: DESCRIPTION,\n    inputSchema: buildExportInputSchema(allowOutPath),\n    call: async (rawArgs) => {\n      const rec = new SpanRecorder();\n      const startedAt = performance.now();\n      type CallResult = Awaited<\n        ReturnType<CodesignMcpToolRegistration['call']>\n      >;\n      let result: CallResult | undefined;\n      let threw: unknown;\n      let revision: string | undefined;\n      try {\n        result = await (async (): Promise<CallResult> => {\n          const args = (rawArgs ?? {}) as Partial<ExportArgs>;\n          if (\n            typeof args.target !== 'string' ||\n            typeof args.format !== 'string' ||\n            typeof args.revision !== 'string'\n          ) {\n            return {\n              isError: true,\n              content: [\n                {\n                  type: 'text' as const,\n                  text: 'export: target, format, and revision are required.'\n                }\n              ]\n            };\n          }\n          if (args.target === 'video') {\n            return {\n              isError: true,\n              content: [\n                {\n                  type: 'text' as const,\n                  text: 'export: target=video is deferred to Phase 4.'\n                }\n              ]\n            };\n          }\n          if (args.outPath !== undefined && !allowOutPath) {\n            return {\n              isError: true,\n              content: [\n                {\n                  type: 'text' as const,\n                  text: 'export: `outPath` is not supported on this (hosted) backend. Omit it — the artifact is written to the workspace and returned as `httpUrl`; fetch that URL to download the bytes to disk.'\n                }\n              ]\n            };\n          }\n          const rev = await rec.time('workspace_read', () =>\n            store.read(args.revision as string)\n          );\n          if (typeof args.blockId !== 'number') {\n            return {\n              isError: true,\n              content: [\n                {\n                  type: 'text' as const,\n                  text: `export: target=${args.target} requires \\`blockId\\`.`\n                }\n              ]\n            };\n          }\n          const mimeMap = TARGET_MIME[args.target as 'pdf' | 'image'];\n          const mime = mimeMap?.[args.format];\n          if (!mime) {\n            return {\n              isError: true,\n              content: [\n                {\n                  type: 'text' as const,\n                  text: `export: invalid format=${args.format} for target=${args.target}.`\n                }\n              ]\n            };\n          }\n          // Capture validated args into locals so the locked closure keeps the\n          // type narrowing the top-level guards established.\n          const revId = args.revision;\n          const blockId = args.blockId;\n          const sceneBytes = rev.scene;\n          // load-into-engine then export reads the shared engine across awaits —\n          // serialize against any concurrent engine-touching tool call.\n          const beforeLock = performance.now();\n          const bytes = await engineLock.runExclusive(async () => {\n            rec.add('lock_wait', performance.now() - beforeLock);\n            const slot = await rec.time('engine_scene_load', async () => {\n              await session.populate(revId, sceneBytes);\n              return session.acquire(revId);\n            });\n            const eng = slot.engine as MinimalEngine;\n            const blob = await rec.time('engine_execute', () =>\n              eng.block.export(blockId, mime, {})\n            );\n            return new Uint8Array(await blob.arrayBuffer());\n          });\n          const shard = args.revision.slice(0, 2);\n          const rest = args.revision.slice(2);\n          const ext = FORMAT_EXT[args.format];\n          const relPath = `exports/${shard}/${rest}/${args.target}.${ext}`;\n          let absPath: string | undefined;\n          let httpUrl: string | undefined;\n          if (args.outPath !== undefined) {\n            // Local-only escape hatch: write through real disk fs, NOT through\n            // the workspace abstraction. The caller chose this path explicitly,\n            // so echoing it back is a confirmation, not a workspace-path leak.\n            await nodeFs.mkdir(dirname(args.outPath), { recursive: true });\n            await rec.time('workspace_write', async () => {\n              await nodeFs.writeFile(args.outPath as string, bytes);\n            });\n            absPath = args.outPath;\n          } else {\n            // Workspace write — goes through the WorkspaceFS abstraction. The\n            // artifact is reachable over HTTP via the `/r/` route; the absolute\n            // disk path is deliberately NOT disclosed.\n            await rec.time('workspace_write', async () => {\n              await fs.writeFile(relPath, bytes);\n            });\n            httpUrl = await urlBuilder.forDownload(relPath);\n          }\n          revision = args.revision;\n          return {\n            content: [\n              {\n                type: 'text' as const,\n                text: JSON.stringify({\n                  uri: `workspace://${relPath}`,\n                  ...(httpUrl ? { httpUrl } : {}),\n                  ...(absPath ? { path: absPath } : {}),\n                  bytes: bytes.byteLength,\n                  format: args.format,\n                  revision: args.revision\n                })\n              }\n            ]\n          };\n        })();\n        return result;\n      } catch (err) {\n        threw = err;\n        throw err;\n      } finally {\n        telemetry.record({\n          tool: 'export',\n          succeeded: threw === undefined && result?.isError !== true,\n          totalMs: performance.now() - startedAt,\n          spans: rec.list(),\n          args: rawArgs,\n          ...(result !== undefined ? { result: summarizeResult(result) } : {}),\n          ...(revision ? { revision } : {}),\n          ...(threw ? { error: toErrorShape(threw) } : {})\n        });\n      }\n    }\n  };\n}\n"]}
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/tools/export.ts"],"names":[],"mappings":"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","sourcesContent":["// packages/codesign-mcp/src/tools/export.ts\n//\n// `export` — spec §6.2. Writes a revision-pinned artifact into\n// `exports/<shard>/<rev>/<format>.<ext>` and returns a workspace URI envelope:\n// `uri` (the durable `workspace://` handle) plus `httpUrl` (the `/r/` fetch\n// link). `path` (an absolute disk path) is returned ONLY when the caller\n// passes an explicit `outPath` — a normal workspace export never discloses\n// the workspace's on-disk location.\n//\n// `target=video` is deferred to Phase 4.\nimport { promises as nodeFs } from 'node:fs';\nimport { dirname } from 'node:path';\nimport { performance } from 'node:perf_hooks';\nimport type { Mutex } from '../engine/mutex.js';\nimport type { EngineSession } from '../engine/session.js';\nimport type { RevisionStore } from '../revisions/store.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\nimport type { ViewerUrlBuilder } from '../viewer/url-builder.js';\nimport type { WorkspaceFS } from '../workspace/types.js';\nimport {\n  NOOP_TELEMETRY_SINK,\n  SpanRecorder,\n  summarizeResult,\n  toErrorShape,\n  type TelemetrySink\n} from './spans.js';\n\ntype Target = 'pdf' | 'image' | 'video';\ntype Format = 'pdf' | 'png' | 'jpeg' | 'webp' | 'mp4';\n\ninterface MinimalEngine {\n  block: {\n    export(blockId: number, mimeType: string, options?: unknown): Promise<Blob>;\n  };\n}\n\ninterface ExportArgs {\n  target: Target;\n  format: Format;\n  revision: string;\n  blockId?: number;\n  outPath?: string;\n}\n\nconst TARGET_MIME: Record<'pdf' | 'image', Record<string, string>> = {\n  pdf: { pdf: 'application/pdf' },\n  image: { png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp' }\n};\n\nconst FORMAT_EXT: Record<Format, string> = {\n  pdf: 'pdf',\n  png: 'png',\n  jpeg: 'jpg',\n  webp: 'webp',\n  mp4: 'mp4'\n};\n\nconst DESCRIPTION = [\n  'Export a revision to pdf/image. Renders `blockId` and writes the result into the workspace under `exports/<shard>/<rev>/<target>.<ext>` (revision-pinned, deterministic).',\n  '',\n  'Returns JSON: `{ uri, httpUrl?, path?, bytes, format, revision }`. `uri` (a `workspace://` URI) is the durable handle. `httpUrl` is a fetch link for opening the artifact now — present for workspace exports, tied to this process. `path` (absolute disk path) is returned ONLY when you passed `outPath`.',\n  '',\n  '`target=video` is deferred to Phase 4.'\n].join('\\n');\n\n// The schema is built per-backend: `outPath` is advertised ONLY when the\n// backend honours it (Local). On Hosted the property is omitted entirely, so\n// an agent never sees an affordance it can't use — it can't try a local path\n// and hit a runtime rejection. The runtime guard in `call` stays as a backstop.\nfunction buildExportInputSchema(allowOutPath: boolean) {\n  const properties: Record<string, unknown> = {\n    target: { enum: ['pdf', 'image', 'video'] },\n    format: { enum: ['pdf', 'png', 'jpeg', 'webp', 'mp4'] },\n    revision: { type: 'string' as const },\n    blockId: {\n      type: 'integer' as const,\n      description: 'Required for pdf and image targets.'\n    }\n  };\n  if (allowOutPath) {\n    properties.outPath = {\n      type: 'string' as const,\n      description: 'Local-only escape hatch; absolute path.'\n    };\n  }\n  return {\n    type: 'object' as const,\n    properties,\n    required: ['target', 'format', 'revision'],\n    additionalProperties: false\n  };\n}\n\nexport interface CreateExportToolOptions<E = unknown> {\n  fs: WorkspaceFS;\n  store: RevisionStore;\n  session: EngineSession<E>;\n  /** Builds the `httpUrl` for workspace-written artifacts (the `/r/` route). */\n  urlBuilder: ViewerUrlBuilder;\n  /** Whether to honour an `outPath` argument (Local: yes; Hosted/sandbox: no). */\n  allowOutPath?: boolean;\n  /** Guards the shared engine — load-then-export must not interleave with another session's edit (see engine/mutex.ts). */\n  engineLock: Mutex;\n  /** Diagnostics telemetry port. Absent → no-op (no timing overhead beyond a few clocks). */\n  telemetry?: TelemetrySink;\n}\n\nexport function createExportTool<E = unknown>(\n  opts: CreateExportToolOptions<E>\n): CodesignMcpToolRegistration {\n  const {\n    fs,\n    store,\n    session,\n    urlBuilder,\n    allowOutPath = false,\n    engineLock\n  } = opts;\n  const telemetry = opts.telemetry ?? NOOP_TELEMETRY_SINK;\n  return {\n    name: 'export',\n    description: DESCRIPTION,\n    inputSchema: buildExportInputSchema(allowOutPath),\n    call: async (rawArgs) => {\n      const rec = new SpanRecorder();\n      const startedAt = performance.now();\n      type CallResult = Awaited<\n        ReturnType<CodesignMcpToolRegistration['call']>\n      >;\n      let result: CallResult | undefined;\n      let threw: unknown;\n      let revision: string | undefined;\n      let exportError: unknown;\n      try {\n        result = await (async (): Promise<CallResult> => {\n          const args = (rawArgs ?? {}) as Partial<ExportArgs>;\n          if (\n            typeof args.target !== 'string' ||\n            typeof args.format !== 'string' ||\n            typeof args.revision !== 'string'\n          ) {\n            return {\n              isError: true,\n              content: [\n                {\n                  type: 'text' as const,\n                  text: 'export: target, format, and revision are required.'\n                }\n              ]\n            };\n          }\n          if (args.target === 'video') {\n            return {\n              isError: true,\n              content: [\n                {\n                  type: 'text' as const,\n                  text: 'export: target=video is deferred to Phase 4.'\n                }\n              ]\n            };\n          }\n          if (args.outPath !== undefined && !allowOutPath) {\n            return {\n              isError: true,\n              content: [\n                {\n                  type: 'text' as const,\n                  text: 'export: `outPath` is not supported on this (hosted) backend. Omit it — the artifact is written to the workspace and returned as `httpUrl`; fetch that URL to download the bytes to disk.'\n                }\n              ]\n            };\n          }\n          const rev = await rec.time('workspace_read', () =>\n            store.read(args.revision as string)\n          );\n          if (typeof args.blockId !== 'number') {\n            return {\n              isError: true,\n              content: [\n                {\n                  type: 'text' as const,\n                  text: `export: target=${args.target} requires \\`blockId\\`.`\n                }\n              ]\n            };\n          }\n          const mimeMap = TARGET_MIME[args.target as 'pdf' | 'image'];\n          const mime = mimeMap?.[args.format];\n          if (!mime) {\n            return {\n              isError: true,\n              content: [\n                {\n                  type: 'text' as const,\n                  text: `export: invalid format=${args.format} for target=${args.target}.`\n                }\n              ]\n            };\n          }\n          // Capture validated args into locals so the locked closure keeps the\n          // type narrowing the top-level guards established.\n          const revId = args.revision;\n          const blockId = args.blockId;\n          const sceneBytes = rev.scene;\n          // load-into-engine then export reads the shared engine across awaits —\n          // serialize against any concurrent engine-touching tool call.\n          const beforeLock = performance.now();\n          const rendered = await engineLock.runExclusive(\n            async (): Promise<{ bytes: Uint8Array } | { error: unknown }> => {\n              rec.add('lock_wait', performance.now() - beforeLock);\n              const slot = await rec.time('engine_scene_load', async () => {\n                await session.populate(revId, sceneBytes);\n                return session.acquire(revId);\n              });\n              const eng = slot.engine as MinimalEngine;\n              // We loaded `revId` under the lock just above, so the correct scene\n              // is current. If the render throws, `blockId` genuinely isn't in\n              // this revision's scene (a wrong or removed id) — return a legible\n              // tool error the model can act on (mirroring `edit`'s dirty-on-throw\n              // path) instead of rethrowing into an opaque MCP -32603.\n              try {\n                const blob = await rec.time('engine_execute', () =>\n                  eng.block.export(blockId, mime, {})\n                );\n                return { bytes: new Uint8Array(await blob.arrayBuffer()) };\n              } catch (err) {\n                return { error: err };\n              }\n            }\n          );\n          if ('error' in rendered) {\n            exportError = rendered.error;\n            return {\n              isError: true,\n              content: [\n                {\n                  type: 'text' as const,\n                  text: `export: could not render block ${blockId} in revision ${revId}. That block id isn't in this revision's scene — double-check the id (use \\`inspect\\` to see the revision's structure), or it may have been removed in this revision. ${\n                    rendered.error instanceof Error\n                      ? (rendered.error.stack ?? rendered.error.message)\n                      : String(rendered.error)\n                  }`\n                }\n              ]\n            };\n          }\n          const bytes = rendered.bytes;\n          const shard = args.revision.slice(0, 2);\n          const rest = args.revision.slice(2);\n          const ext = FORMAT_EXT[args.format];\n          const relPath = `exports/${shard}/${rest}/${args.target}.${ext}`;\n          let absPath: string | undefined;\n          let httpUrl: string | undefined;\n          if (args.outPath !== undefined) {\n            // Local-only escape hatch: write through real disk fs, NOT through\n            // the workspace abstraction. The caller chose this path explicitly,\n            // so echoing it back is a confirmation, not a workspace-path leak.\n            await nodeFs.mkdir(dirname(args.outPath), { recursive: true });\n            await rec.time('workspace_write', async () => {\n              await nodeFs.writeFile(args.outPath as string, bytes);\n            });\n            absPath = args.outPath;\n          } else {\n            // Workspace write — goes through the WorkspaceFS abstraction. The\n            // artifact is reachable over HTTP via the `/r/` route; the absolute\n            // disk path is deliberately NOT disclosed.\n            await rec.time('workspace_write', async () => {\n              await fs.writeFile(relPath, bytes);\n            });\n            httpUrl = await urlBuilder.forDownload(relPath);\n          }\n          revision = args.revision;\n          return {\n            content: [\n              {\n                type: 'text' as const,\n                text: JSON.stringify({\n                  uri: `workspace://${relPath}`,\n                  ...(httpUrl ? { httpUrl } : {}),\n                  ...(absPath ? { path: absPath } : {}),\n                  bytes: bytes.byteLength,\n                  format: args.format,\n                  revision: args.revision\n                })\n              }\n            ]\n          };\n        })();\n        return result;\n      } catch (err) {\n        threw = err;\n        throw err;\n      } finally {\n        telemetry.record({\n          tool: 'export',\n          succeeded: threw === undefined && result?.isError !== true,\n          totalMs: performance.now() - startedAt,\n          spans: rec.list(),\n          args: rawArgs,\n          ...(result !== undefined ? { result: summarizeResult(result) } : {}),\n          ...(revision ? { revision } : {}),\n          ...(threw\n            ? { error: toErrorShape(threw) }\n            : exportError\n              ? { error: toErrorShape(exportError) }\n              : {})\n        });\n      }\n    }\n  };\n}\n"]}

package/dist/tools/index.js

@@ -18,11 +18,11 @@ import { createImportTool } from './import.js';
 import { createInspectTool } from './inspect.js';
 import { createListTool } from './list.js';
 import { createLoadTool } from './load.js';
-import { createOpenEditorTool } from './open-editor.js';
 import { createPreviewTool } from './preview.js';
 import { createRenameTool } from './rename.js';
 import { createSaveTool } from './save.js';
 import { wrapWithTelemetry } from './telemetry-wrapper.js';
+import { createViewTool } from './view.js';
 // Beta kill-switch for asset_generate. Off for the beta (the feature isn't
 // supported yet); set to true to re-expose the tool once it ships.
 const ASSET_GENERATE_ENABLED = false;
@@ -75,7 +75,7 @@ export function buildDesignToolRegistrations(opts) {
         createHistoryTool({ store: opts.store }),
         createInspectTool({ store: opts.store }),
         createRenameTool({ store: opts.store }),
-        createOpenEditorTool({ urlBuilder: opts.urlBuilder, store: opts.store }),
+        createViewTool({ urlBuilder: opts.urlBuilder, store: opts.store }),
         createAssetSearchTool({
             session: opts.session,
             engineLock: opts.engineLock

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,0EAA0E;AAC1E,0EAA0E;AAC1E,2EAA2E;AAC3E,aAAa;AACb,2DAA2D;AAC3D,yEAAyE;AACzE,2DAA2D;AAU3D,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,2EAA2E;AAC3E,mEAAmE;AACnE,MAAM,sBAAsB,GAAG,KAAK,CAAC;AA+BrC,MAAM,UAAU,4BAA4B,CAC1C,IAA4C;IAE5C,MAAM,aAAa,GAAkC;QACnD,cAAc,CAAC;YACb,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;QACF,iBAAiB,CAAC;YAChB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;QACF,gBAAgB,CAAC;YACf,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;QACF,cAAc,CAAC;YACb,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,YAAY,EAAE,IAAI,CAAC,YAAY;SAChC,CAAC;QACF,cAAc,CAAC;YACb,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,mEAAmE;YACnE,yEAAyE;YACzE,SAAS,EAAE,IAAI,CAAC,YAAY;YAC5B,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,eAAe,EAAE,IAAI,CAAC,eAAe;SACtC,CAAC;QACF,cAAc,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QACrC,iBAAiB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QACxC,iBAAiB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QACxC,gBAAgB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QACvC,oBAAoB,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QACxE,qBAAqB,CAAC;YACpB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B,CAAC;KACH,CAAC;IAEF,2EAA2E;IAC3E,6EAA6E;IAC7E,6EAA6E;IAC7E,uEAAuE;IACvE,gDAAgD;IAChD,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,aAAa,CAAC,IAAI,CAChB,gBAAgB,CAAC;YACf,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,cAAc,EAAE,IAAI;SACrB,CAAC,CACH,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,sEAAsE;IACtE,2EAA2E;IAC3E,4EAA4E;IAC5E,sEAAsE;IACtE,4EAA4E;IAC5E,IAAI,sBAAsB,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACrD,aAAa,CAAC,IAAI,CAChB,uBAAuB,CAAC;YACtB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B,CAAC,CACH,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,6EAA6E;IAC7E,8EAA8E;IAC9E,wEAAwE;IACxE,sDAAsD;IACtD,IAAI,CAAC,IAAI,CAAC,SAAS;QAAE,OAAO,aAAa,CAAC;IAC1C,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACjC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC7D,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,EAAE,CACxC,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC;QAClC,CAAC,CAAC,YAAY;QACd,CAAC,CAAC,iBAAiB,CAAC,YAAY,EAAE,SAAS,CAAC,CAC/C,CAAC;AACJ,CAAC","sourcesContent":["// packages/codesign-mcp/src/tools/index.ts\n//\n// Builds the design + workspace tool registrations from a fully-DI'd set of\n// primitives: the always-on design + workspace tools, plus `asset_generate`\n// — currently hidden for the beta (see ASSET_GENERATE_ENABLED below), and\n// otherwise gated on a usable gateway (Local: API_KEY set). A hidden tool\n// never shows up in tools/list, so the model won't attempt a call that can\n// only fail.\n// Each variant's CLI bootstrap (cli/stdio.ts, cli/http.ts)\n// constructs these primitives once and passes them in; this file owns no\n// engine bootstrap, no FS bootstrap, no gateway selection.\n\nimport type { Mutex } from '../engine/mutex.js';\nimport type { EngineSession } from '../engine/session.js';\nimport type { GatewayClient } from '../gateway/types.js';\nimport type { RevisionStore } from '../revisions/store.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\nimport type { ViewerUrlBuilder } from '../viewer/url-builder.js';\nimport type { WorkspaceFS } from '../workspace/types.js';\nimport type { TelemetrySink } from './spans.js';\nimport { createAssetGenerateTool } from './asset-generate.js';\nimport { createAssetSearchTool } from './asset-search.js';\nimport { createEditTool } from './edit.js';\nimport { createExportTool } from './export.js';\nimport { createHistoryTool } from './history.js';\nimport { createImportTool } from './import.js';\nimport { createInspectTool } from './inspect.js';\nimport { createListTool } from './list.js';\nimport { createLoadTool } from './load.js';\nimport { createOpenEditorTool } from './open-editor.js';\nimport { createPreviewTool } from './preview.js';\nimport { createRenameTool } from './rename.js';\nimport { createSaveTool } from './save.js';\nimport { wrapWithTelemetry } from './telemetry-wrapper.js';\n\n// Beta kill-switch for asset_generate. Off for the beta (the feature isn't\n// supported yet); set to true to re-expose the tool once it ships.\nconst ASSET_GENERATE_ENABLED = false;\n\nexport interface BuildDesignToolRegistrationsOptions<E = unknown> {\n  fs: WorkspaceFS;\n  store: RevisionStore;\n  session: EngineSession<E>;\n  /**\n   * Serializes access to the shared CE.SDK engine across the edit/preview/\n   * export tools. One engine today (process singleton) ⇒ one lock shared by\n   * every session. See engine/mutex.ts and the bootstrap (cli/http.ts,\n   * cli/stdio.ts) for where it is created.\n   */\n  engineLock: Mutex;\n  gateway: GatewayClient;\n  urlBuilder: ViewerUrlBuilder;\n  /** True on Local (the `outPath?` escape hatch is allowed); false on Hosted/sandbox. */\n  allowOutPath: boolean;\n  /** Called when `edit` writes a new leaf revision (viewer SSE hook). */\n  onLeafWritten?: (event: {\n    revision: string;\n    rootRevision: string;\n  }) => void | Promise<void>;\n  /** Render a thumbnail for a newly committed revision. Optional; best-effort. */\n  renderThumbnail?: (event: {\n    revision: string;\n    engine: E;\n  }) => Promise<Uint8Array>;\n  /** Diagnostics telemetry port, threaded into the engine tools (edit/preview/export). */\n  telemetry?: TelemetrySink;\n}\n\nexport function buildDesignToolRegistrations<E = unknown>(\n  opts: BuildDesignToolRegistrationsOptions<E>\n): CodesignMcpToolRegistration[] {\n  const registrations: CodesignMcpToolRegistration[] = [\n    createEditTool({\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock,\n      onLeafWritten: opts.onLeafWritten,\n      renderThumbnail: opts.renderThumbnail,\n      fs: opts.fs,\n      telemetry: opts.telemetry\n    }),\n    createPreviewTool({\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock,\n      telemetry: opts.telemetry\n    }),\n    createExportTool({\n      fs: opts.fs,\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock,\n      urlBuilder: opts.urlBuilder,\n      allowOutPath: opts.allowOutPath,\n      telemetry: opts.telemetry\n    }),\n    createSaveTool({\n      fs: opts.fs,\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock,\n      urlBuilder: opts.urlBuilder,\n      allowOutPath: opts.allowOutPath\n    }),\n    createLoadTool({\n      fs: opts.fs,\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock,\n      // Same Local-only disk gate as save/export's outPath: a `{ path }`\n      // source only makes sense where the process shares a disk with the user.\n      allowPath: opts.allowOutPath,\n      onLeafWritten: opts.onLeafWritten,\n      renderThumbnail: opts.renderThumbnail\n    }),\n    createListTool({ store: opts.store }),\n    createHistoryTool({ store: opts.store }),\n    createInspectTool({ store: opts.store }),\n    createRenameTool({ store: opts.store }),\n    createOpenEditorTool({ urlBuilder: opts.urlBuilder, store: opts.store }),\n    createAssetSearchTool({\n      session: opts.session,\n      engineLock: opts.engineLock\n    })\n  ];\n\n  // `import` is Local-only for now: its sole source arm (`{ path }`) needs a\n  // server that shares the caller's disk. On Hosted there is no byte transport\n  // until CODE-42, so we HIDE the tool there rather than show the model a tool\n  // whose every call would fail. `allowOutPath` is the same Local(true)/\n  // Hosted(false) signal export/save already use.\n  if (opts.allowOutPath) {\n    registrations.push(\n      createImportTool({\n        fs: opts.fs,\n        urlBuilder: opts.urlBuilder,\n        allowLocalPath: true\n      })\n    );\n  }\n\n  // BETA: asset_generate is hidden for the beta — not supported yet, and we\n  // don't want the model to see a tool it can't use. The implementation\n  // (asset-generate.ts, gateway plumbing) is intentionally kept intact; flip\n  // ASSET_GENERATE_ENABLED back to true to re-expose it. Hiding the tool also\n  // drops the handbook/instructions hint, which keys off tool presence.\n  // Opt-in: only expose asset_generate when the gateway can fulfil a request.\n  if (ASSET_GENERATE_ENABLED && opts.gateway.available) {\n    registrations.push(\n      createAssetGenerateTool({\n        gateway: opts.gateway,\n        fs: opts.fs,\n        urlBuilder: opts.urlBuilder\n      })\n    );\n  }\n\n  // Diagnostics coverage. The engine tools (edit/preview/export) self-report a\n  // rich ToolCallReport with phase spans (they were passed `telemetry` above).\n  // Wrap EVERY other tool so its calls are recorded too — args, result, timing,\n  // success — just with empty spans. Without a telemetry sink, nothing is\n  // wrapped (zero overhead, byte-equivalent to before).\n  if (!opts.telemetry) return registrations;\n  const telemetry = opts.telemetry;\n  const selfReporting = new Set(['edit', 'preview', 'export']);\n  return registrations.map((registration) =>\n    selfReporting.has(registration.name)\n      ? registration\n      : wrapWithTelemetry(registration, telemetry)\n  );\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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","sourcesContent":["// packages/codesign-mcp/src/tools/index.ts\n//\n// Builds the design + workspace tool registrations from a fully-DI'd set of\n// primitives: the always-on design + workspace tools, plus `asset_generate`\n// — currently hidden for the beta (see ASSET_GENERATE_ENABLED below), and\n// otherwise gated on a usable gateway (Local: API_KEY set). A hidden tool\n// never shows up in tools/list, so the model won't attempt a call that can\n// only fail.\n// Each variant's CLI bootstrap (cli/stdio.ts, cli/http.ts)\n// constructs these primitives once and passes them in; this file owns no\n// engine bootstrap, no FS bootstrap, no gateway selection.\n\nimport type { Mutex } from '../engine/mutex.js';\nimport type { EngineSession } from '../engine/session.js';\nimport type { GatewayClient } from '../gateway/types.js';\nimport type { RevisionStore } from '../revisions/store.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\nimport type { ViewerUrlBuilder } from '../viewer/url-builder.js';\nimport type { WorkspaceFS } from '../workspace/types.js';\nimport type { TelemetrySink } from './spans.js';\nimport { createAssetGenerateTool } from './asset-generate.js';\nimport { createAssetSearchTool } from './asset-search.js';\nimport { createEditTool } from './edit.js';\nimport { createExportTool } from './export.js';\nimport { createHistoryTool } from './history.js';\nimport { createImportTool } from './import.js';\nimport { createInspectTool } from './inspect.js';\nimport { createListTool } from './list.js';\nimport { createLoadTool } from './load.js';\nimport { createPreviewTool } from './preview.js';\nimport { createRenameTool } from './rename.js';\nimport { createSaveTool } from './save.js';\nimport { wrapWithTelemetry } from './telemetry-wrapper.js';\nimport { createViewTool } from './view.js';\n\n// Beta kill-switch for asset_generate. Off for the beta (the feature isn't\n// supported yet); set to true to re-expose the tool once it ships.\nconst ASSET_GENERATE_ENABLED = false;\n\nexport interface BuildDesignToolRegistrationsOptions<E = unknown> {\n  fs: WorkspaceFS;\n  store: RevisionStore;\n  session: EngineSession<E>;\n  /**\n   * Serializes access to the shared CE.SDK engine across the edit/preview/\n   * export tools. One engine today (process singleton) ⇒ one lock shared by\n   * every session. See engine/mutex.ts and the bootstrap (cli/http.ts,\n   * cli/stdio.ts) for where it is created.\n   */\n  engineLock: Mutex;\n  gateway: GatewayClient;\n  urlBuilder: ViewerUrlBuilder;\n  /** True on Local (the `outPath?` escape hatch is allowed); false on Hosted/sandbox. */\n  allowOutPath: boolean;\n  /** Called when `edit` writes a new leaf revision (viewer SSE hook). */\n  onLeafWritten?: (event: {\n    revision: string;\n    rootRevision: string;\n  }) => void | Promise<void>;\n  /** Render a thumbnail for a newly committed revision. Optional; best-effort. */\n  renderThumbnail?: (event: {\n    revision: string;\n    engine: E;\n  }) => Promise<Uint8Array>;\n  /** Diagnostics telemetry port, threaded into the engine tools (edit/preview/export). */\n  telemetry?: TelemetrySink;\n}\n\nexport function buildDesignToolRegistrations<E = unknown>(\n  opts: BuildDesignToolRegistrationsOptions<E>\n): CodesignMcpToolRegistration[] {\n  const registrations: CodesignMcpToolRegistration[] = [\n    createEditTool({\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock,\n      onLeafWritten: opts.onLeafWritten,\n      renderThumbnail: opts.renderThumbnail,\n      fs: opts.fs,\n      telemetry: opts.telemetry\n    }),\n    createPreviewTool({\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock,\n      telemetry: opts.telemetry\n    }),\n    createExportTool({\n      fs: opts.fs,\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock,\n      urlBuilder: opts.urlBuilder,\n      allowOutPath: opts.allowOutPath,\n      telemetry: opts.telemetry\n    }),\n    createSaveTool({\n      fs: opts.fs,\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock,\n      urlBuilder: opts.urlBuilder,\n      allowOutPath: opts.allowOutPath\n    }),\n    createLoadTool({\n      fs: opts.fs,\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock,\n      // Same Local-only disk gate as save/export's outPath: a `{ path }`\n      // source only makes sense where the process shares a disk with the user.\n      allowPath: opts.allowOutPath,\n      onLeafWritten: opts.onLeafWritten,\n      renderThumbnail: opts.renderThumbnail\n    }),\n    createListTool({ store: opts.store }),\n    createHistoryTool({ store: opts.store }),\n    createInspectTool({ store: opts.store }),\n    createRenameTool({ store: opts.store }),\n    createViewTool({ urlBuilder: opts.urlBuilder, store: opts.store }),\n    createAssetSearchTool({\n      session: opts.session,\n      engineLock: opts.engineLock\n    })\n  ];\n\n  // `import` is Local-only for now: its sole source arm (`{ path }`) needs a\n  // server that shares the caller's disk. On Hosted there is no byte transport\n  // until CODE-42, so we HIDE the tool there rather than show the model a tool\n  // whose every call would fail. `allowOutPath` is the same Local(true)/\n  // Hosted(false) signal export/save already use.\n  if (opts.allowOutPath) {\n    registrations.push(\n      createImportTool({\n        fs: opts.fs,\n        urlBuilder: opts.urlBuilder,\n        allowLocalPath: true\n      })\n    );\n  }\n\n  // BETA: asset_generate is hidden for the beta — not supported yet, and we\n  // don't want the model to see a tool it can't use. The implementation\n  // (asset-generate.ts, gateway plumbing) is intentionally kept intact; flip\n  // ASSET_GENERATE_ENABLED back to true to re-expose it. Hiding the tool also\n  // drops the handbook/instructions hint, which keys off tool presence.\n  // Opt-in: only expose asset_generate when the gateway can fulfil a request.\n  if (ASSET_GENERATE_ENABLED && opts.gateway.available) {\n    registrations.push(\n      createAssetGenerateTool({\n        gateway: opts.gateway,\n        fs: opts.fs,\n        urlBuilder: opts.urlBuilder\n      })\n    );\n  }\n\n  // Diagnostics coverage. The engine tools (edit/preview/export) self-report a\n  // rich ToolCallReport with phase spans (they were passed `telemetry` above).\n  // Wrap EVERY other tool so its calls are recorded too — args, result, timing,\n  // success — just with empty spans. Without a telemetry sink, nothing is\n  // wrapped (zero overhead, byte-equivalent to before).\n  if (!opts.telemetry) return registrations;\n  const telemetry = opts.telemetry;\n  const selfReporting = new Set(['edit', 'preview', 'export']);\n  return registrations.map((registration) =>\n    selfReporting.has(registration.name)\n      ? registration\n      : wrapWithTelemetry(registration, telemetry)\n  );\n}\n"]}

package/dist/tools/load.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/tools/load.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AA8TzD,MAAM,WAAW,qBAAqB,CAAC,CAAC,GAAG,OAAO;IAChD,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B,0GAA0G;IAC1G,UAAU,EAAE,KAAK,CAAC;IAClB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;KACtB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,oFAAoF;IACpF,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,CAAC,CAAC;KACX,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAC3B;AAED,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EACxC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC7B,2BAA2B,CAmK7B"}
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/tools/load.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAyUzD,MAAM,WAAW,qBAAqB,CAAC,CAAC,GAAG,OAAO;IAChD,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B,0GAA0G;IAC1G,UAAU,EAAE,KAAK,CAAC;IAClB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;KACtB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,oFAAoF;IACpF,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,CAAC,CAAC;KACX,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAC3B;AAED,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EACxC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC7B,2BAA2B,CAmK7B"}