@imgly/codesign-mcp 0.1.0

package/dist/tools/asset-search.js

@@ -0,0 +1,120 @@
+// packages/codesign-mcp/src/tools/asset-search.ts
+//
+// `asset_search` — read-only discovery over the engine's asset sources.
+// Asset sources are registered on the engine *instance*, not the scene, so
+// the tool takes no `revision`/`parent` and never commits anything. Applying
+// a found asset to the scene stays inside `edit` code (see the handbook's
+// asset-sources section) — `edit` remains the single mutating,
+// revision-committing tool.
+const DEFAULT_PER_PAGE = 20;
+const MAX_PER_PAGE = 50;
+const DESCRIPTION = [
+    'Discover the asset sources registered on the CreativeEngine and search the assets they contain. Read-only — never creates a revision.',
+    '',
+    'Without `sourceId`: lists every source id with its supported MIME types.',
+    '',
+    'With `sourceId`: returns one page of assets as JSON `{ total, currentPage, nextPage, assets: [{ id, label, groups, uri, thumbUri, width, height }] }`. `query` fuzzy-matches labels and tags.',
+    '',
+    'To USE a result, apply it inside `edit` code (see the handbook): re-find it with `engine.asset.findAssets(sourceId, { query, page: 0, perPage: 1 })`, then `engine.asset.apply(sourceId, result.assets[0])` to create a new block — or set an image fill on an existing block manually. Do NOT use `engine.asset.applyToBlock` (silent no-op on this server).'
+].join('\n');
+const INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        sourceId: {
+            type: 'string',
+            description: 'Asset source id. Omit to list all sources.'
+        },
+        query: {
+            type: 'string',
+            description: 'Fuzzy search over asset labels and tags.'
+        },
+        page: {
+            type: 'integer',
+            minimum: 0,
+            description: 'Page index. Default 0.'
+        },
+        perPage: {
+            type: 'integer',
+            minimum: 1,
+            description: 'Results per page. Default 20, max 50.'
+        }
+    },
+    additionalProperties: false
+};
+export function createAssetSearchTool(opts) {
+    const { session, engineLock } = opts;
+    return {
+        name: 'asset_search',
+        description: DESCRIPTION,
+        inputSchema: INPUT_SCHEMA,
+        call: async (rawArgs) => {
+            const args = (rawArgs ?? {});
+            return engineLock.runExclusive(async () => {
+                // Asset sources hang off the engine instance, not the loaded scene:
+                // any slot will do. acquire(null) resets the scene, which is safe
+                // here because it only runs when no slot is warm (nothing to lose).
+                const slot = session.currentSlot() ?? (await session.acquire(null));
+                const engine = slot.engine;
+                const sources = engine.asset.findAllSources();
+                if (args.sourceId === undefined) {
+                    const body = {
+                        sources: sources.map((id) => ({
+                            id,
+                            supportedMimeTypes: engine.asset.getSupportedMimeTypes(id)
+                        }))
+                    };
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(body) }]
+                    };
+                }
+                if (!sources.includes(args.sourceId)) {
+                    return {
+                        isError: true,
+                        content: [
+                            {
+                                type: 'text',
+                                text: `asset_search: unknown sourceId "${args.sourceId}". Registered sources: ${sources.join(', ')}`
+                            }
+                        ]
+                    };
+                }
+                try {
+                    const result = await engine.asset.findAssets(args.sourceId, {
+                        ...(args.query !== undefined ? { query: args.query } : {}),
+                        page: Math.max(0, args.page ?? 0),
+                        perPage: Math.max(1, Math.min(args.perPage ?? DEFAULT_PER_PAGE, MAX_PER_PAGE))
+                    });
+                    const body = {
+                        total: result.total,
+                        currentPage: result.currentPage,
+                        nextPage: result.nextPage,
+                        assets: result.assets.map((a) => ({
+                            id: a.id,
+                            label: a.label,
+                            groups: a.groups,
+                            uri: a.meta?.uri,
+                            thumbUri: a.meta?.thumbUri,
+                            width: a.meta?.width,
+                            height: a.meta?.height
+                        }))
+                    };
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(body) }]
+                    };
+                }
+                catch (err) {
+                    return {
+                        isError: true,
+                        content: [
+                            {
+                                type: 'text',
+                                text: `asset_search: findAssets failed — ${err instanceof Error ? err.message : String(err)}. The scene was not touched.`
+                            }
+                        ]
+                    };
+                }
+            });
+        }
+    };
+}
+//# sourceMappingURL=asset-search.js.map

package/dist/tools/asset-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-search.js","sourceRoot":"","sources":["../../src/tools/asset-search.ts"],"names":[],"mappings":"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","sourcesContent":["// packages/codesign-mcp/src/tools/asset-search.ts\n//\n// `asset_search` — read-only discovery over the engine's asset sources.\n// Asset sources are registered on the engine *instance*, not the scene, so\n// the tool takes no `revision`/`parent` and never commits anything. Applying\n// a found asset to the scene stays inside `edit` code (see the handbook's\n// asset-sources section) — `edit` remains the single mutating,\n// revision-committing tool.\n\nimport type { Mutex } from '../engine/mutex.js';\nimport type { EngineSession } from '../engine/session.js';\nimport type { CodesignMcpToolRegistration } from '../server.js';\n\nconst DEFAULT_PER_PAGE = 20;\nconst MAX_PER_PAGE = 50;\n\n/** The slice of CreativeEngine.asset this tool needs — keeps tests fake-able. */\ninterface AssetEngine {\n  asset: {\n    findAllSources(): string[];\n    getSupportedMimeTypes(sourceId: string): string[];\n    findAssets(\n      sourceId: string,\n      query: { query?: string; page: number; perPage: number }\n    ): Promise<{\n      assets: Array<{\n        id: string;\n        label?: string;\n        groups?: string[];\n        meta?: Record<string, unknown>;\n      }>;\n      currentPage: number;\n      nextPage?: number;\n      total: number;\n    }>;\n  };\n}\n\ninterface AssetSearchArgs {\n  sourceId?: string;\n  query?: string;\n  page?: number;\n  perPage?: number;\n}\n\nconst DESCRIPTION = [\n  'Discover the asset sources registered on the CreativeEngine and search the assets they contain. Read-only — never creates a revision.',\n  '',\n  'Without `sourceId`: lists every source id with its supported MIME types.',\n  '',\n  'With `sourceId`: returns one page of assets as JSON `{ total, currentPage, nextPage, assets: [{ id, label, groups, uri, thumbUri, width, height }] }`. `query` fuzzy-matches labels and tags.',\n  '',\n  'To USE a result, apply it inside `edit` code (see the handbook): re-find it with `engine.asset.findAssets(sourceId, { query, page: 0, perPage: 1 })`, then `engine.asset.apply(sourceId, result.assets[0])` to create a new block — or set an image fill on an existing block manually. Do NOT use `engine.asset.applyToBlock` (silent no-op on this server).'\n].join('\\n');\n\nconst INPUT_SCHEMA = {\n  type: 'object' as const,\n  properties: {\n    sourceId: {\n      type: 'string' as const,\n      description: 'Asset source id. Omit to list all sources.'\n    },\n    query: {\n      type: 'string' as const,\n      description: 'Fuzzy search over asset labels and tags.'\n    },\n    page: {\n      type: 'integer' as const,\n      minimum: 0,\n      description: 'Page index. Default 0.'\n    },\n    perPage: {\n      type: 'integer' as const,\n      minimum: 1,\n      description: 'Results per page. Default 20, max 50.'\n    }\n  },\n  additionalProperties: false\n};\n\nexport interface CreateAssetSearchToolOptions<E = unknown> {\n  session: EngineSession<E>;\n  /** Guards the shared engine — findAssets must not interleave with an edit's load-mutate-save sequence (see engine/mutex.ts). */\n  engineLock: Mutex;\n}\n\nexport function createAssetSearchTool<E = unknown>(\n  opts: CreateAssetSearchToolOptions<E>\n): CodesignMcpToolRegistration {\n  const { session, engineLock } = opts;\n  return {\n    name: 'asset_search',\n    description: DESCRIPTION,\n    inputSchema: INPUT_SCHEMA,\n    call: async (rawArgs) => {\n      const args = (rawArgs ?? {}) as AssetSearchArgs;\n      return engineLock.runExclusive(async () => {\n        // Asset sources hang off the engine instance, not the loaded scene:\n        // any slot will do. acquire(null) resets the scene, which is safe\n        // here because it only runs when no slot is warm (nothing to lose).\n        const slot = session.currentSlot() ?? (await session.acquire(null));\n        const engine = slot.engine as AssetEngine;\n        const sources = engine.asset.findAllSources();\n        if (args.sourceId === undefined) {\n          const body = {\n            sources: sources.map((id) => ({\n              id,\n              supportedMimeTypes: engine.asset.getSupportedMimeTypes(id)\n            }))\n          };\n          return {\n            content: [{ type: 'text' as const, text: JSON.stringify(body) }]\n          };\n        }\n        if (!sources.includes(args.sourceId)) {\n          return {\n            isError: true,\n            content: [\n              {\n                type: 'text' as const,\n                text: `asset_search: unknown sourceId \"${args.sourceId}\". Registered sources: ${sources.join(', ')}`\n              }\n            ]\n          };\n        }\n        try {\n          const result = await engine.asset.findAssets(args.sourceId, {\n            ...(args.query !== undefined ? { query: args.query } : {}),\n            page: Math.max(0, args.page ?? 0),\n            perPage: Math.max(\n              1,\n              Math.min(args.perPage ?? DEFAULT_PER_PAGE, MAX_PER_PAGE)\n            )\n          });\n          const body = {\n            total: result.total,\n            currentPage: result.currentPage,\n            nextPage: result.nextPage,\n            assets: result.assets.map((a) => ({\n              id: a.id,\n              label: a.label,\n              groups: a.groups,\n              uri: a.meta?.uri,\n              thumbUri: a.meta?.thumbUri,\n              width: a.meta?.width,\n              height: a.meta?.height\n            }))\n          };\n          return {\n            content: [{ type: 'text' as const, text: JSON.stringify(body) }]\n          };\n        } catch (err) {\n          return {\n            isError: true,\n            content: [\n              {\n                type: 'text' as const,\n                text: `asset_search: findAssets failed — ${\n                  err instanceof Error ? err.message : String(err)\n                }. The scene was not touched.`\n              }\n            ]\n          };\n        }\n      });\n    }\n  };\n}\n"]}

package/dist/tools/content-types.d.ts

@@ -0,0 +1,11 @@
+export interface TextContent {
+    type: 'text';
+    text: string;
+}
+export interface ImageContent {
+    type: 'image';
+    /** base64-encoded image bytes. */
+    data: string;
+    mimeType: string;
+}
+//# sourceMappingURL=content-types.d.ts.map

package/dist/tools/content-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-types.d.ts","sourceRoot":"","sources":["../../src/tools/content-types.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/dist/tools/content-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=content-types.js.map

package/dist/tools/content-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-types.js","sourceRoot":"","sources":["../../src/tools/content-types.ts"],"names":[],"mappings":"","sourcesContent":["// Local replacements for @mariozechner/pi-ai's TextContent / ImageContent.\n// Only the fields codesign-mcp constructs and reads are modeled here.\nexport interface TextContent {\n  type: 'text';\n  text: string;\n}\n\nexport interface ImageContent {\n  type: 'image';\n  /** base64-encoded image bytes. */\n  data: string;\n  mimeType: string;\n}\n"]}

package/dist/tools/edit.d.ts

@@ -0,0 +1,29 @@
+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 CreateEditToolOptions<E = unknown> {
+    store: RevisionStore;
+    session: EngineSession<E>;
+    /**
+     * Guards the shared engine. The acquire → run code → save → thumbnail
+     * sequence below mutates one engine across several awaits; this serializes
+     * it against any other engine-touching tool call (see engine/mutex.ts).
+     */
+    engineLock: Mutex;
+    /** Called after a successful edit writes a new leaf revision. */
+    onLeafWritten?: (event: {
+        revision: string;
+        rootRevision: string;
+    }) => void | Promise<void>;
+    /** Render a thumbnail for the newly committed revision. Best-effort: failures are swallowed. */
+    renderThumbnail?: (event: {
+        revision: string;
+        engine: E;
+    }) => Promise<Uint8Array>;
+    /** Workspace FS for persisting the thumbnail (required if renderThumbnail is supplied). */
+    fs?: WorkspaceFS;
+}
+export declare function createEditTool<E = unknown>(opts: CreateEditToolOptions<E>): CodesignMcpToolRegistration;
+//# sourceMappingURL=edit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../src/tools/edit.ts"],"names":[],"mappings":"AAcA,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,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,MAAM,WAAW,qBAAqB,CAAC,CAAC,GAAG,OAAO;IAChD,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B;;;;OAIG;IACH,UAAU,EAAE,KAAK,CAAC;IAClB,iEAAiE;IACjE,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,gGAAgG;IAChG,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,CAAC,CAAC;KACX,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1B,2FAA2F;IAC3F,EAAE,CAAC,EAAE,WAAW,CAAC;CAClB;AAiDD,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EACxC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC7B,2BAA2B,CA2H7B"}

package/dist/tools/edit.js

@@ -0,0 +1,165 @@
+// packages/codesign-mcp/src/tools/edit.ts
+//
+// `edit` — the spec's central tool (§6.1). Replaces `exec.ts`. Differences
+// from the POC `exec`:
+//   - `parent` is mandatory (null = new design root).
+//   - `title?` set on root creation; `note?` annotates this revision.
+//   - Writes a new revision via RevisionStore after `code` returns.
+//   - Reloads engine if session slot's currentRevision !== parent.
+//   - Dirty-on-throw: failed code marks the slot dirty.
+//   - Returns {revision, parent} JSON as the first MessagePart (text).
+//
+// `onLeafWritten` is the viewer hook: called after a successful write so the
+// SSE broadcaster can fan out the new revision id to subscribed viewers.
+import { normalizeResult } from './result.js';
+const DESCRIPTION = [
+    'Edit the CE.SDK canvas by running JavaScript against the live CreativeEngine, then commit the result as a new revision.',
+    '',
+    '⚠ Call `handbook` BEFORE your first `edit`. It documents the mandatory `parent` argument, the dirty-on-throw safety contract, the typeface schema, and the runtime quirks.',
+    '',
+    "REQUIRED: `parent` is a revision id (returned by a previous edit), or the JSON null literal (no quotes) to start a new design. Omitting it is an error — there is no implicit 'continue from wherever'.",
+    '',
+    'Returns: the first content part is JSON `{ revision, parent }` — store `revision` so you can pass it as `parent` on the next edit.',
+    '',
+    "Optional: `title` (set on parent=null only — the design's display name) and `note` (a one-liner describing what this edit accomplished — purely descriptive, helps you re-ground after a rewind)."
+].join('\n');
+const EDIT_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        parent: {
+            oneOf: [{ type: 'string' }, { type: 'null' }],
+            description: 'Parent revision id (string), or the JSON null literal (no quotes — the value null, not the four-character string "null") for a new design root. REQUIRED — there is no implicit default.'
+        },
+        code: {
+            type: 'string',
+            description: 'Async JS body. `engine` is in scope. Strict return contract per the handbook.'
+        },
+        title: {
+            type: 'string',
+            description: 'Display name for the design. Set only when parent=null (creating a new design). For mid-chain renames use the `rename` tool.'
+        },
+        note: {
+            type: 'string',
+            description: 'Freeform descriptive text — what this edit accomplished. Metadata only; never load-bearing.'
+        }
+    },
+    required: ['parent', 'code'],
+    additionalProperties: false
+};
+export function createEditTool(opts) {
+    const { store, session, onLeafWritten, renderThumbnail, fs, engineLock } = opts;
+    return {
+        name: 'edit',
+        description: DESCRIPTION,
+        inputSchema: EDIT_INPUT_SCHEMA,
+        call: async (rawArgs) => {
+            const args = (rawArgs ?? {});
+            if (!Object.hasOwn(args, 'parent')) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'edit: `parent` is required. Pass the revision id from a previous edit, or the JSON null literal (no quotes) for a new design root. See `handbook` for the rewind-recovery flow.'
+                        }
+                    ]
+                };
+            }
+            if (args.parent === 'null') {
+                // LLMs sometimes serialize JSON null as the string "null" when the
+                // description mentions null in backticks. Catch it explicitly so
+                // the agent gets a teaching message instead of "unknown revision".
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'edit: `parent` arrived as the four-character string "null" (with quotes). Pass JSON null (the literal, no quotes) to create a new design root.'
+                        }
+                    ]
+                };
+            }
+            if (typeof args.code !== 'string') {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'edit: `code` (string) is required.'
+                        }
+                    ]
+                };
+            }
+            // The shared engine is loaded, mutated by user code, then saved across
+            // several awaits below. Serialize the whole sequence so a concurrent
+            // session sharing this engine can't swap the scene out mid-edit.
+            return engineLock.runExclusive(async () => {
+                // Pre-stage scene bytes for the session if parent is non-null.
+                if (args.parent !== null) {
+                    const parentRev = await store.read(args.parent);
+                    await session.populate(args.parent, parentRev.scene);
+                }
+                const slot = await session.acquire(args.parent ?? null);
+                let codeResult;
+                try {
+                    const AsyncFunction = Object.getPrototypeOf(async () => { }).constructor;
+                    const fn = new AsyncFunction('engine', args.code);
+                    codeResult = await fn(slot.engine);
+                }
+                catch (err) {
+                    session.markDirty(slot);
+                    return {
+                        isError: true,
+                        content: [
+                            {
+                                type: 'text',
+                                text: `edit: code threw — engine slot marked dirty (next edit pays one reload). ${err instanceof Error
+                                    ? (err.stack ?? err.message)
+                                    : String(err)}`
+                            }
+                        ]
+                    };
+                }
+                const adapter = session.opts.adapter;
+                const sceneBytes = await adapter.saveToString(slot.engine);
+                const written = await store.write({
+                    scene: sceneBytes,
+                    parent: args.parent ?? null,
+                    title: args.title,
+                    note: args.note,
+                    code: args.code
+                });
+                session.commit(slot, written.id);
+                if (renderThumbnail && fs) {
+                    try {
+                        const bytes = 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`, bytes);
+                    }
+                    catch {
+                        // best-effort; thumbnail failure must not poison the edit success path
+                    }
+                }
+                if (onLeafWritten) {
+                    const rootRevision = args.parent === null
+                        ? written.id
+                        : (await store.historyOf(written.id))[0].id;
+                    await onLeafWritten({ revision: written.id, rootRevision });
+                }
+                const envelope = { revision: written.id, parent: args.parent ?? null };
+                const codeParts = normalizeResult(codeResult);
+                return {
+                    content: [
+                        { type: 'text', text: JSON.stringify(envelope) },
+                        ...codeParts
+                    ]
+                };
+            });
+        }
+    };
+}
+//# sourceMappingURL=edit.js.map

package/dist/tools/edit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit.js","sourceRoot":"","sources":["../../src/tools/edit.ts"],"names":[],"mappings":"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","sourcesContent":["// packages/codesign-mcp/src/tools/edit.ts\n//\n// `edit` — the spec's central tool (§6.1). Replaces `exec.ts`. Differences\n// from the POC `exec`:\n//   - `parent` is mandatory (null = new design root).\n//   - `title?` set on root creation; `note?` annotates this revision.\n//   - Writes a new revision via RevisionStore after `code` returns.\n//   - Reloads engine if session slot's currentRevision !== parent.\n//   - Dirty-on-throw: failed code marks the slot dirty.\n//   - Returns {revision, parent} JSON as the first MessagePart (text).\n//\n// `onLeafWritten` is the viewer hook: called after a successful write so the\n// SSE broadcaster can fan out the new revision id to subscribed viewers.\n\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 { WorkspaceFS } from '../workspace/types.js';\nimport { normalizeResult } from './result.js';\n\nexport interface CreateEditToolOptions<E = unknown> {\n  store: RevisionStore;\n  session: EngineSession<E>;\n  /**\n   * Guards the shared engine. The acquire → run code → save → thumbnail\n   * sequence below mutates one engine across several awaits; this serializes\n   * it against any other engine-touching tool call (see engine/mutex.ts).\n   */\n  engineLock: Mutex;\n  /** Called after a successful edit writes a new leaf revision. */\n  onLeafWritten?: (event: {\n    revision: string;\n    rootRevision: string;\n  }) => void | Promise<void>;\n  /** Render a thumbnail for the newly committed revision. Best-effort: failures are swallowed. */\n  renderThumbnail?: (event: {\n    revision: string;\n    engine: E;\n  }) => Promise<Uint8Array>;\n  /** Workspace FS for persisting the thumbnail (required if renderThumbnail is supplied). */\n  fs?: WorkspaceFS;\n}\n\nconst DESCRIPTION = [\n  'Edit the CE.SDK canvas by running JavaScript against the live CreativeEngine, then commit the result as a new revision.',\n  '',\n  '⚠ Call `handbook` BEFORE your first `edit`. It documents the mandatory `parent` argument, the dirty-on-throw safety contract, the typeface schema, and the runtime quirks.',\n  '',\n  \"REQUIRED: `parent` is a revision id (returned by a previous edit), or the JSON null literal (no quotes) to start a new design. Omitting it is an error — there is no implicit 'continue from wherever'.\",\n  '',\n  'Returns: the first content part is JSON `{ revision, parent }` — store `revision` so you can pass it as `parent` on the next edit.',\n  '',\n  \"Optional: `title` (set on parent=null only — the design's display name) and `note` (a one-liner describing what this edit accomplished — purely descriptive, helps you re-ground after a rewind).\"\n].join('\\n');\n\ninterface EditArgs {\n  parent: string | null;\n  code: string;\n  title?: string;\n  note?: string;\n}\n\nconst EDIT_INPUT_SCHEMA = {\n  type: 'object' as const,\n  properties: {\n    parent: {\n      oneOf: [{ type: 'string' as const }, { type: 'null' as const }],\n      description:\n        'Parent revision id (string), or the JSON null literal (no quotes — the value null, not the four-character string \"null\") for a new design root. REQUIRED — there is no implicit default.'\n    },\n    code: {\n      type: 'string' as const,\n      description:\n        'Async JS body. `engine` is in scope. Strict return contract per the handbook.'\n    },\n    title: {\n      type: 'string' as const,\n      description:\n        'Display name for the design. Set only when parent=null (creating a new design). For mid-chain renames use the `rename` tool.'\n    },\n    note: {\n      type: 'string' as const,\n      description:\n        'Freeform descriptive text — what this edit accomplished. Metadata only; never load-bearing.'\n    }\n  },\n  required: ['parent', 'code'],\n  additionalProperties: false\n};\n\nexport function createEditTool<E = unknown>(\n  opts: CreateEditToolOptions<E>\n): CodesignMcpToolRegistration {\n  const { store, session, onLeafWritten, renderThumbnail, fs, engineLock } =\n    opts;\n  return {\n    name: 'edit',\n    description: DESCRIPTION,\n    inputSchema: EDIT_INPUT_SCHEMA,\n    call: async (rawArgs) => {\n      const args = (rawArgs ?? {}) as Partial<EditArgs>;\n      if (!Object.hasOwn(args, 'parent')) {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: 'edit: `parent` is required. Pass the revision id from a previous edit, or the JSON null literal (no quotes) for a new design root. See `handbook` for the rewind-recovery flow.'\n            }\n          ]\n        };\n      }\n      if (args.parent === 'null') {\n        // LLMs sometimes serialize JSON null as the string \"null\" when the\n        // description mentions null in backticks. Catch it explicitly so\n        // the agent gets a teaching message instead of \"unknown revision\".\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: 'edit: `parent` arrived as the four-character string \"null\" (with quotes). Pass JSON null (the literal, no quotes) to create a new design root.'\n            }\n          ]\n        };\n      }\n      if (typeof args.code !== 'string') {\n        return {\n          isError: true,\n          content: [\n            {\n              type: 'text' as const,\n              text: 'edit: `code` (string) is required.'\n            }\n          ]\n        };\n      }\n      // The shared engine is loaded, mutated by user code, then saved across\n      // several awaits below. Serialize the whole sequence so a concurrent\n      // session sharing this engine can't swap the scene out mid-edit.\n      return engineLock.runExclusive(async () => {\n        // Pre-stage scene bytes for the session if parent is non-null.\n        if (args.parent !== null) {\n          const parentRev = await store.read(args.parent as string);\n          await session.populate(args.parent as string, parentRev.scene);\n        }\n        const slot = await session.acquire(args.parent ?? null);\n        let codeResult: unknown;\n        try {\n          const AsyncFunction = Object.getPrototypeOf(\n            async () => {}\n          ).constructor;\n          const fn = new AsyncFunction('engine', args.code);\n          codeResult = await fn(slot.engine);\n        } catch (err) {\n          session.markDirty(slot);\n          return {\n            isError: true,\n            content: [\n              {\n                type: 'text' as const,\n                text: `edit: code threw — engine slot marked dirty (next edit pays one reload). ${\n                  err instanceof Error\n                    ? (err.stack ?? err.message)\n                    : String(err)\n                }`\n              }\n            ]\n          };\n        }\n        const adapter = (\n          session as unknown as {\n            opts: { adapter: { saveToString(e: E): Promise<string> } };\n          }\n        ).opts.adapter;\n        const sceneBytes = await adapter.saveToString(slot.engine);\n        const written = await store.write({\n          scene: sceneBytes,\n          parent: args.parent ?? null,\n          title: args.title,\n          note: args.note,\n          code: args.code\n        });\n        session.commit(slot, written.id);\n        if (renderThumbnail && fs) {\n          try {\n            const bytes = 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(`exports/${shard}/${rest}/preview.webp`, bytes);\n          } catch {\n            // best-effort; thumbnail failure must not poison the edit success path\n          }\n        }\n        if (onLeafWritten) {\n          const rootRevision =\n            args.parent === null\n              ? written.id\n              : (await store.historyOf(written.id))[0].id;\n          await onLeafWritten({ revision: written.id, rootRevision });\n        }\n        const envelope = { revision: written.id, parent: args.parent ?? null };\n        const codeParts = normalizeResult(codeResult);\n        return {\n          content: [\n            { type: 'text' as const, text: JSON.stringify(envelope) },\n            ...codeParts\n          ]\n        };\n      });\n    }\n  };\n}\n"]}

package/dist/tools/engine.d.ts

@@ -0,0 +1,31 @@
+import type CreativeEngine from '@cesdk/engine';
+/**
+ * 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.
+ *
+ * Both `@cesdk/node` (WASM) and `@cesdk/node-native` (N-API) are loaded through
+ * `createRequire` (CJS-shaped) rather than ESM dynamic import. `@cesdk/node`'s
+ * emscripten/wasm runtime spawns Workers that resolve relative to the package's
+ * `__dirname`; ESM dynamic import + vitest pre-bundling break that path with
+ * `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).
+ */
+export declare function ensureHeadlessEngine(license: string): Promise<CreativeEngine>;
+//# sourceMappingURL=engine.d.ts.map

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

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

package/dist/tools/engine.js

@@ -0,0 +1,59 @@
+let cached;
+/**
+ * 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.
+ *
+ * Both `@cesdk/node` (WASM) and `@cesdk/node-native` (N-API) are loaded through
+ * `createRequire` (CJS-shaped) rather than ESM dynamic import. `@cesdk/node`'s
+ * emscripten/wasm runtime spawns Workers that resolve relative to the package's
+ * `__dirname`; ESM dynamic import + vitest pre-bundling break that path with
+ * `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).
+ */
+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 });
+            // 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
+            // starts in Pixel — the agent never has to remember.
+            const origCreate = engine.scene.create.bind(engine.scene);
+            engine.scene.create =
+                ((layout) => {
+                    const sceneId = origCreate(layout);
+                    // @cesdk/node setDesignUnit takes only the unit; it operates on
+                    // the current scene, which is the one create() just returned.
+                    engine.scene.setDesignUnit('Pixel');
+                    return sceneId;
+                });
+            return engine;
+        })();
+    }
+    return cached;
+}
+//# sourceMappingURL=engine.js.map

package/dist/tools/engine.js.map

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

package/dist/tools/export.d.ts

@@ -0,0 +1,19 @@
+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 { ViewerUrlBuilder } from '../viewer/url-builder.js';
+import type { WorkspaceFS } from '../workspace/types.js';
+export interface CreateExportToolOptions<E = unknown> {
+    fs: WorkspaceFS;
+    store: RevisionStore;
+    session: EngineSession<E>;
+    /** Builds the `httpUrl` for workspace-written artifacts (the `/r/` route). */
+    urlBuilder: ViewerUrlBuilder;
+    /** Whether to honour an `outPath` argument (Local: yes; Hosted/sandbox: no). */
+    allowOutPath?: boolean;
+    /** Guards the shared engine — load-then-export must not interleave with another session's edit (see engine/mutex.ts). */
+    engineLock: Mutex;
+}
+export declare function createExportTool<E = unknown>(opts: CreateExportToolOptions<E>): CodesignMcpToolRegistration;
+//# sourceMappingURL=export.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/tools/export.ts"],"names":[],"mappings":"AAYA,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;AAoEzD,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;CACnB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1C,IAAI,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAC/B,2BAA2B,CAgI7B"}