@imgly/codesign-mcp 0.1.5 → 0.1.7

package/dist/tools/export.js

@@ -10,6 +10,8 @@
 // `target=video` is deferred to Phase 4.
 import { promises as nodeFs } from 'node:fs';
 import { dirname } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { NOOP_TELEMETRY_SINK, SpanRecorder, summarizeResult, toErrorShape } from './spans.js';
 const TARGET_MIME = {
     pdf: { pdf: 'application/pdf' },
     image: { png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp' }
@@ -57,122 +59,158 @@ function buildExportInputSchema(allowOutPath) {
 }
 export function createExportTool(opts) {
     const { fs, store, session, urlBuilder, allowOutPath = false, engineLock } = opts;
+    const telemetry = opts.telemetry ?? NOOP_TELEMETRY_SINK;
     return {
         name: 'export',
         description: DESCRIPTION,
         inputSchema: buildExportInputSchema(allowOutPath),
         call: async (rawArgs) => {
-            const args = (rawArgs ?? {});
-            if (typeof args.target !== 'string' ||
-                typeof args.format !== 'string' ||
-                typeof args.revision !== 'string') {
-                return {
-                    isError: true,
-                    content: [
-                        {
-                            type: 'text',
-                            text: 'export: target, format, and revision are required.'
-                        }
-                    ]
-                };
-            }
-            if (args.target === 'video') {
-                return {
-                    isError: true,
-                    content: [
-                        {
-                            type: 'text',
-                            text: 'export: target=video is deferred to Phase 4.'
-                        }
-                    ]
-                };
-            }
-            if (args.outPath !== undefined && !allowOutPath) {
-                return {
-                    isError: true,
-                    content: [
-                        {
-                            type: 'text',
-                            text: 'export: `outPath` is not supported on this (hosted) backend. Omit it — the artifact is written to the workspace and returned as `httpUrl`; fetch that URL to download the bytes to disk.'
-                        }
-                    ]
-                };
-            }
-            const rev = await store.read(args.revision);
-            if (typeof args.blockId !== 'number') {
-                return {
-                    isError: true,
-                    content: [
-                        {
-                            type: 'text',
-                            text: `export: target=${args.target} requires \`blockId\`.`
-                        }
-                    ]
-                };
-            }
-            const mimeMap = TARGET_MIME[args.target];
-            const mime = mimeMap?.[args.format];
-            if (!mime) {
-                return {
-                    isError: true,
-                    content: [
-                        {
-                            type: 'text',
-                            text: `export: invalid format=${args.format} for target=${args.target}.`
-                        }
-                    ]
-                };
+            const rec = new SpanRecorder();
+            const startedAt = performance.now();
+            let result;
+            let threw;
+            let revision;
+            try {
+                result = await (async () => {
+                    const args = (rawArgs ?? {});
+                    if (typeof args.target !== 'string' ||
+                        typeof args.format !== 'string' ||
+                        typeof args.revision !== 'string') {
+                        return {
+                            isError: true,
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'export: target, format, and revision are required.'
+                                }
+                            ]
+                        };
+                    }
+                    if (args.target === 'video') {
+                        return {
+                            isError: true,
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'export: target=video is deferred to Phase 4.'
+                                }
+                            ]
+                        };
+                    }
+                    if (args.outPath !== undefined && !allowOutPath) {
+                        return {
+                            isError: true,
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'export: `outPath` is not supported on this (hosted) backend. Omit it — the artifact is written to the workspace and returned as `httpUrl`; fetch that URL to download the bytes to disk.'
+                                }
+                            ]
+                        };
+                    }
+                    const rev = await rec.time('workspace_read', () => store.read(args.revision));
+                    if (typeof args.blockId !== 'number') {
+                        return {
+                            isError: true,
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `export: target=${args.target} requires \`blockId\`.`
+                                }
+                            ]
+                        };
+                    }
+                    const mimeMap = TARGET_MIME[args.target];
+                    const mime = mimeMap?.[args.format];
+                    if (!mime) {
+                        return {
+                            isError: true,
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `export: invalid format=${args.format} for target=${args.target}.`
+                                }
+                            ]
+                        };
+                    }
+                    // Capture validated args into locals so the locked closure keeps the
+                    // type narrowing the top-level guards established.
+                    const revId = args.revision;
+                    const blockId = args.blockId;
+                    const sceneBytes = rev.scene;
+                    // load-into-engine then export reads the shared engine across awaits —
+                    // serialize against any concurrent engine-touching tool call.
+                    const beforeLock = performance.now();
+                    const bytes = await engineLock.runExclusive(async () => {
+                        rec.add('lock_wait', performance.now() - beforeLock);
+                        const slot = await rec.time('engine_scene_load', async () => {
+                            await session.populate(revId, sceneBytes);
+                            return session.acquire(revId);
+                        });
+                        const eng = slot.engine;
+                        const blob = await rec.time('engine_execute', () => eng.block.export(blockId, mime, {}));
+                        return new Uint8Array(await blob.arrayBuffer());
+                    });
+                    const shard = args.revision.slice(0, 2);
+                    const rest = args.revision.slice(2);
+                    const ext = FORMAT_EXT[args.format];
+                    const relPath = `exports/${shard}/${rest}/${args.target}.${ext}`;
+                    let absPath;
+                    let httpUrl;
+                    if (args.outPath !== undefined) {
+                        // Local-only escape hatch: write through real disk fs, NOT through
+                        // the workspace abstraction. The caller chose this path explicitly,
+                        // so echoing it back is a confirmation, not a workspace-path leak.
+                        await nodeFs.mkdir(dirname(args.outPath), { recursive: true });
+                        await rec.time('workspace_write', async () => {
+                            await nodeFs.writeFile(args.outPath, bytes);
+                        });
+                        absPath = args.outPath;
+                    }
+                    else {
+                        // Workspace write — goes through the WorkspaceFS abstraction. The
+                        // artifact is reachable over HTTP via the `/r/` route; the absolute
+                        // disk path is deliberately NOT disclosed.
+                        await rec.time('workspace_write', async () => {
+                            await fs.writeFile(relPath, bytes);
+                        });
+                        httpUrl = await urlBuilder.forDownload(relPath);
+                    }
+                    revision = args.revision;
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    uri: `workspace://${relPath}`,
+                                    ...(httpUrl ? { httpUrl } : {}),
+                                    ...(absPath ? { path: absPath } : {}),
+                                    bytes: bytes.byteLength,
+                                    format: args.format,
+                                    revision: args.revision
+                                })
+                            }
+                        ]
+                    };
+                })();
+                return result;
             }
-            // Capture validated args into locals so the locked closure keeps the
-            // type narrowing the top-level guards established.
-            const revision = args.revision;
-            const blockId = args.blockId;
-            const sceneBytes = rev.scene;
-            // load-into-engine then export reads the shared engine across awaits —
-            // serialize against any concurrent engine-touching tool call.
-            const bytes = await engineLock.runExclusive(async () => {
-                await session.populate(revision, sceneBytes);
-                const slot = await session.acquire(revision);
-                const eng = slot.engine;
-                const blob = await eng.block.export(blockId, mime, {});
-                return new Uint8Array(await blob.arrayBuffer());
-            });
-            const shard = args.revision.slice(0, 2);
-            const rest = args.revision.slice(2);
-            const ext = FORMAT_EXT[args.format];
-            const relPath = `exports/${shard}/${rest}/${args.target}.${ext}`;
-            let absPath;
-            let httpUrl;
-            if (args.outPath !== undefined) {
-                // Local-only escape hatch: write through real disk fs, NOT through
-                // the workspace abstraction. The caller chose this path explicitly,
-                // so echoing it back is a confirmation, not a workspace-path leak.
-                await nodeFs.mkdir(dirname(args.outPath), { recursive: true });
-                await nodeFs.writeFile(args.outPath, bytes);
-                absPath = args.outPath;
+            catch (err) {
+                threw = err;
+                throw err;
             }
-            else {
-                // Workspace write — goes through the WorkspaceFS abstraction. The
-                // artifact is reachable over HTTP via the `/r/` route; the absolute
-                // disk path is deliberately NOT disclosed.
-                await fs.writeFile(relPath, bytes);
-                httpUrl = await urlBuilder.forDownload(relPath);
+            finally {
+                telemetry.record({
+                    tool: 'export',
+                    succeeded: threw === undefined && result?.isError !== true,
+                    totalMs: performance.now() - startedAt,
+                    spans: rec.list(),
+                    args: rawArgs,
+                    ...(result !== undefined ? { result: summarizeResult(result) } : {}),
+                    ...(revision ? { revision } : {}),
+                    ...(threw ? { error: toErrorShape(threw) } : {})
+                });
             }
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            uri: `workspace://${relPath}`,
-                            ...(httpUrl ? { httpUrl } : {}),
-                            ...(absPath ? { path: absPath } : {}),
-                            bytes: bytes.byteLength,
-                            format: args.format,
-                            revision: args.revision
-                        })
-                    }
-                ]
-            };
         }
     };
 }

package/dist/tools/export.js.map

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

package/dist/tools/import.d.ts

@@ -0,0 +1,12 @@
+import type { CodesignMcpToolRegistration } from '../server.js';
+import type { ViewerUrlBuilder } from '../viewer/url-builder.js';
+import type { WorkspaceFS } from '../workspace/types.js';
+export interface CreateImportToolOptions {
+    fs: WorkspaceFS;
+    /** Builds the `httpUrl` for the imported asset (the `/r/` route). */
+    urlBuilder: ViewerUrlBuilder;
+    /** Whether to honour a local `source.path` (Local: yes; Hosted/sandbox: no). */
+    allowLocalPath: boolean;
+}
+export declare function createImportTool(opts: CreateImportToolOptions): CodesignMcpToolRegistration;
+//# sourceMappingURL=import.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../src/tools/import.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AA2EzD,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,WAAW,CAAC;IAChB,qEAAqE;IACrE,UAAU,EAAE,gBAAgB,CAAC;IAC7B,gFAAgF;IAChF,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,uBAAuB,GAC5B,2BAA2B,CAsE7B"}

package/dist/tools/import.js

@@ -0,0 +1,144 @@
+// packages/codesign-mcp/src/tools/import.ts
+//
+// `import` — bring a local media file (image/video/audio) into the workspace.
+// Reads the file's bytes off the real disk (node:fs/promises), content-addresses
+// them into `assets/<sha>.<ext>` via WorkspaceFS, and returns a durable
+// `workspace://` handle to embed in a later `edit`. Make-available only: it never
+// mutates a scene and never commits a revision (same stance as asset_search /
+// asset_generate).
+//
+// M1 exposes exactly one `source` arm: `{ path }` (local disk). The union is
+// built so hosted byte transports (base64, upload-handle — CODE-42) add without
+// reshape. `{ path }` is advertised + honoured only on a backend that shares the
+// disk (Local); on Hosted the arm is omitted from the schema and a runtime guard
+// rejects it as a backstop (mirrors export.ts's outPath).
+//
+// Two filesystems, deliberately distinct (platform-matches-node.md):
+//   INPUT  = the user's real disk  -> node:fs/promises (readFile)
+//   OUTPUT = the workspace store   -> WorkspaceFS (writeFile)
+import { readFile as readFileFromDisk } from 'node:fs/promises';
+import { extname, isAbsolute } from 'node:path';
+import { shortHash } from '../workspace/content-hash.js';
+// Extension -> { mime, kind, canonical ext }. The stored path always uses the
+// canonical ext (jpeg -> jpg) so content-addressing is stable regardless of the
+// source file's spelling. Extension-only classification is deliberate (KISS): a
+// magic-byte fallback is a future extension, added when a real mislabeled file
+// needs it (YAGNI).
+const MEDIA_TYPES = {
+    jpg: { mime: 'image/jpeg', kind: 'image', ext: 'jpg' },
+    jpeg: { mime: 'image/jpeg', kind: 'image', ext: 'jpg' },
+    png: { mime: 'image/png', kind: 'image', ext: 'png' },
+    webp: { mime: 'image/webp', kind: 'image', ext: 'webp' },
+    gif: { mime: 'image/gif', kind: 'image', ext: 'gif' },
+    svg: { mime: 'image/svg+xml', kind: 'image', ext: 'svg' },
+    mp4: { mime: 'video/mp4', kind: 'video', ext: 'mp4' },
+    webm: { mime: 'video/webm', kind: 'video', ext: 'webm' },
+    mov: { mime: 'video/quicktime', kind: 'video', ext: 'mov' },
+    mp3: { mime: 'audio/mpeg', kind: 'audio', ext: 'mp3' },
+    wav: { mime: 'audio/wav', kind: 'audio', ext: 'wav' },
+    m4a: { mime: 'audio/mp4', kind: 'audio', ext: 'm4a' },
+    ogg: { mime: 'audio/ogg', kind: 'audio', ext: 'ogg' },
+    aac: { mime: 'audio/aac', kind: 'audio', ext: 'aac' }
+};
+const SUPPORTED_HINT = 'Supported: image (jpg, png, webp, gif, svg), video (mp4, webm, mov), audio (mp3, wav, m4a, ogg, aac).';
+/** Lowercased extension without the dot (`".JPG"` -> `"jpg"`; `""` if none). */
+function fileExt(path) {
+    return extname(path).slice(1).toLowerCase();
+}
+const DESCRIPTION = [
+    'Import a local media file (image, video, or audio) into the workspace so it can be used in a design. Copies the file bytes into the content-addressed asset store at `assets/<sha>.<ext>`.',
+    '',
+    'Returns JSON: `{ uri, httpUrl, mimeType, kind, bytes }`. `uri` (a `workspace://` URI) is the durable handle — embed it in a subsequent `edit` (image/video fill, or `engine.asset.apply`), NEVER `httpUrl`, so the design stays loadable after a restart or rewind. `httpUrl` is a fetch link for opening the asset now.',
+    '',
+    'Make-available only: it never edits a scene and never creates a revision — do the placement in `edit`.',
+    '',
+    'Source: `{ path }` — an absolute path to a file the server can read. Local-only (this backend shares your disk); on a hosted server this arm is not offered.'
+].join('\n');
+// Schema is built per-backend (mirrors export.ts): the `{ path }` arm is
+// advertised ONLY when the backend can read local disk (Local). On Hosted the
+// `source` object has no arms yet — CODE-42 adds base64/upload arms there
+// without reshaping this tool. The runtime guard in `call` stays as a backstop.
+function buildImportInputSchema(allowLocalPath) {
+    const sourceProperties = {};
+    if (allowLocalPath) {
+        sourceProperties.path = {
+            type: 'string',
+            description: 'Absolute path to a local media file the server can read (image/video/audio).'
+        };
+    }
+    return {
+        type: 'object',
+        properties: {
+            source: {
+                type: 'object',
+                properties: sourceProperties,
+                additionalProperties: false
+            }
+        },
+        required: ['source'],
+        additionalProperties: false
+    };
+}
+export function createImportTool(opts) {
+    const { fs, urlBuilder, allowLocalPath } = opts;
+    const err = (text) => ({
+        isError: true,
+        content: [{ type: 'text', text }]
+    });
+    return {
+        name: 'import',
+        description: DESCRIPTION,
+        inputSchema: buildImportInputSchema(allowLocalPath),
+        call: async (rawArgs) => {
+            const args = (rawArgs ?? {});
+            const path = args.source?.path;
+            if (typeof path === 'string') {
+                if (!allowLocalPath) {
+                    return err("import: `source.path` is not supported on this (hosted) backend. A hosted server cannot read the client's disk; base64/upload transports are tracked in CODE-42.");
+                }
+                // Contract: `source.path` is absolute. A relative path would resolve
+                // against the server's cwd — invisible to the caller — so it could
+                // silently read the wrong file (or a surprising one). Reject up front.
+                if (!isAbsolute(path)) {
+                    return err(`import: \`source.path\` must be an absolute path (got "${path}").`);
+                }
+                // Classify by extension before touching disk — cheap fail-fast.
+                const type = MEDIA_TYPES[fileExt(path)];
+                if (!type) {
+                    return err(`import: unsupported or undetectable media type for "${path}". ${SUPPORTED_HINT}`);
+                }
+                // INPUT: real disk. A missing/unreadable file throws here.
+                let bytes;
+                try {
+                    bytes = await readFileFromDisk(path);
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    return err(`import: could not read "${path}" — ${msg}`);
+                }
+                // OUTPUT: workspace store, content-addressed.
+                const sha = await shortHash(bytes);
+                const relPath = `assets/${sha}.${type.ext}`;
+                await fs.writeFile(relPath, bytes);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                uri: `workspace://${relPath}`,
+                                httpUrl: await urlBuilder.forDownload(relPath),
+                                mimeType: type.mime,
+                                kind: type.kind,
+                                bytes: bytes.byteLength
+                            })
+                        }
+                    ]
+                };
+            }
+            return err(allowLocalPath
+                ? 'import: provide `source.path` (an absolute path to a local media file).'
+                : 'import: no usable `source` on this (hosted) backend. Local file paths are not readable here; base64/upload transports are tracked in CODE-42.');
+        }
+    };
+}
+//# sourceMappingURL=import.js.map

package/dist/tools/import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import.js","sourceRoot":"","sources":["../../src/tools/import.ts"],"names":[],"mappings":"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","sourcesContent":["// packages/codesign-mcp/src/tools/import.ts\n//\n// `import` — bring a local media file (image/video/audio) into the workspace.\n// Reads the file's bytes off the real disk (node:fs/promises), content-addresses\n// them into `assets/<sha>.<ext>` via WorkspaceFS, and returns a durable\n// `workspace://` handle to embed in a later `edit`. Make-available only: it never\n// mutates a scene and never commits a revision (same stance as asset_search /\n// asset_generate).\n//\n// M1 exposes exactly one `source` arm: `{ path }` (local disk). The union is\n// built so hosted byte transports (base64, upload-handle — CODE-42) add without\n// reshape. `{ path }` is advertised + honoured only on a backend that shares the\n// disk (Local); on Hosted the arm is omitted from the schema and a runtime guard\n// rejects it as a backstop (mirrors export.ts's outPath).\n//\n// Two filesystems, deliberately distinct (platform-matches-node.md):\n//   INPUT  = the user's real disk  -> node:fs/promises (readFile)\n//   OUTPUT = the workspace store   -> WorkspaceFS (writeFile)\n\nimport { readFile as readFileFromDisk } from 'node:fs/promises';\nimport { extname, isAbsolute } from 'node:path';\nimport type { CodesignMcpToolRegistration } from '../server.js';\nimport type { ViewerUrlBuilder } from '../viewer/url-builder.js';\nimport { shortHash } from '../workspace/content-hash.js';\nimport type { WorkspaceFS } from '../workspace/types.js';\n\ntype Kind = 'image' | 'video' | 'audio';\n\n// Extension -> { mime, kind, canonical ext }. The stored path always uses the\n// canonical ext (jpeg -> jpg) so content-addressing is stable regardless of the\n// source file's spelling. Extension-only classification is deliberate (KISS): a\n// magic-byte fallback is a future extension, added when a real mislabeled file\n// needs it (YAGNI).\nconst MEDIA_TYPES: Record<string, { mime: string; kind: Kind; ext: string }> = {\n  jpg: { mime: 'image/jpeg', kind: 'image', ext: 'jpg' },\n  jpeg: { mime: 'image/jpeg', kind: 'image', ext: 'jpg' },\n  png: { mime: 'image/png', kind: 'image', ext: 'png' },\n  webp: { mime: 'image/webp', kind: 'image', ext: 'webp' },\n  gif: { mime: 'image/gif', kind: 'image', ext: 'gif' },\n  svg: { mime: 'image/svg+xml', kind: 'image', ext: 'svg' },\n  mp4: { mime: 'video/mp4', kind: 'video', ext: 'mp4' },\n  webm: { mime: 'video/webm', kind: 'video', ext: 'webm' },\n  mov: { mime: 'video/quicktime', kind: 'video', ext: 'mov' },\n  mp3: { mime: 'audio/mpeg', kind: 'audio', ext: 'mp3' },\n  wav: { mime: 'audio/wav', kind: 'audio', ext: 'wav' },\n  m4a: { mime: 'audio/mp4', kind: 'audio', ext: 'm4a' },\n  ogg: { mime: 'audio/ogg', kind: 'audio', ext: 'ogg' },\n  aac: { mime: 'audio/aac', kind: 'audio', ext: 'aac' }\n};\n\nconst SUPPORTED_HINT =\n  'Supported: image (jpg, png, webp, gif, svg), video (mp4, webm, mov), audio (mp3, wav, m4a, ogg, aac).';\n\ninterface ImportArgs {\n  source?: { path?: string };\n}\n\n/** Lowercased extension without the dot (`\".JPG\"` -> `\"jpg\"`; `\"\"` if none). */\nfunction fileExt(path: string): string {\n  return extname(path).slice(1).toLowerCase();\n}\n\nconst DESCRIPTION = [\n  'Import a local media file (image, video, or audio) into the workspace so it can be used in a design. Copies the file bytes into the content-addressed asset store at `assets/<sha>.<ext>`.',\n  '',\n  'Returns JSON: `{ uri, httpUrl, mimeType, kind, bytes }`. `uri` (a `workspace://` URI) is the durable handle — embed it in a subsequent `edit` (image/video fill, or `engine.asset.apply`), NEVER `httpUrl`, so the design stays loadable after a restart or rewind. `httpUrl` is a fetch link for opening the asset now.',\n  '',\n  'Make-available only: it never edits a scene and never creates a revision — do the placement in `edit`.',\n  '',\n  'Source: `{ path }` — an absolute path to a file the server can read. Local-only (this backend shares your disk); on a hosted server this arm is not offered.'\n].join('\\n');\n\n// Schema is built per-backend (mirrors export.ts): the `{ path }` arm is\n// advertised ONLY when the backend can read local disk (Local). On Hosted the\n// `source` object has no arms yet — CODE-42 adds base64/upload arms there\n// without reshaping this tool. The runtime guard in `call` stays as a backstop.\nfunction buildImportInputSchema(allowLocalPath: boolean) {\n  const sourceProperties: Record<string, unknown> = {};\n  if (allowLocalPath) {\n    sourceProperties.path = {\n      type: 'string' as const,\n      description:\n        'Absolute path to a local media file the server can read (image/video/audio).'\n    };\n  }\n  return {\n    type: 'object' as const,\n    properties: {\n      source: {\n        type: 'object' as const,\n        properties: sourceProperties,\n        additionalProperties: false\n      }\n    },\n    required: ['source'],\n    additionalProperties: false\n  };\n}\n\nexport interface CreateImportToolOptions {\n  fs: WorkspaceFS;\n  /** Builds the `httpUrl` for the imported asset (the `/r/` route). */\n  urlBuilder: ViewerUrlBuilder;\n  /** Whether to honour a local `source.path` (Local: yes; Hosted/sandbox: no). */\n  allowLocalPath: boolean;\n}\n\nexport function createImportTool(\n  opts: CreateImportToolOptions\n): CodesignMcpToolRegistration {\n  const { fs, urlBuilder, allowLocalPath } = opts;\n  const err = (text: string) => ({\n    isError: true as const,\n    content: [{ type: 'text' as const, text }]\n  });\n  return {\n    name: 'import',\n    description: DESCRIPTION,\n    inputSchema: buildImportInputSchema(allowLocalPath),\n    call: async (rawArgs) => {\n      const args = (rawArgs ?? {}) as ImportArgs;\n      const path = args.source?.path;\n\n      if (typeof path === 'string') {\n        if (!allowLocalPath) {\n          return err(\n            \"import: `source.path` is not supported on this (hosted) backend. A hosted server cannot read the client's disk; base64/upload transports are tracked in CODE-42.\"\n          );\n        }\n        // Contract: `source.path` is absolute. A relative path would resolve\n        // against the server's cwd — invisible to the caller — so it could\n        // silently read the wrong file (or a surprising one). Reject up front.\n        if (!isAbsolute(path)) {\n          return err(\n            `import: \\`source.path\\` must be an absolute path (got \"${path}\").`\n          );\n        }\n        // Classify by extension before touching disk — cheap fail-fast.\n        const type = MEDIA_TYPES[fileExt(path)];\n        if (!type) {\n          return err(\n            `import: unsupported or undetectable media type for \"${path}\". ${SUPPORTED_HINT}`\n          );\n        }\n        // INPUT: real disk. A missing/unreadable file throws here.\n        let bytes: Uint8Array;\n        try {\n          bytes = await readFileFromDisk(path);\n        } catch (e) {\n          const msg = e instanceof Error ? e.message : String(e);\n          return err(`import: could not read \"${path}\" — ${msg}`);\n        }\n        // OUTPUT: workspace store, content-addressed.\n        const sha = await shortHash(bytes);\n        const relPath = `assets/${sha}.${type.ext}`;\n        await fs.writeFile(relPath, bytes);\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: JSON.stringify({\n                uri: `workspace://${relPath}`,\n                httpUrl: await urlBuilder.forDownload(relPath),\n                mimeType: type.mime,\n                kind: type.kind,\n                bytes: bytes.byteLength\n              })\n            }\n          ]\n        };\n      }\n\n      return err(\n        allowLocalPath\n          ? 'import: provide `source.path` (an absolute path to a local media file).'\n          : 'import: no usable `source` on this (hosted) backend. Local file paths are not readable here; base64/upload transports are tracked in CODE-42.'\n      );\n    }\n  };\n}\n"]}

package/dist/tools/index.d.ts

@@ -5,6 +5,7 @@ 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';
+import type { TelemetrySink } from './spans.js';
 export interface BuildDesignToolRegistrationsOptions<E = unknown> {
     fs: WorkspaceFS;
     store: RevisionStore;
@@ -30,6 +31,8 @@ export interface BuildDesignToolRegistrationsOptions<E = unknown> {
         revision: string;
         engine: E;
     }) => Promise<Uint8Array>;
+    /** Diagnostics telemetry port, threaded into the engine tools (edit/preview/export). */
+    telemetry?: TelemetrySink;
 }
 export declare function buildDesignToolRegistrations<E = unknown>(opts: BuildDesignToolRegistrationsOptions<E>): CodesignMcpToolRegistration[];
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.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,qBAAqB,CAAC;AACzD,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;AAiBzD,MAAM,WAAW,mCAAmC,CAAC,CAAC,GAAG,OAAO;IAC9D,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B;;;;;OAKG;IACH,UAAU,EAAE,KAAK,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,uFAAuF;IACvF,YAAY,EAAE,OAAO,CAAC;IACtB,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,gFAAgF;IAChF,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,4BAA4B,CAAC,CAAC,GAAG,OAAO,EACtD,IAAI,EAAE,mCAAmC,CAAC,CAAC,CAAC,GAC3C,2BAA2B,EAAE,CA2D/B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.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,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAoBhD,MAAM,WAAW,mCAAmC,CAAC,CAAC,GAAG,OAAO;IAC9D,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B;;;;;OAKG;IACH,UAAU,EAAE,KAAK,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,uFAAuF;IACvF,YAAY,EAAE,OAAO,CAAC;IACtB,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,gFAAgF;IAChF,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,CAAC,CAAC;KACX,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1B,wFAAwF;IACxF,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED,wBAAgB,4BAA4B,CAAC,CAAC,GAAG,OAAO,EACtD,IAAI,EAAE,mCAAmC,CAAC,CAAC,CAAC,GAC3C,2BAA2B,EAAE,CAoG/B"}