@imgly/codesign-mcp 0.1.5 → 0.1.6

package/dist/tools/index.js

@@ -14,12 +14,15 @@ import { createAssetSearchTool } from './asset-search.js';
 import { createEditTool } from './edit.js';
 import { createExportTool } from './export.js';
 import { createHistoryTool } from './history.js';
+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';
 // 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;
@@ -31,12 +34,14 @@ export function buildDesignToolRegistrations(opts) {
             engineLock: opts.engineLock,
             onLeafWritten: opts.onLeafWritten,
             renderThumbnail: opts.renderThumbnail,
-            fs: opts.fs
+            fs: opts.fs,
+            telemetry: opts.telemetry
         }),
         createPreviewTool({
             store: opts.store,
             session: opts.session,
-            engineLock: opts.engineLock
+            engineLock: opts.engineLock,
+            telemetry: opts.telemetry
         }),
         createExportTool({
             fs: opts.fs,
@@ -44,7 +49,8 @@ export function buildDesignToolRegistrations(opts) {
             session: opts.session,
             engineLock: opts.engineLock,
             urlBuilder: opts.urlBuilder,
-            allowOutPath: opts.allowOutPath
+            allowOutPath: opts.allowOutPath,
+            telemetry: opts.telemetry
         }),
         createSaveTool({
             fs: opts.fs,
@@ -54,6 +60,17 @@ export function buildDesignToolRegistrations(opts) {
             urlBuilder: opts.urlBuilder,
             allowOutPath: opts.allowOutPath
         }),
+        createLoadTool({
+            fs: opts.fs,
+            store: opts.store,
+            session: opts.session,
+            engineLock: opts.engineLock,
+            // Same Local-only disk gate as save/export's outPath: a `{ path }`
+            // source only makes sense where the process shares a disk with the user.
+            allowPath: opts.allowOutPath,
+            onLeafWritten: opts.onLeafWritten,
+            renderThumbnail: opts.renderThumbnail
+        }),
         createListTool({ store: opts.store }),
         createHistoryTool({ store: opts.store }),
         createInspectTool({ store: opts.store }),
@@ -64,6 +81,18 @@ export function buildDesignToolRegistrations(opts) {
             engineLock: opts.engineLock
         })
     ];
+    // `import` is Local-only for now: its sole source arm (`{ path }`) needs a
+    // server that shares the caller's disk. On Hosted there is no byte transport
+    // until CODE-42, so we HIDE the tool there rather than show the model a tool
+    // whose every call would fail. `allowOutPath` is the same Local(true)/
+    // Hosted(false) signal export/save already use.
+    if (opts.allowOutPath) {
+        registrations.push(createImportTool({
+            fs: opts.fs,
+            urlBuilder: opts.urlBuilder,
+            allowLocalPath: true
+        }));
+    }
     // BETA: asset_generate is hidden for the beta — not supported yet, and we
     // don't want the model to see a tool it can't use. The implementation
     // (asset-generate.ts, gateway plumbing) is intentionally kept intact; flip
@@ -77,6 +106,17 @@ export function buildDesignToolRegistrations(opts) {
             urlBuilder: opts.urlBuilder
         }));
     }
-    return registrations;
+    // Diagnostics coverage. The engine tools (edit/preview/export) self-report a
+    // rich ToolCallReport with phase spans (they were passed `telemetry` above).
+    // Wrap EVERY other tool so its calls are recorded too — args, result, timing,
+    // success — just with empty spans. Without a telemetry sink, nothing is
+    // wrapped (zero overhead, byte-equivalent to before).
+    if (!opts.telemetry)
+        return registrations;
+    const telemetry = opts.telemetry;
+    const selfReporting = new Set(['edit', 'preview', 'export']);
+    return registrations.map((registration) => selfReporting.has(registration.name)
+        ? registration
+        : wrapWithTelemetry(registration, telemetry));
 }
 //# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"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 { 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 { createInspectTool } from './inspect.js';\nimport { createListTool } from './list.js';\nimport { createOpenEditorTool } from './open-editor.js';\nimport { createPreviewTool } from './preview.js';\nimport { createRenameTool } from './rename.js';\nimport { createSaveTool } from './save.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}\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    }),\n    createPreviewTool({\n      store: opts.store,\n      session: opts.session,\n      engineLock: opts.engineLock\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    }),\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    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  // 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  return registrations;\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 { 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"]}

package/dist/tools/load.d.ts

@@ -0,0 +1,26 @@
+import type { Mutex } from '../engine/mutex.js';
+import type { EngineSession } from '../engine/session.js';
+import type { RevisionStore } from '../revisions/store.js';
+import type { CodesignMcpToolRegistration } from '../server.js';
+import type { WorkspaceFS } from '../workspace/types.js';
+export interface CreateLoadToolOptions<E = unknown> {
+    fs: WorkspaceFS;
+    store: RevisionStore;
+    session: EngineSession<E>;
+    /** Guards the shared engine — load-then-explode must not interleave with another engine-touching call. */
+    engineLock: Mutex;
+    /** Whether to honour a `{ path }` source (Local: yes; Hosted/sandbox: no). */
+    allowPath?: boolean;
+    /** Called after the new root revision is written (viewer SSE hook). */
+    onLeafWritten?: (event: {
+        revision: string;
+        rootRevision: string;
+    }) => void | Promise<void>;
+    /** Render a thumbnail for the new revision. Best-effort: failures are swallowed. */
+    renderThumbnail?: (event: {
+        revision: string;
+        engine: E;
+    }) => Promise<Uint8Array>;
+}
+export declare function createLoadTool<E = unknown>(opts: CreateLoadToolOptions<E>): CodesignMcpToolRegistration;
+//# sourceMappingURL=load.d.ts.map

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

@@ -0,0 +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"}

package/dist/tools/load.js

@@ -0,0 +1,400 @@
+// packages/codesign-mcp/src/tools/load.ts
+//
+// `load` — ingest a native CE.SDK `.scene` file or `.zip` scene archive as a
+// NEW design root revision (the inverse of `save`). Archives are "exploded":
+// after `loadFromArchiveURL` their bundled asset bytes live in the engine as
+// ephemeral `buffer:` resources (which scene-level `saveToString` rejects —
+// the CODE-3 bug); we extract each one into the content-addressed asset store
+// (`assets/<sha>.<ext>`), relocate it to a durable `workspace://` URI, and
+// only then serialize. Bare `.scene` files carry no asset bytes: they persist
+// as-is, plus a classification report of every referenced asset URI.
+//
+// Both source variants normalize to bytes up front (fetch for `url`, disk
+// read for `path` — Local only), then dispatch on the zip magic bytes.
+// Archive bytes are staged to a temp file and loaded via a `file://` URL:
+// scene-level CE.SDK v1.77 has no `loadFromArchive(path/bytes)`, only
+// `loadFromArchiveURL`, and `file` is a first-class engine scheme.
+import { promises as nodeFs } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { SCENE_ALLOWED_RESOURCE_SCHEMES } from '../engine/scene-resource-schemes.js';
+import { shortHash } from '../workspace/content-hash.js';
+const DESCRIPTION = [
+    'Load a native CE.SDK design — a `.scene` file or a `.zip` scene archive (e.g. a template) — as a NEW design root revision. The inverse of `save`.',
+    '',
+    'Source: `{ url }` (http/https) or `{ path }` (absolute local file path; Local only). Archives are ingested: bundled asset bytes are extracted into the workspace as content-addressed `assets/<sha>.<ext>` files, so the loaded design is durable and behaves exactly like a natively-built one.',
+    '',
+    'Returns JSON `{ revision, title }` — continue with `edit({ parent: revision, … })`. Bare `.scene` loads additionally return `assets`: a classification of every referenced asset URI by scheme (`workspace` / `external` / `bundle` / `transient` / `other`). External URLs are NOT fetched.'
+].join('\n');
+// The schema is built per-backend, like `save`'s outPath: the `{ path }`
+// source arm is advertised ONLY where local disk paths exist (Local).
+//
+// `source` is a FLAT object with optional `url`/`path` — deliberately NOT a
+// `oneOf` union. A `oneOf` here is the single construct most likely to break
+// tool calling: OpenAI bans it in strict mode, and weaker models (e.g.
+// openrouter:xiaomi/mimo-v2.5-pro, and Claude per samchon/openapi#88) serialize
+// the whole union value as an escaped JSON string, which then fails validation.
+// The "exactly one of url/path" invariant is enforced in `call` below, with a
+// clear error message instead of an opaque oneOf mismatch. This mirrors
+// `import`'s `source` shape. See test/tools/schema-best-practices.test.ts.
+function buildLoadInputSchema(allowPath) {
+    const sourceProperties = {
+        url: {
+            type: 'string',
+            description: 'http(s) URL of a `.scene` file or `.zip` scene archive.'
+        }
+    };
+    if (allowPath) {
+        sourceProperties.path = {
+            type: 'string',
+            description: 'Absolute local file path of a `.scene` file or `.zip` scene archive. Local-only.'
+        };
+    }
+    return {
+        type: 'object',
+        properties: {
+            source: {
+                type: 'object',
+                description: allowPath
+                    ? 'The design to load. Provide exactly one of `url` (http/https) or `path` (absolute local file path; Local only).'
+                    : 'The design to load. Provide `url` (http/https).',
+                properties: sourceProperties,
+                additionalProperties: false
+            },
+            title: {
+                type: 'string',
+                description: "Display name for the new design. Defaults to the source file's basename."
+            }
+        },
+        required: ['source'],
+        additionalProperties: false
+    };
+}
+/** Standard zip local-file-header magic: PK\x03\x04. */
+function isZip(bytes) {
+    return (bytes.length >= 4 &&
+        bytes[0] === 0x50 &&
+        bytes[1] === 0x4b &&
+        bytes[2] === 0x03 &&
+        bytes[3] === 0x04);
+}
+/** Basename of the source, minus a `.zip`/`.scene` extension. */
+function deriveTitle(source) {
+    let base;
+    if ('url' in source) {
+        const raw = new URL(source.url).pathname.split('/').pop() ?? '';
+        try {
+            base = decodeURIComponent(raw);
+        }
+        catch {
+            base = raw; // malformed percent sequence — use the basename as-is
+        }
+    }
+    else {
+        // Local paths are literal filenames — never percent-decode them.
+        base = source.path.split('/').pop() ?? '';
+    }
+    const name = base.replace(/\.(zip|scene)$/i, '');
+    return name === '' ? undefined : name;
+}
+// Broad enough for what CE.SDK archives actually bundle (images, fonts,
+// audio/video). Unknown types get a neutral `.bin` — the workspace store and
+// the /r/ route are extension-agnostic.
+const MIME_EXT = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/webp': 'webp',
+    'image/gif': 'gif',
+    'image/svg+xml': 'svg',
+    'video/mp4': 'mp4',
+    'video/quicktime': 'mov',
+    'audio/mpeg': 'mp3',
+    'audio/wav': 'wav',
+    'audio/x-wav': 'wav',
+    'audio/mp4': 'm4a',
+    'font/ttf': 'ttf',
+    'font/otf': 'otf',
+    'font/woff': 'woff',
+    'font/woff2': 'woff2',
+    'application/x-font-ttf': 'ttf',
+    'application/font-sfnt': 'ttf'
+};
+function extForMime(mime) {
+    return MIME_EXT[mime] ?? 'bin';
+}
+function concatChunks(chunks) {
+    const total = chunks.reduce((n, c) => n + c.byteLength, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.byteLength;
+    }
+    return out;
+}
+/**
+ * Persist one engine resource's bytes into the content-addressed asset store
+ * and return its workspace-relative path. Identical bytes land at the
+ * identical path regardless of caller (automatic dedup).
+ */
+async function persistResourceBytes(eng, fs, uri) {
+    const chunks = [];
+    eng.editor.getResourceData(uri, 1 << 20, (chunk) => {
+        chunks.push(chunk.slice()); // copy — the engine may reuse the buffer
+        return true;
+    });
+    const bytes = concatChunks(chunks);
+    const sha = await shortHash(bytes);
+    const ext = extForMime(await eng.editor.getMimeType(uri));
+    const relPath = `assets/${sha}.${ext}`;
+    if (!(await fs.exists(relPath))) {
+        await fs.writeFile(relPath, bytes);
+    }
+    return relPath;
+}
+/** The engine's error code when a serialized scene still carries a scheme
+ * outside `allowedResourceSchemes` (e.g. a lingering `buffer:`). */
+const DISALLOWED_SCHEMES_CODE = 'SCENE.DISALLOWED_SCHEMES';
+function isDisallowedSchemesError(err) {
+    return (err instanceof Error &&
+        err.code === DISALLOWED_SCHEMES_CODE);
+}
+/**
+ * Extract every transient (`buffer:`) resource into the content-addressed
+ * asset store and relocate it to its durable `workspace://` URI, then
+ * serialize with the shared scene-scheme allowlist (which permits `workspace`
+ * but not `buffer` — see scene-resource-schemes.ts), so a missed transient
+ * still fails loudly instead of silently persisting an unloadable scene.
+ */
+async function explodeArchiveIntoWorkspace(eng, fs) {
+    // Persist + relocate every transient, remembering each URL's workspace path.
+    const persistedByUrl = new Map();
+    for (const resource of eng.editor.findAllTransientResources()) {
+        const relPath = await persistResourceBytes(eng, fs, resource.URL);
+        persistedByUrl.set(resource.URL, relPath);
+        eng.editor.relocateResource(resource.URL, `workspace://${relPath}`);
+    }
+    try {
+        // Common case: every transient relocated cleanly, so no scheme is disallowed.
+        return await eng.scene.saveToString({
+            allowedResourceSchemes: SCENE_ALLOWED_RESOURCE_SCHEMES
+        });
+    }
+    catch (err) {
+        if (!isDisallowedSchemesError(err))
+            throw err;
+        // A duplicate-content transient survived: relocateResource no-ops when two
+        // transients share a content-addressed target (seen with duplicated fonts
+        // in premium-template archives), so the engine still serializes that
+        // straggler's buffer: URL. Retry with a drain callback that rewrites it in
+        // the OUTPUT to its already-persisted workspace:// form.
+        //
+        // Two engine constraints shape this (CE.SDK v1.77): (1) the callback MUST
+        // NOT re-enter the engine — getResourceData/getMimeType from inside it
+        // deadlocks saveToString (it holds the engine while awaiting the callback),
+        // so every straggler must be a transient we persisted above and the
+        // callback is a pure lookup; (2) we attach the callback ONLY here, on the
+        // failure path — passing onDisallowedResourceScheme when nothing is
+        // disallowed hangs saveToString.
+        const scene = await eng.scene.saveToString({
+            allowedResourceSchemes: SCENE_ALLOWED_RESOURCE_SCHEMES,
+            onDisallowedResourceScheme: async (url) => {
+                const relPath = persistedByUrl.get(url);
+                if (relPath === undefined) {
+                    // A buffer: URL we never enumerated as a transient — should not
+                    // happen; fail loudly rather than persist an unloadable scene.
+                    throw new Error(`load: cannot drain transient "${url}" — not persisted during explode.`);
+                }
+                return `workspace://${relPath}`;
+            }
+        });
+        // The drain fixed the serialized OUTPUT, but the engine still holds the
+        // un-relocatable straggler in memory — its live state now diverges from the
+        // persisted scene. `load` commits this slot warm for the next edit, so
+        // reload the drained scene to realign: reloading collapses the duplicate
+        // typeface onto its single workspace:// URI, leaving no buffer: straggler.
+        // Without this, the next edit reuses the warm slot and its plain
+        // saveToString (no drain) fails on the lingering buffer: URL.
+        await eng.scene.loadFromString(scene, false, true);
+        return scene;
+    }
+}
+/**
+ * Classify one asset URI by its scheme. Only a `buffer:` URI is genuinely
+ * `transient` (in-memory, silently lost on the next save); every scheme in
+ * SCENE_ALLOWED_RESOURCE_SCHEMES (workspace/http/https/bundle/file/…) is durable.
+ */
+function classifyUri(uri) {
+    if (uri.startsWith('workspace://'))
+        return 'workspace';
+    if (uri.startsWith('http://') || uri.startsWith('https://'))
+        return 'external';
+    if (uri.startsWith('bundle://'))
+        return 'bundle';
+    if (uri.startsWith('buffer:'))
+        return 'transient';
+    return 'other';
+}
+/**
+ * Classify every asset reference of a bare `.scene` (which carries no asset
+ * bytes) by scheme. A referenced asset does NOT reliably surface in
+ * `findAllMediaURIs()` alone: durable re-fetchable refs the engine keeps as
+ * URLs (e.g. http(s)) come back there, while anything it had to load into
+ * memory — `workspace://` (resolved via our URI resolver), `bundle://`
+ * fallbacks, and genuine `buffer:` orphans — comes back from
+ * `findAllTransientResources()` carrying its real URI. So we read BOTH lists
+ * and classify by scheme, deduped by URI.
+ *
+ * Verified against the real engine (CODE-3): after a waitForResources load a
+ * resolved `workspace://` asset appears ONLY as a transient resource (never in
+ * findAllMediaURIs), and an UNRESOLVABLE `workspace://` ref is silently dropped
+ * and substituted (e.g. a bundled fallback font) — so there is no reliable
+ * "dangling" signal to report, and no such class exists. External URLs are
+ * reported, never fetched.
+ */
+function classifyAssets(eng) {
+    const uris = new Set([
+        ...eng.editor.findAllMediaURIs(),
+        ...eng.editor.findAllTransientResources().map((r) => r.URL)
+    ]);
+    return [...uris].map((uri) => ({ uri, class: classifyUri(uri) }));
+}
+function errorResult(text) {
+    return { isError: true, content: [{ type: 'text', text }] };
+}
+export function createLoadTool(opts) {
+    const { fs, store, session, engineLock, allowPath = false, onLeafWritten, renderThumbnail } = opts;
+    return {
+        name: 'load',
+        description: DESCRIPTION,
+        inputSchema: buildLoadInputSchema(allowPath),
+        call: async (rawArgs) => {
+            const args = (rawArgs ?? {});
+            const source = args.source;
+            if (source === undefined ||
+                typeof source !== 'object' ||
+                'url' in source === 'path' in source) {
+                return errorResult('load: `source` is required — exactly one of `{ url }` or `{ path }`.');
+            }
+            if ('path' in source && !allowPath) {
+                return errorResult('load: `source.path` is not supported on this (hosted) backend. Pass a `{ url }` source instead.');
+            }
+            // Ingest bytes OUTSIDE the engine lock — network/disk I/O must not
+            // block concurrent engine work.
+            let bytes;
+            if ('url' in source) {
+                let parsed;
+                try {
+                    parsed = new URL(source.url);
+                }
+                catch {
+                    return errorResult(`load: invalid URL "${source.url}".`);
+                }
+                if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+                    return errorResult('load: `source.url` must be http(s).');
+                }
+                let resp;
+                try {
+                    resp = await fetch(source.url);
+                }
+                catch (err) {
+                    return errorResult(`load: fetching "${source.url}" failed — ${err instanceof Error ? err.message : String(err)}`);
+                }
+                if (!resp.ok) {
+                    return errorResult(`load: fetching "${source.url}" failed with HTTP ${resp.status}.`);
+                }
+                try {
+                    bytes = new Uint8Array(await resp.arrayBuffer());
+                }
+                catch (err) {
+                    return errorResult(`load: reading the response body of "${source.url}" failed — ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else {
+                try {
+                    bytes = new Uint8Array(await nodeFs.readFile(source.path));
+                }
+                catch (err) {
+                    return errorResult(`load: reading "${source.path}" failed — ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            const title = args.title ?? deriveTitle(source);
+            // The engine is loaded and mutated across several awaits — serialize
+            // against any other engine-touching tool call.
+            return engineLock.runExclusive(async () => {
+                const slot = await session.acquire(null);
+                const eng = slot.engine;
+                try {
+                    let scene;
+                    let assets;
+                    if (isZip(bytes)) {
+                        // Stage to a temp file and load via file:// — scene-level CE.SDK
+                        // has no loadFromArchive(bytes/path), only loadFromArchiveURL.
+                        const stagedDir = await nodeFs.mkdtemp(join(tmpdir(), 'codesign-load-'));
+                        const staged = join(stagedDir, 'archive.zip');
+                        try {
+                            await nodeFs.writeFile(staged, bytes);
+                            // waitForResources: the archive's bundled bytes must be fully
+                            // materialized as buffer: resources before we enumerate them.
+                            await eng.scene.loadFromArchiveURL(pathToFileURL(staged).href, false, true);
+                        }
+                        finally {
+                            await nodeFs
+                                .rm(stagedDir, { recursive: true, force: true })
+                                .catch(() => { });
+                        }
+                        scene = await explodeArchiveIntoWorkspace(eng, fs);
+                    }
+                    else {
+                        const content = new TextDecoder().decode(bytes).trim();
+                        await eng.scene.loadFromString(content, false, true);
+                        assets = classifyAssets(eng);
+                        scene = content;
+                    }
+                    const written = await store.write({ scene, parent: null, title });
+                    session.commit(slot, written.id);
+                    // Thumbnail block mirrors edit.ts — duplication is deliberate (KISS).
+                    if (renderThumbnail) {
+                        try {
+                            const thumb = await renderThumbnail({
+                                revision: written.id,
+                                engine: slot.engine
+                            });
+                            const shard = written.id.slice(0, 2);
+                            const rest = written.id.slice(2);
+                            await fs.writeFile(`exports/${shard}/${rest}/preview.webp`, thumb);
+                        }
+                        catch {
+                            // best-effort; thumbnail failure must not poison the load
+                        }
+                    }
+                    if (onLeafWritten) {
+                        // A new root is its own lineage root.
+                        await onLeafWritten({
+                            revision: written.id,
+                            rootRevision: written.id
+                        });
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    revision: written.id,
+                                    title: await store.currentTitle(written.id),
+                                    ...(assets !== undefined ? { assets } : {})
+                                })
+                            }
+                        ]
+                    };
+                }
+                catch (err) {
+                    session.markDirty(slot);
+                    return errorResult(`load: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+                }
+            });
+        }
+    };
+}
+//# sourceMappingURL=load.js.map

package/dist/tools/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/tools/load.ts"],"names":[],"mappings":"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","sourcesContent":["// packages/codesign-mcp/src/tools/load.ts\n//\n// `load` — ingest a native CE.SDK `.scene` file or `.zip` scene archive as a\n// NEW design root revision (the inverse of `save`). Archives are \"exploded\":\n// after `loadFromArchiveURL` their bundled asset bytes live in the engine as\n// ephemeral `buffer:` resources (which scene-level `saveToString` rejects —\n// the CODE-3 bug); we extract each one into the content-addressed asset store\n// (`assets/<sha>.<ext>`), relocate it to a durable `workspace://` URI, and\n// only then serialize. Bare `.scene` files carry no asset bytes: they persist\n// as-is, plus a classification report of every referenced asset URI.\n//\n// Both source variants normalize to bytes up front (fetch for `url`, disk\n// read for `path` — Local only), then dispatch on the zip magic bytes.\n// Archive bytes are staged to a temp file and loaded via a `file://` URL:\n// scene-level CE.SDK v1.77 has no `loadFromArchive(path/bytes)`, only\n// `loadFromArchiveURL`, and `file` is a first-class engine scheme.\n\nimport { promises as nodeFs } from 'node:fs';\nimport { tmpdir } from 'node:os';\nimport { join } from 'node:path';\nimport { pathToFileURL } from 'node:url';\nimport type { Mutex } from '../engine/mutex.js';\nimport { SCENE_ALLOWED_RESOURCE_SCHEMES } from '../engine/scene-resource-schemes.js';\nimport type { EngineSession } from '../engine/session.js';\nimport type { RevisionStore } from '../revisions/store.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\nimport { shortHash } from '../workspace/content-hash.js';\nimport type { WorkspaceFS } from '../workspace/types.js';\n\n/** The slice of CreativeEngine this tool touches — keeps it testable. */\ninterface MinimalLoadEngine {\n  scene: {\n    loadFromArchiveURL(\n      url: string,\n      overrideEditorConfig?: boolean,\n      waitForResources?: boolean\n    ): Promise<number>;\n    loadFromString(\n      content: string,\n      overrideEditorConfig?: boolean,\n      waitForResources?: boolean\n    ): Promise<number>;\n    saveToString(options?: {\n      allowedResourceSchemes?: string[];\n      onDisallowedResourceScheme?: (\n        url: string,\n        dataHash: string\n      ) => Promise<string>;\n    }): Promise<string>;\n  };\n  editor: {\n    findAllTransientResources(): Array<{ URL: string; size: number }>;\n    findAllMediaURIs(): string[];\n    getResourceData(\n      uri: string,\n      chunkSize: number,\n      onData: (result: Uint8Array) => boolean\n    ): void;\n    relocateResource(currentUrl: string, relocatedUrl: string): void;\n    getMimeType(uri: string): Promise<string>;\n  };\n}\n\ntype LoadSource = { url: string } | { path: string };\n\ninterface LoadArgs {\n  source: LoadSource;\n  title?: string;\n}\n\nconst DESCRIPTION = [\n  'Load a native CE.SDK design — a `.scene` file or a `.zip` scene archive (e.g. a template) — as a NEW design root revision. The inverse of `save`.',\n  '',\n  'Source: `{ url }` (http/https) or `{ path }` (absolute local file path; Local only). Archives are ingested: bundled asset bytes are extracted into the workspace as content-addressed `assets/<sha>.<ext>` files, so the loaded design is durable and behaves exactly like a natively-built one.',\n  '',\n  'Returns JSON `{ revision, title }` — continue with `edit({ parent: revision, … })`. Bare `.scene` loads additionally return `assets`: a classification of every referenced asset URI by scheme (`workspace` / `external` / `bundle` / `transient` / `other`). External URLs are NOT fetched.'\n].join('\\n');\n\n// The schema is built per-backend, like `save`'s outPath: the `{ path }`\n// source arm is advertised ONLY where local disk paths exist (Local).\n//\n// `source` is a FLAT object with optional `url`/`path` — deliberately NOT a\n// `oneOf` union. A `oneOf` here is the single construct most likely to break\n// tool calling: OpenAI bans it in strict mode, and weaker models (e.g.\n// openrouter:xiaomi/mimo-v2.5-pro, and Claude per samchon/openapi#88) serialize\n// the whole union value as an escaped JSON string, which then fails validation.\n// The \"exactly one of url/path\" invariant is enforced in `call` below, with a\n// clear error message instead of an opaque oneOf mismatch. This mirrors\n// `import`'s `source` shape. See test/tools/schema-best-practices.test.ts.\nfunction buildLoadInputSchema(allowPath: boolean) {\n  const sourceProperties: Record<string, unknown> = {\n    url: {\n      type: 'string' as const,\n      description: 'http(s) URL of a `.scene` file or `.zip` scene archive.'\n    }\n  };\n  if (allowPath) {\n    sourceProperties.path = {\n      type: 'string' as const,\n      description:\n        'Absolute local file path of a `.scene` file or `.zip` scene archive. Local-only.'\n    };\n  }\n  return {\n    type: 'object' as const,\n    properties: {\n      source: {\n        type: 'object' as const,\n        description: allowPath\n          ? 'The design to load. Provide exactly one of `url` (http/https) or `path` (absolute local file path; Local only).'\n          : 'The design to load. Provide `url` (http/https).',\n        properties: sourceProperties,\n        additionalProperties: false\n      },\n      title: {\n        type: 'string' as const,\n        description:\n          \"Display name for the new design. Defaults to the source file's basename.\"\n      }\n    },\n    required: ['source'],\n    additionalProperties: false\n  };\n}\n\n/** Standard zip local-file-header magic: PK\\x03\\x04. */\nfunction isZip(bytes: Uint8Array): boolean {\n  return (\n    bytes.length >= 4 &&\n    bytes[0] === 0x50 &&\n    bytes[1] === 0x4b &&\n    bytes[2] === 0x03 &&\n    bytes[3] === 0x04\n  );\n}\n\n/** Basename of the source, minus a `.zip`/`.scene` extension. */\nfunction deriveTitle(source: LoadSource): string | undefined {\n  let base: string;\n  if ('url' in source) {\n    const raw = new URL(source.url).pathname.split('/').pop() ?? '';\n    try {\n      base = decodeURIComponent(raw);\n    } catch {\n      base = raw; // malformed percent sequence — use the basename as-is\n    }\n  } else {\n    // Local paths are literal filenames — never percent-decode them.\n    base = source.path.split('/').pop() ?? '';\n  }\n  const name = base.replace(/\\.(zip|scene)$/i, '');\n  return name === '' ? undefined : name;\n}\n\n// Broad enough for what CE.SDK archives actually bundle (images, fonts,\n// audio/video). Unknown types get a neutral `.bin` — the workspace store and\n// the /r/ route are extension-agnostic.\nconst MIME_EXT: Record<string, string> = {\n  'image/png': 'png',\n  'image/jpeg': 'jpg',\n  'image/webp': 'webp',\n  'image/gif': 'gif',\n  'image/svg+xml': 'svg',\n  'video/mp4': 'mp4',\n  'video/quicktime': 'mov',\n  'audio/mpeg': 'mp3',\n  'audio/wav': 'wav',\n  'audio/x-wav': 'wav',\n  'audio/mp4': 'm4a',\n  'font/ttf': 'ttf',\n  'font/otf': 'otf',\n  'font/woff': 'woff',\n  'font/woff2': 'woff2',\n  'application/x-font-ttf': 'ttf',\n  'application/font-sfnt': 'ttf'\n};\n\nfunction extForMime(mime: string): string {\n  return MIME_EXT[mime] ?? 'bin';\n}\n\nfunction concatChunks(chunks: Uint8Array[]): Uint8Array {\n  const total = chunks.reduce((n, c) => n + c.byteLength, 0);\n  const out = new Uint8Array(total);\n  let offset = 0;\n  for (const c of chunks) {\n    out.set(c, offset);\n    offset += c.byteLength;\n  }\n  return out;\n}\n\n/**\n * Persist one engine resource's bytes into the content-addressed asset store\n * and return its workspace-relative path. Identical bytes land at the\n * identical path regardless of caller (automatic dedup).\n */\nasync function persistResourceBytes(\n  eng: MinimalLoadEngine,\n  fs: WorkspaceFS,\n  uri: string\n): Promise<string> {\n  const chunks: Uint8Array[] = [];\n  eng.editor.getResourceData(uri, 1 << 20, (chunk) => {\n    chunks.push(chunk.slice()); // copy — the engine may reuse the buffer\n    return true;\n  });\n  const bytes = concatChunks(chunks);\n  const sha = await shortHash(bytes);\n  const ext = extForMime(await eng.editor.getMimeType(uri));\n  const relPath = `assets/${sha}.${ext}`;\n  if (!(await fs.exists(relPath))) {\n    await fs.writeFile(relPath, bytes);\n  }\n  return relPath;\n}\n\n/** The engine's error code when a serialized scene still carries a scheme\n * outside `allowedResourceSchemes` (e.g. a lingering `buffer:`). */\nconst DISALLOWED_SCHEMES_CODE = 'SCENE.DISALLOWED_SCHEMES';\n\nfunction isDisallowedSchemesError(err: unknown): boolean {\n  return (\n    err instanceof Error &&\n    (err as Error & { code?: string }).code === DISALLOWED_SCHEMES_CODE\n  );\n}\n\n/**\n * Extract every transient (`buffer:`) resource into the content-addressed\n * asset store and relocate it to its durable `workspace://` URI, then\n * serialize with the shared scene-scheme allowlist (which permits `workspace`\n * but not `buffer` — see scene-resource-schemes.ts), so a missed transient\n * still fails loudly instead of silently persisting an unloadable scene.\n */\nasync function explodeArchiveIntoWorkspace(\n  eng: MinimalLoadEngine,\n  fs: WorkspaceFS\n): Promise<string> {\n  // Persist + relocate every transient, remembering each URL's workspace path.\n  const persistedByUrl = new Map<string, string>();\n  for (const resource of eng.editor.findAllTransientResources()) {\n    const relPath = await persistResourceBytes(eng, fs, resource.URL);\n    persistedByUrl.set(resource.URL, relPath);\n    eng.editor.relocateResource(resource.URL, `workspace://${relPath}`);\n  }\n  try {\n    // Common case: every transient relocated cleanly, so no scheme is disallowed.\n    return await eng.scene.saveToString({\n      allowedResourceSchemes: SCENE_ALLOWED_RESOURCE_SCHEMES\n    });\n  } catch (err) {\n    if (!isDisallowedSchemesError(err)) throw err;\n    // A duplicate-content transient survived: relocateResource no-ops when two\n    // transients share a content-addressed target (seen with duplicated fonts\n    // in premium-template archives), so the engine still serializes that\n    // straggler's buffer: URL. Retry with a drain callback that rewrites it in\n    // the OUTPUT to its already-persisted workspace:// form.\n    //\n    // Two engine constraints shape this (CE.SDK v1.77): (1) the callback MUST\n    // NOT re-enter the engine — getResourceData/getMimeType from inside it\n    // deadlocks saveToString (it holds the engine while awaiting the callback),\n    // so every straggler must be a transient we persisted above and the\n    // callback is a pure lookup; (2) we attach the callback ONLY here, on the\n    // failure path — passing onDisallowedResourceScheme when nothing is\n    // disallowed hangs saveToString.\n    const scene = await eng.scene.saveToString({\n      allowedResourceSchemes: SCENE_ALLOWED_RESOURCE_SCHEMES,\n      onDisallowedResourceScheme: async (url) => {\n        const relPath = persistedByUrl.get(url);\n        if (relPath === undefined) {\n          // A buffer: URL we never enumerated as a transient — should not\n          // happen; fail loudly rather than persist an unloadable scene.\n          throw new Error(\n            `load: cannot drain transient \"${url}\" — not persisted during explode.`\n          );\n        }\n        return `workspace://${relPath}`;\n      }\n    });\n    // The drain fixed the serialized OUTPUT, but the engine still holds the\n    // un-relocatable straggler in memory — its live state now diverges from the\n    // persisted scene. `load` commits this slot warm for the next edit, so\n    // reload the drained scene to realign: reloading collapses the duplicate\n    // typeface onto its single workspace:// URI, leaving no buffer: straggler.\n    // Without this, the next edit reuses the warm slot and its plain\n    // saveToString (no drain) fails on the lingering buffer: URL.\n    await eng.scene.loadFromString(scene, false, true);\n    return scene;\n  }\n}\n\ntype AssetClass = 'workspace' | 'external' | 'bundle' | 'transient' | 'other';\n\ninterface AssetReportEntry {\n  uri: string;\n  class: AssetClass;\n}\n\n/**\n * Classify one asset URI by its scheme. Only a `buffer:` URI is genuinely\n * `transient` (in-memory, silently lost on the next save); every scheme in\n * SCENE_ALLOWED_RESOURCE_SCHEMES (workspace/http/https/bundle/file/…) is durable.\n */\nfunction classifyUri(uri: string): AssetClass {\n  if (uri.startsWith('workspace://')) return 'workspace';\n  if (uri.startsWith('http://') || uri.startsWith('https://'))\n    return 'external';\n  if (uri.startsWith('bundle://')) return 'bundle';\n  if (uri.startsWith('buffer:')) return 'transient';\n  return 'other';\n}\n\n/**\n * Classify every asset reference of a bare `.scene` (which carries no asset\n * bytes) by scheme. A referenced asset does NOT reliably surface in\n * `findAllMediaURIs()` alone: durable re-fetchable refs the engine keeps as\n * URLs (e.g. http(s)) come back there, while anything it had to load into\n * memory — `workspace://` (resolved via our URI resolver), `bundle://`\n * fallbacks, and genuine `buffer:` orphans — comes back from\n * `findAllTransientResources()` carrying its real URI. So we read BOTH lists\n * and classify by scheme, deduped by URI.\n *\n * Verified against the real engine (CODE-3): after a waitForResources load a\n * resolved `workspace://` asset appears ONLY as a transient resource (never in\n * findAllMediaURIs), and an UNRESOLVABLE `workspace://` ref is silently dropped\n * and substituted (e.g. a bundled fallback font) — so there is no reliable\n * \"dangling\" signal to report, and no such class exists. External URLs are\n * reported, never fetched.\n */\nfunction classifyAssets(eng: MinimalLoadEngine): AssetReportEntry[] {\n  const uris = new Set<string>([\n    ...eng.editor.findAllMediaURIs(),\n    ...eng.editor.findAllTransientResources().map((r) => r.URL)\n  ]);\n  return [...uris].map((uri) => ({ uri, class: classifyUri(uri) }));\n}\n\nfunction errorResult(text: string): {\n  isError: true;\n  content: Array<{ type: 'text'; text: string }>;\n} {\n  return { isError: true, content: [{ type: 'text' as const, text }] };\n}\n\nexport interface CreateLoadToolOptions<E = unknown> {\n  fs: WorkspaceFS;\n  store: RevisionStore;\n  session: EngineSession<E>;\n  /** Guards the shared engine — load-then-explode must not interleave with another engine-touching call. */\n  engineLock: Mutex;\n  /** Whether to honour a `{ path }` source (Local: yes; Hosted/sandbox: no). */\n  allowPath?: boolean;\n  /** Called after the new root revision is written (viewer SSE hook). */\n  onLeafWritten?: (event: {\n    revision: string;\n    rootRevision: string;\n  }) => void | Promise<void>;\n  /** Render a thumbnail for the new revision. Best-effort: failures are swallowed. */\n  renderThumbnail?: (event: {\n    revision: string;\n    engine: E;\n  }) => Promise<Uint8Array>;\n}\n\nexport function createLoadTool<E = unknown>(\n  opts: CreateLoadToolOptions<E>\n): CodesignMcpToolRegistration {\n  const {\n    fs,\n    store,\n    session,\n    engineLock,\n    allowPath = false,\n    onLeafWritten,\n    renderThumbnail\n  } = opts;\n  return {\n    name: 'load',\n    description: DESCRIPTION,\n    inputSchema: buildLoadInputSchema(allowPath),\n    call: async (rawArgs) => {\n      const args = (rawArgs ?? {}) as Partial<LoadArgs>;\n      const source = args.source;\n      if (\n        source === undefined ||\n        typeof source !== 'object' ||\n        'url' in source === 'path' in source\n      ) {\n        return errorResult(\n          'load: `source` is required — exactly one of `{ url }` or `{ path }`.'\n        );\n      }\n      if ('path' in source && !allowPath) {\n        return errorResult(\n          'load: `source.path` is not supported on this (hosted) backend. Pass a `{ url }` source instead.'\n        );\n      }\n      // Ingest bytes OUTSIDE the engine lock — network/disk I/O must not\n      // block concurrent engine work.\n      let bytes: Uint8Array;\n      if ('url' in source) {\n        let parsed: URL;\n        try {\n          parsed = new URL(source.url);\n        } catch {\n          return errorResult(`load: invalid URL \"${source.url}\".`);\n        }\n        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {\n          return errorResult('load: `source.url` must be http(s).');\n        }\n        let resp: Response;\n        try {\n          resp = await fetch(source.url);\n        } catch (err) {\n          return errorResult(\n            `load: fetching \"${source.url}\" failed — ${\n              err instanceof Error ? err.message : String(err)\n            }`\n          );\n        }\n        if (!resp.ok) {\n          return errorResult(\n            `load: fetching \"${source.url}\" failed with HTTP ${resp.status}.`\n          );\n        }\n        try {\n          bytes = new Uint8Array(await resp.arrayBuffer());\n        } catch (err) {\n          return errorResult(\n            `load: reading the response body of \"${source.url}\" failed — ${\n              err instanceof Error ? err.message : String(err)\n            }`\n          );\n        }\n      } else {\n        try {\n          bytes = new Uint8Array(await nodeFs.readFile(source.path));\n        } catch (err) {\n          return errorResult(\n            `load: reading \"${source.path}\" failed — ${\n              err instanceof Error ? err.message : String(err)\n            }`\n          );\n        }\n      }\n      const title = args.title ?? deriveTitle(source);\n      // The engine is loaded and mutated across several awaits — serialize\n      // against any other engine-touching tool call.\n      return engineLock.runExclusive(async () => {\n        const slot = await session.acquire(null);\n        const eng = slot.engine as MinimalLoadEngine;\n        try {\n          let scene: string;\n          let assets: AssetReportEntry[] | undefined;\n          if (isZip(bytes)) {\n            // Stage to a temp file and load via file:// — scene-level CE.SDK\n            // has no loadFromArchive(bytes/path), only loadFromArchiveURL.\n            const stagedDir = await nodeFs.mkdtemp(\n              join(tmpdir(), 'codesign-load-')\n            );\n            const staged = join(stagedDir, 'archive.zip');\n            try {\n              await nodeFs.writeFile(staged, bytes);\n              // waitForResources: the archive's bundled bytes must be fully\n              // materialized as buffer: resources before we enumerate them.\n              await eng.scene.loadFromArchiveURL(\n                pathToFileURL(staged).href,\n                false,\n                true\n              );\n            } finally {\n              await nodeFs\n                .rm(stagedDir, { recursive: true, force: true })\n                .catch(() => {});\n            }\n            scene = await explodeArchiveIntoWorkspace(eng, fs);\n          } else {\n            const content = new TextDecoder().decode(bytes).trim();\n            await eng.scene.loadFromString(content, false, true);\n            assets = classifyAssets(eng);\n            scene = content;\n          }\n          const written = await store.write({ scene, parent: null, title });\n          session.commit(slot, written.id);\n          // Thumbnail block mirrors edit.ts — duplication is deliberate (KISS).\n          if (renderThumbnail) {\n            try {\n              const thumb = await renderThumbnail({\n                revision: written.id,\n                engine: slot.engine\n              });\n              const shard = written.id.slice(0, 2);\n              const rest = written.id.slice(2);\n              await fs.writeFile(\n                `exports/${shard}/${rest}/preview.webp`,\n                thumb\n              );\n            } catch {\n              // best-effort; thumbnail failure must not poison the load\n            }\n          }\n          if (onLeafWritten) {\n            // A new root is its own lineage root.\n            await onLeafWritten({\n              revision: written.id,\n              rootRevision: written.id\n            });\n          }\n          return {\n            content: [\n              {\n                type: 'text' as const,\n                text: JSON.stringify({\n                  revision: written.id,\n                  title: await store.currentTitle(written.id),\n                  ...(assets !== undefined ? { assets } : {})\n                })\n              }\n            ]\n          };\n        } catch (err) {\n          session.markDirty(slot);\n          return errorResult(\n            `load: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`\n          );\n        }\n      });\n    }\n  };\n}\n"]}