@sudomock/mcp 3.0.0 → 3.2.0

package/dist/index.js

@@ -3,8 +3,7 @@
  * SudoMock MCP Server
  *
  * Local stdio MCP server for Claude Desktop, Claude Code, Cursor, and VS Code.
- * Renders photorealistic product mockups from Photoshop PSD templates and
- * product photos via the SudoMock API.
+ * Renders photorealistic product mockups from Photoshop PSD templates via the SudoMock API.
  *
  * Auth: SUDOMOCK_API_KEY environment variable
  * Transport: stdio (local process)
@@ -173,7 +172,7 @@ export function formatJobAccepted(result) {
     };
     return JSON.stringify(summary, null, 2);
 }
-export const TERMINAL_JOB_STATUSES = new Set(["succeeded", "failed", "cancelled"]);
+export const TERMINAL_JOB_STATUSES = new Set(["succeeded", "failed"]);
 /** GET /api/v1/jobs/{job_id} -- owner-scoped job status snapshot. */
 async function getJob(jobId, timeout = DEFAULT_TIMEOUT) {
     const result = (await apiRequest({
@@ -528,6 +527,7 @@ function publicAccount(result) {
     const envelope = asRecord(result);
     const data = asRecord(envelope.data ?? result);
     const account = asRecord(data.account);
+    const organization = asRecord(data.organization);
     const subscription = asRecord(data.subscription);
     const usage = asRecord(data.usage);
     const apiKey = asRecord(data.api_key);
@@ -540,6 +540,12 @@ function publicAccount(result) {
                 name: account.name ?? null,
                 created_at: account.created_at ?? null,
             },
+            // The plan, the credits and the balance below belong to this
+            // organization, not to the person: the API key is the organization's.
+            organization: {
+                id: organization.id ?? null,
+                name: organization.name ?? null,
+            },
             subscription: {
                 plan: subscription.plan ?? null,
                 tier: subscription.tier ?? null,
@@ -602,6 +608,57 @@ function publicWebhookAction(result) {
         status: data.status ?? null,
     };
 }
+function publicWebhookBulkReplay(result) {
+    const envelope = asRecord(result);
+    const data = asRecord(envelope.data ?? result);
+    return {
+        success: envelope.success !== false,
+        status: data.status ?? null,
+        count: data.count ?? null,
+    };
+}
+function publicFontList(result) {
+    const envelope = asRecord(result);
+    const rows = Array.isArray(envelope.data) ? envelope.data : [];
+    const pagination = asRecord(envelope.pagination);
+    return {
+        success: envelope.success !== false,
+        data: rows.map((row) => {
+            const font = asRecord(row);
+            return {
+                uuid: font.uuid ?? null,
+                family: font.family ?? null,
+                subfamily: font.subfamily ?? null,
+                postscript_name: font.postscript_name ?? null,
+                category: font.category ?? null,
+                license: font.license ?? null,
+                is_premium: font.is_premium === true,
+                is_system: font.is_system === true,
+                preview_url: font.preview_url ?? null,
+                file_url: font.file_url ?? null,
+                created_at: font.created_at ?? null,
+            };
+        }),
+        pagination: {
+            page: pagination.page ?? null,
+            per_page: pagination.per_page ?? null,
+            total: pagination.total ?? rows.length,
+        },
+    };
+}
+function publicUploadTarget(result) {
+    const envelope = asRecord(result);
+    const data = asRecord(envelope.data ?? result);
+    return {
+        success: envelope.success !== false,
+        data: {
+            upload_url: data.upload_url ?? null,
+            file_url: data.file_url ?? null,
+            method: data.method ?? null,
+            expires_in: data.expires_in ?? null,
+        },
+    };
+}
 /**
  * A job is done when its status is terminal. The poll response (GET
  * /api/v1/jobs/{job_id}) always reports the job state in the `status` field.
@@ -647,10 +704,20 @@ function withToolLog(tool, cb) {
         }
     };
 }
+/**
+ * What each tool was registered with, keyed by the name it was registered
+ * under. Replaying an entry under a second name publishes the same tool twice
+ * without a second copy of its handler or its input schema, which is how the
+ * family spellings at the bottom of this file are added.
+ */
+const registrations = new Map();
 /**
  * Wraps every tool callback registered through `tool()` / `registerTool()` so
- * each call writes one log line. Both SDK methods take the callback as their
- * last argument; the registration call sites below stay untouched and typed.
+ * each call writes one log line, and records the registration on the way past.
+ * Both SDK methods take the callback as their last argument; the registration
+ * call sites below stay untouched and typed. The copy is taken before the
+ * callback is wrapped, so a replay logs under the name it is replayed as
+ * rather than under the name it was first registered with.
  */
 function instrumentToolCalls(target) {
     for (const method of ["tool", "registerTool"]) {
@@ -658,6 +725,7 @@ function instrumentToolCalls(target) {
         const wrapped = (...args) => {
             const last = args.length - 1;
             if (typeof args[0] === "string" && typeof args[last] === "function") {
+                registrations.set(args[0], { method, args: [...args] });
                 args[last] = withToolLog(args[0], args[last]);
             }
             return original.apply(target, args);
@@ -674,9 +742,9 @@ const server = new McpServer({
 });
 instrumentToolCalls(server);
 // ---------------------------------------------------------------------------
-// Tool 1: list_psd_mockups
+// Tool 1: list_mockups
 // ---------------------------------------------------------------------------
-server.tool("list_psd_mockups", "List your uploaded PSD mockup templates with UUIDs, names, and thumbnails. Use returned UUIDs with render_psd_mockup or get_psd_mockup.", {
+server.tool("list_mockups", "List your uploaded mockup templates with UUIDs, names, and thumbnails. Use returned UUIDs with render_mockup or get_mockup_details.", {
     limit: z.number().min(1).max(100).default(20).describe("Results per page (1-100, default 20)"),
     offset: z.number().min(0).default(0).describe("Pagination offset (default 0)"),
     name: z.string().optional().describe("Filter by name (case-insensitive substring match)"),
@@ -687,7 +755,7 @@ server.tool("list_psd_mockups", "List your uploaded PSD mockup templates with UU
 }, async ({ limit, offset, name, created_after, created_before, sort_by, sort_order }) => {
     const result = await apiRequest({
         method: "GET",
-        path: "/api/v1/psd-mockups",
+        path: "/api/v1/mockups",
         params: { limit, offset, name, created_after, created_before, sort: sort_by, order: sort_order },
     });
     return {
@@ -698,14 +766,14 @@ server.tool("list_psd_mockups", "List your uploaded PSD mockup templates with UU
     };
 });
 // ---------------------------------------------------------------------------
-// Tool 2: get_psd_mockup
+// Tool 2: get_mockup_details
 // ---------------------------------------------------------------------------
-server.tool("get_psd_mockup", "Get full details of a PSD mockup: smart object UUIDs, layer names, dimensions, positions, blend modes, editable text layers, and thumbnail URLs.", {
-    mockup_uuid: z.string().describe("The UUID of the PSD mockup to inspect"),
+server.tool("get_mockup_details", "Get full details of a mockup: smart object UUIDs, layer names, dimensions, positions, blend modes, and thumbnail URLs.", {
+    mockup_uuid: z.string().describe("The UUID of the mockup to inspect"),
 }, async ({ mockup_uuid }) => {
     const result = await apiRequest({
         method: "GET",
-        path: `/api/v1/psd-mockups/${mockup_uuid}`,
+        path: `/api/v1/mockups/${mockup_uuid}`,
     });
     return {
         content: [{
@@ -715,15 +783,15 @@ server.tool("get_psd_mockup", "Get full details of a PSD mockup: smart object UU
     };
 });
 // ---------------------------------------------------------------------------
-// Tool 3: update_psd_mockup
+// Tool 3: update_mockup
 // ---------------------------------------------------------------------------
-server.tool("update_psd_mockup", "Rename a PSD mockup template.", {
-    mockup_uuid: z.string().describe("The UUID of the PSD mockup to rename"),
+server.tool("update_mockup", "Rename a mockup template.", {
+    mockup_uuid: z.string().describe("The UUID of the mockup to rename"),
     name: z.string().describe("New display name for the mockup"),
 }, async ({ mockup_uuid, name }) => {
     const result = await apiRequest({
         method: "PATCH",
-        path: `/api/v1/psd-mockups/${mockup_uuid}`,
+        path: `/api/v1/mockups/${mockup_uuid}`,
         body: { name },
     });
     return {
@@ -734,20 +802,28 @@ server.tool("update_psd_mockup", "Rename a PSD mockup template.", {
     };
 });
 // ---------------------------------------------------------------------------
-// Tool 4: delete_psd_mockup
+// Tool 4: delete_mockup
 // ---------------------------------------------------------------------------
-server.tool("delete_psd_mockup", "Permanently delete a PSD mockup template. Cannot be undone.", {
-    mockup_uuid: z.string().describe("The UUID of the PSD mockup to delete"),
+server.tool("delete_mockup", "Permanently delete a mockup template. Cannot be undone.", {
+    mockup_uuid: z.string().describe("The UUID of the mockup to delete"),
 }, async ({ mockup_uuid }) => {
     await apiRequest({
         method: "DELETE",
-        path: `/api/v1/psd-mockups/${mockup_uuid}`,
+        path: `/api/v1/mockups/${mockup_uuid}`,
     });
     return { content: [{ type: "text", text: `Mockup ${mockup_uuid} deleted successfully.` }] };
 });
 // ---------------------------------------------------------------------------
-// Tool 5: render_psd_mockup
+// Tool 5: render_mockup
 // ---------------------------------------------------------------------------
+// Every name the API takes for how artwork meets its area, on a smart object,
+// on a photo mockup print area and on a video's still frame alike: 'fill',
+// 'fit' and 'crop', and 'contain' and 'cover', the older names for 'fit' and
+// 'crop', which it still accepts. A name is sent as given. On a smart object
+// this package keeps 'fill' as its default when fit is left out; on a print
+// area nothing is sent and the API's own default applies.
+const FIT_MODES = ["fill", "fit", "crop", "contain", "cover"];
+const SMART_OBJECT_FIT_HELP = "'fill' stretches the artwork to the bounds, 'fit' fits it inside keeping its proportions, 'crop' covers the area keeping its proportions and cuts the overflow. 'contain' and 'cover' are the older names for 'fit' and 'crop' and are still accepted. Default 'fill'.";
 const smartObjectInputSchema = z
     .object({
     uuid: z
@@ -762,18 +838,21 @@ const smartObjectInputSchema = z
             .enum(["image/png", "image/jpeg", "image/jpg", "image/webp", "image/gif"])
             .optional()
             .describe("MIME type for base64 artwork; defaults to image/png"),
-        fit: z.enum(["fill", "contain", "cover"]).default("fill").describe("How artwork fills the smart object area"),
+        fit: z
+            .enum(FIT_MODES)
+            .default("fill")
+            .describe(`How the artwork meets the smart object area. ${SMART_OBJECT_FIT_HELP}`),
         size: z
             .object({
-            width: z.number().int().min(1).optional().describe("Artwork width in pixels"),
-            height: z.number().int().min(1).optional().describe("Artwork height in pixels"),
+            width: z.number().min(1).optional().describe("Artwork width in pixels, at least 1. Fractions are accepted."),
+            height: z.number().min(1).optional().describe("Artwork height in pixels, at least 1. Fractions are accepted."),
         })
             .optional()
             .describe("Optional custom artwork size"),
         position: z
             .object({
-            top: z.number().int().optional().describe("Top offset in pixels"),
-            left: z.number().int().optional().describe("Left offset in pixels"),
+            top: z.number().optional().describe("Top offset in pixels. Fractions are accepted."),
+            left: z.number().optional().describe("Left offset in pixels. Fractions are accepted."),
         })
             .optional()
             .describe("Optional custom artwork position"),
@@ -789,9 +868,20 @@ const smartObjectInputSchema = z
         .optional(),
     color: z
         .object({
-        hex: z.string().regex(/^#[0-9a-fA-F]{6}$/).describe("Color overlay as a six-digit hex code"),
+        hex: z
+            .string()
+            .regex(/^#[0-9a-fA-F]{6}$/)
+            .optional()
+            .describe("Color overlay as a six-digit hex code, e.g. '#FF5733'. Send this or label."),
+        label: z
+            .string()
+            .min(1)
+            .max(32)
+            .optional()
+            .describe("The name of a color saved on this mockup, e.g. 'blue jean', matched exactly. Send this instead of hex."),
         blending_mode: z.string().default("normal").describe("Blend mode for the color overlay"),
     })
+        .refine((color) => (color.hex === undefined) !== (color.label === undefined), "Provide exactly one of color.hex or color.label")
         .optional(),
     adjustment_layers: z
         .object({
@@ -811,7 +901,7 @@ const textLayerInputSchema = z
     uuid: z
         .string()
         .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/)
-        .describe("UUID from get_psd_mockup text_layers"),
+        .describe("UUID from get_mockup_details text_layers"),
     text: z.string().min(1).max(500).optional().describe("Replacement text for a single-style layer"),
     segments: z
         .array(z.object({
@@ -836,6 +926,10 @@ const textLayerInputSchema = z
         .enum(["shrink", "clip", "overflow"])
         .default("overflow")
         .describe("Long-text handling for single-style point text; default overflow"),
+    vertical_align: z
+        .enum(["top", "bottom", "center"])
+        .optional()
+        .describe("Where text that fit 'shrink' scaled down sits in the original area: 'top' (the default), 'center' or 'bottom'. Single-style point text only."),
 })
     .superRefine((layer, ctx) => {
     if ((layer.text === undefined) === (layer.segments === undefined)) {
@@ -858,22 +952,121 @@ const textLayerInputSchema = z
         ctx.addIssue({ code: "custom", message: "Segment indexes must be unique" });
     }
 });
-server.tool("render_psd_mockup", "Render a PSD mockup with artwork, editable text, or both. Supports one or multiple smart objects and preserves the template's authored appearance. Returns the rendered image URL. Costs 1 credit. Use list_psd_mockups and get_psd_mockup to find target UUIDs.", {
-    mockup_uuid: z.string().describe("UUID of the PSD mockup template (from list_psd_mockups)"),
-    smart_object_uuid: z.string().optional().describe("UUID of one smart object layer. Provide with artwork_url, or use smart_objects for one or more entries."),
-    artwork_url: z.string().optional().describe("Public artwork URL for smart_object_uuid. Provide both singular fields, or use smart_objects."),
+const LAYER_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const HEX_COLOR = /^#?[0-9a-fA-F]{6}$/;
+/** One outline color, or up to eight front to back; null keeps an authored color. */
+function outlineColors() {
+    return z.union([
+        z.string().regex(HEX_COLOR),
+        z.array(z.string().regex(HEX_COLOR).nullable()).min(1).max(8),
+    ]);
+}
+// One text layer and one group written as flat arguments: the names the hosted
+// server publishes on render_mockup. They become a single text_layers entry and
+// a single group_layers entry, built by the same rules the hosted server builds
+// them with (singleTextLayer and singleGroupLayer below), so the same flat
+// arguments put the same text_layers and group_layers entries on the wire from
+// either server.
+const SINGLE_LAYER_SHORTCUT = {
+    text_layer_uuid: z
+        .string()
+        .regex(LAYER_UUID)
+        .optional()
+        .describe("UUID of one editable text layer from get_mockup_details text_layers. Send with text or text_segments; it becomes one text_layers entry, placed before any text_layers entries sent with it."),
+    text: z
+        .string()
+        .min(1)
+        .max(500)
+        .optional()
+        .describe("Replacement text for the text_layer_uuid layer when it has one style (segment_count 1). Use text_segments for a styled layer."),
+    text_segments: z
+        .array(z.object({
+        index: z.number().int().min(0).max(31).describe("Zero-based segment index"),
+        text: z.string().min(1).max(200).describe("Replacement text for this segment"),
+    }))
+        .min(1)
+        .max(32)
+        .optional()
+        .describe("For a styled text_layer_uuid layer (segment_count above 1): {index, text} entries. Listed segments are replaced, the rest keep their text, and each keeps its own styling. Used instead of text."),
+    text_font: z.string().max(255).optional().describe("Font UUID or PostScript name from list_fonts. Single-style layers only. Omit to keep the layer's font."),
+    text_font_size: z.number().positive().max(2000).optional().describe("Font size in pixels at the mockup's native resolution. Single-style layers only. Omit to keep the original size."),
+    text_color: z.string().regex(HEX_COLOR).optional().describe("Text color as a six-digit hex code, e.g. '#1A1A1A'. Single-style layers only. Omit to keep the original color."),
+    text_stroke_color: outlineColors()
+        .optional()
+        .describe("Colors for the text layer's own outlines: one hex code for the front outline, or up to eight front to back; null keeps an authored color. Single-style layers only."),
+    text_fit: z
+        .enum(["shrink", "clip", "overflow"])
+        .optional()
+        .describe("Long-text handling for single-style point text: 'overflow' keeps the designed size, 'shrink' scales it down to fit, 'clip' cuts it at the last character that fits. Omit for 'overflow'."),
+    text_vertical_align: z
+        .enum(["top", "bottom", "center"])
+        .optional()
+        .describe("Where text that text_fit 'shrink' scaled down sits in the original area: 'top' (the default), 'center' or 'bottom'. Single-style layers only."),
+    group_layer_uuid: z
+        .string()
+        .regex(LAYER_UUID)
+        .optional()
+        .describe("UUID of an editable group layer from the mockup's group_layers. Send with group_stroke_color."),
+    group_stroke_color: outlineColors()
+        .optional()
+        .describe("Colors for that group's outlines: one hex code for the front outline, or up to eight front to back; null keeps an authored color. The change affects everything inside the group."),
+};
+/**
+ * The text_layers entry the flat text arguments describe, or undefined when
+ * they describe none. The hosted server's rules, one for one: the entry needs a
+ * layer UUID and either segments or text; segments win when both arrive and
+ * then travel without styling, because each segment keeps its own; a styling
+ * argument left out is left off the wire.
+ */
+function singleTextLayer(args) {
+    if (!args.text_layer_uuid || (!args.text_segments && !args.text))
+        return undefined;
+    const layer = { uuid: args.text_layer_uuid };
+    if (args.text_segments) {
+        layer.segments = args.text_segments;
+        return layer;
+    }
+    layer.text = args.text;
+    if (args.text_font)
+        layer.font = args.text_font;
+    if (args.text_font_size)
+        layer.font_size = args.text_font_size;
+    if (args.text_color)
+        layer.color = args.text_color;
+    if (args.text_stroke_color)
+        layer.stroke_color = args.text_stroke_color;
+    if (args.text_fit)
+        layer.fit = args.text_fit;
+    if (args.text_vertical_align)
+        layer.vertical_align = args.text_vertical_align;
+    return layer;
+}
+/** The group_layers entry the flat group arguments describe; both halves are needed. */
+function singleGroupLayer(args) {
+    if (!args.group_layer_uuid || args.group_stroke_color === undefined)
+        return undefined;
+    return { uuid: args.group_layer_uuid, stroke_color: args.group_stroke_color };
+}
+server.tool("render_mockup", "Render a PSD mockup with artwork, editable text, or both. Supports one or multiple smart objects and preserves the template's authored appearance. Name what to fill with any of these, alone or together: smart_object_uuid + artwork_url for one smart object, smart_objects entries ({uuid, asset or color}) for one or more, text_layers entries ({uuid, text or segments}), or text_layer_uuid + text for one text layer. Sent together they are combined into one render: the smart_object_uuid entry comes before the smart_objects entries, and the text_layer_uuid entry before the text_layers entries. A call that names nothing to render returns an error. Returns the rendered image URL. Costs 1 credit. Use list_mockups and get_mockup_details to find target UUIDs.", {
+    mockup_uuid: z.string().describe("UUID of the mockup template (from list_mockups)"),
+    smart_object_uuid: z.string().optional().describe("UUID of one smart object layer (from get_mockup_details). Send with artwork_url, or leave both out and use smart_objects or text_layers. With smart_objects, this entry comes first."),
+    artwork_url: z.string().optional().describe("Public artwork URL for smart_object_uuid. Send the two together, or leave both out and use smart_objects or text_layers."),
+    // An empty list is accepted and counts as not sent, as on the hosted
+    // server: smart_objects: [] beside the single pair renders the pair.
     smart_objects: z
         .array(smartObjectInputSchema)
-        .min(1)
         .optional()
-        .describe("One or more smart object overrides, each with asset or color. Do not combine with smart_object_uuid/artwork_url."),
+        .describe("Smart objects to fill, each with a uuid and asset or color. Works on its own; with smart_object_uuid these entries follow that one."),
     text_layers: z
         .array(textLayerInputSchema)
-        .min(1)
         .max(50)
         .optional()
-        .describe("Editable text overrides from get_psd_mockup. Each entry needs exactly one of text or segments. May be used alone or with smart objects."),
-    fit: z.enum(["fill", "contain", "cover"]).default("fill").describe("How singular artwork_url fills its smart object area"),
+        .describe("Text layer overrides from get_mockup_details, each with a uuid and exactly one of text or segments. Works on its own; with text_layer_uuid these entries follow that one."),
+    ...SINGLE_LAYER_SHORTCUT,
+    fit: z
+        .enum(FIT_MODES)
+        .default("fill")
+        .describe(`How the singular artwork_url meets its smart object area. ${SMART_OBJECT_FIT_HELP}`),
     image_format: z.enum(["webp", "png", "jpg"]).default("webp").describe("Output format"),
     image_size: z.number().min(100).max(10000).default(2048).describe("Output width in pixels (default 2048)"),
     quality: z.number().min(1).max(100).default(90).describe("Compression quality for webp/jpg (default 90)"),
@@ -899,17 +1092,24 @@ server.tool("render_psd_mockup", "Render a PSD mockup with artwork, editable tex
     const hasSmartObjectUuid = args.smart_object_uuid !== undefined;
     const hasArtworkUrl = args.artwork_url !== undefined;
     if (hasSmartObjectUuid !== hasArtworkUrl) {
-        throw new Error("Provide both smart_object_uuid and artwork_url, or use smart_objects.");
-    }
-    if (args.smart_objects && hasSmartObjectUuid) {
-        throw new Error("Provide smart_objects or smart_object_uuid/artwork_url, not both.");
+        throw new Error("Provide smart_object_uuid and artwork_url together, or leave both out and use smart_objects or text_layers.");
     }
-    if (!args.smart_objects && !hasSmartObjectUuid && !args.text_layers) {
-        throw new Error("Provide smart_objects, smart_object_uuid/artwork_url, or text_layers.");
+    const shortcutTextLayer = singleTextLayer(args);
+    const shortcutGroupLayer = singleGroupLayer(args);
+    // An empty list names nothing, so it counts as not sent.
+    const listedSmartObjects = args.smart_objects ?? [];
+    const listedTextLayers = args.text_layers ?? [];
+    if (!listedSmartObjects.length &&
+        !hasSmartObjectUuid &&
+        !listedTextLayers.length &&
+        !shortcutTextLayer &&
+        !shortcutGroupLayer) {
+        throw new Error("Nothing to render: provide smart_object_uuid with artwork_url, smart_objects, text_layers, text_layer_uuid with text or text_segments, or group_layer_uuid with group_stroke_color.");
     }
-    const smartObjects = args.smart_objects
-        ? [...args.smart_objects]
-        : [];
+    // The single pair and the lists are combined the way the hosted server
+    // combines them: the single entry first, then every list entry as given.
+    // An entry that names the same uuid twice reaches the API twice.
+    const smartObjects = [];
     if (hasSmartObjectUuid && hasArtworkUrl) {
         const smartObject = {
             uuid: args.smart_object_uuid,
@@ -945,6 +1145,11 @@ server.tool("render_psd_mockup", "Render a PSD mockup with artwork, editable tex
         }
         smartObjects.push(smartObject);
     }
+    smartObjects.push(...listedSmartObjects);
+    const textLayers = [
+        ...(shortcutTextLayer ? [shortcutTextLayer] : []),
+        ...listedTextLayers,
+    ];
     const body = {
         mockup_uuid: args.mockup_uuid,
         export_options: {
@@ -956,8 +1161,10 @@ server.tool("render_psd_mockup", "Render a PSD mockup with artwork, editable tex
     };
     if (smartObjects.length)
         body.smart_objects = smartObjects;
-    if (args.text_layers)
-        body.text_layers = args.text_layers;
+    if (textLayers.length)
+        body.text_layers = textLayers;
+    if (shortcutGroupLayer)
+        body.group_layers = [shortcutGroupLayer];
     if (args.export_label) {
         body.export_label = args.export_label;
     }
@@ -1002,9 +1209,40 @@ server.tool("remove_background", "Remove the background from any image and retur
     };
 });
 // ---------------------------------------------------------------------------
-// Tool: create_photo_mockup
+// Tool: list_fonts
 // ---------------------------------------------------------------------------
-server.tool("create_photo_mockup", "Create a reusable photo mockup from a public image URL of a product. Returns the mockup_id and its render targets synchronously. Costs 25 credits. If the image is unsuitable, the 25 credits are refunded automatically. Set is_async=true to queue instead and receive a job_id to poll with get_job or wait_for_job. Use the dashboard for visual fine-tuning.", {
+server.tool("list_fonts", "List fonts available for text layers: the shared system catalog plus any fonts you have uploaded. Filter by family name (search), by category (serif, sans-serif, display), or by scope ('all', 'system', or 'custom' for your uploads only); results are paginated (per_page up to 100). Use a font's uuid or postscript_name as the font of a text_layers entry when rendering with render_mockup. Costs 0 credits.", {
+    search: z.string().optional().describe("Filter by family name (case-insensitive contains), e.g. 'sans'"),
+    category: z.string().optional().describe("Filter by category, e.g. 'serif', 'sans-serif', 'display'"),
+    scope: z
+        .enum(["all", "system", "custom"])
+        .default("all")
+        .describe("Which fonts to return: 'all' (system fonts plus your uploads, the default), 'system', or 'custom' (your uploads only)"),
+    page: z.number().int().min(1).default(1).describe("Page number (1-based, default 1)"),
+    per_page: z.number().int().min(1).max(100).default(50).describe("Results per page (1-100, default 50)"),
+}, async ({ search, category, scope, page, per_page }) => {
+    const result = await apiRequest({
+        method: "GET",
+        path: "/api/v1/fonts",
+        params: {
+            page,
+            per_page,
+            scope,
+            search: search || undefined,
+            category: category || undefined,
+        },
+    });
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify(publicFontList(result), null, 2),
+            }],
+    };
+});
+// ---------------------------------------------------------------------------
+// Tool: create_2d_mockup
+// ---------------------------------------------------------------------------
+server.tool("create_2d_mockup", "Create a reusable photo mockup from a public image URL. Returns the mockup ID and public render targets synchronously. Costs 25 credits. If the image is unsuitable, the 25 credits are refunded automatically. Set is_async=true to queue instead and receive a job_id to poll with get_job or wait_for_job. Use the dashboard for visual fine-tuning.", {
     source_url: z.string().describe("Public HTTPS URL of the product image"),
     name: z.string().optional().describe("Optional display name for the photo mockup"),
     idempotency_key: z.string().min(1).max(255).optional().describe("Optional retry-stable key for this create request"),
@@ -1020,7 +1258,7 @@ server.tool("create_photo_mockup", "Create a reusable photo mockup from a public
         body.is_async = true;
     const result = (await apiRequest({
         method: "POST",
-        path: "/api/v1/photo-mockups",
+        path: "/api/v1/sudoai/2d-mockups",
         body,
         headers: { "Idempotency-Key": idempotency_key ?? randomUUID() },
     }));
@@ -1054,16 +1292,15 @@ server.tool("create_photo_mockup", "Create a reusable photo mockup from a public
     return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
 });
 // ---------------------------------------------------------------------------
-// Tool: render_photo_mockup
+// 2D render: one tool per kind of target
 // ---------------------------------------------------------------------------
-// A render names one target and nothing else: exactly one of print_area_uuid
-// or surface_uuid. A product surface is sized by a coverage percentage, a
-// print area by a fit, and either by an exact width + height. One tool holds
-// both dials, the same shape the hosted server exposes, so the dial that
-// belongs to the other kind of target is refused here by name instead of
-// being a field the caller could never reach.
-const PHOTO_RENDER_SHARED = {
-    mockup_id: z.string().describe("UUID of the photo mockup (mockup_id from list_photo_mockups, get_photo_mockup or create_photo_mockup)."),
+// A render names one target and nothing else. A product surface takes a
+// coverage percentage; a print area takes a fit or an explicit box. Two tools
+// rather than one, because those are two different dials and a single tool
+// could only describe in prose what the shape can state outright: whichever
+// tool the caller reaches for, every field on it applies.
+const TWO_D_SHARED = {
+    mockup_uuid: z.string().describe("UUID of the photo mockup template (from list_2d_mockups, returned as mockup_id)."),
     artwork_url: z.string().describe("Public URL of the artwork image (PNG/JPG/WebP) to place on the mockup"),
     remove_background: z.boolean().default(false).describe("Remove the artwork's background before placing it. Adds 25 credits per artwork."),
     opacity: z.number().min(0).max(100).default(100).describe("Artwork opacity percentage (0-100)"),
@@ -1107,82 +1344,74 @@ const PHOTO_RENDER_SHARED = {
     is_async: z
         .boolean()
         .default(false)
-        .describe("Queue the render instead of waiting. When true the API returns 202 with a job_id immediately -- poll with get_job, or call wait_for_job to block until it finishes and hands back result_url. Default false returns print_files + render_uuid synchronously (200). Use for long renders or when running many in parallel."),
+        .describe("Queue the render instead of waiting. When true the API returns 202 with a job_id immediately; poll with get_job, or call wait_for_job to block until it finishes and hands back result_url. Default false returns print_files + render_uuid synchronously (200). Use for long renders or when running many in parallel."),
 };
-// The sentences a refused option is answered with.
+// The option a caller can write on one of these two tools but not the other,
+// and the sentence that sends them to the one that works.
+//
+// An argument a tool never declared is dropped before the handler ever sees it,
+// so `coverage` on a print area, `fit` on a surface, and the retired `scale` on
+// either used to come back as a successful render with the caller's option
+// gone and nothing said about it. The API answers all three with a 422. The
+// consumer on this side is a language model: an option it wrote disappearing in
+// silence teaches it nothing and it writes the same option again, while one
+// named sentence teaches it in a single turn.
 //
-// The API answers each of these with a 422, and refusing them here as well is
-// deliberate: a client that can put a shape on the wire the API is guaranteed
-// to reject has spent the caller's round trip telling them something it
-// already knew. The consumer on this side is a language model: an option it
-// wrote disappearing in silence teaches it nothing and it writes the same
-// option again, while one named sentence teaches it in a single turn. The
-// wording is the API's own, so the caller reads the same reason whichever
+// The wording is the API's own, so the caller reads the same reason whichever
 // side answers first.
-const ONE_TARGET = "Provide exactly one of print_area_uuid or surface_uuid";
-const FIT_ON_SURFACE = "A surface covers the whole product, so fit has nothing to fit against. Send coverage to choose how much of the surface the artwork spans, or width and height to give it an exact size, or render a print area instead.";
-const COVERAGE_ON_PRINT_AREA = "A print area is sized by fit, or by an explicit width and height, so coverage has no meaning on one. Send fit or a width and height, or render the product surface instead.";
 const RETIRED_SCALE = "scale has been retired and nothing replaces the name. Send width and height together to draw the artwork at an exact size; a single multiplier could not express two independent axes.";
+const TWO_D_REFUSED_OPTIONS = {
+    surface: {
+        fit: "A surface covers the whole product, so fit has nothing to fit against. Send coverage to choose how much of the surface the artwork spans, or width and height to give it an exact size, or render a print area instead.",
+        scale: RETIRED_SCALE,
+    },
+    print_area: {
+        coverage: "A print area is sized by fit, or by an explicit width and height, so coverage has no meaning on one. Send fit or a width and height, or render the product surface instead.",
+        scale: RETIRED_SCALE,
+    },
+};
 /**
- * The tool's input. Strict on purpose: an argument a tool never declared is
- * dropped before the handler ever sees it, so the retired `scale` used to come
- * back as a successful render with the caller's option gone and nothing said
- * about it. A name we never published is either a typo or an option the
- * caller believes exists, and both are worth one line of reply.
+ * Build the arguments one 2D render tool accepts, and refuse the rest by name.
+ *
+ * Strict on purpose, and only on these two tools: the pair exists precisely
+ * because the sizing options are split between them, so an option landing on
+ * the wrong one of the two is the mistake most worth catching. Refusing is
+ * keyed on the argument being written rather than on the value it holds, so an
+ * explicitly written null is caught as well: writing it is the caller naming
+ * the option.
+ *
+ * An option with no sentence of its own still gets refused rather than dropped.
+ * A name we never published is either a typo or an option the caller believes
+ * exists, and both are worth one line of reply.
  */
-const renderPhotoMockupInput = z.strictObject({
-    ...PHOTO_RENDER_SHARED,
-    print_area_uuid: z
-        .string()
-        .optional()
-        .describe("UUID of a saved print area from get_photo_mockup's print_areas[] (its print_area_id): a bounded zone somebody drew on the product, such as a chest logo. Omit when surface_uuid is used."),
-    surface_uuid: z
-        .string()
-        .optional()
-        .describe("UUID of a product surface from get_photo_mockup's surfaces[]: a whole printable product, for an all-over print. Omit when print_area_uuid is used."),
-    coverage: z
-        .number()
-        .min(10)
-        .max(100)
-        .optional()
-        .describe("How much of the surface the artwork spans, as a percentage (10-100). Belongs to surface_uuid; sending it with print_area_uuid is refused. Omit to span the whole surface, which is what an all-over print usually wants. Send width and height instead to give the artwork an exact size."),
-    fit: z
-        .enum(["contain", "fill", "cover"])
-        .optional()
-        .describe("How the artwork meets the print area, which it always fills edge to edge: 'contain' keeps the proportions and fits inside (the default), 'fill' stretches to the edges, 'cover' fills and crops the overflow. Belongs to print_area_uuid; sending it with surface_uuid is refused. Leave it out to get 'contain'. To sit inside the area with room around it, send width and height instead."),
-    // A percentage cannot express a box whose proportions differ from the
-    // surface's, which is exactly what an artwork resized on a canvas is, so
-    // the exact box belongs to both kinds of target.
-    width: z
-        .number()
-        .min(1)
-        .max(30000)
-        .optional()
-        .describe("Artwork width in pixels, drawn at that exact size instead of by coverage or fit. Send together with height, and without coverage or fit. Width and height are independent, so any aspect ratio is allowed - stretching on one axis only is a supported placement."),
-    height: z
-        .number()
-        .min(1)
-        .max(30000)
-        .optional()
-        .describe("Artwork height in pixels. Send together with width. Sending only one of the two is rejected rather than silently completed, so the aspect ratio is never guessed for you."),
-}, {
-    error: (issue) => {
-        if (issue.code !== "unrecognized_keys")
-            return undefined;
-        return issue.keys
-            .map((key) => key === "scale"
-            ? RETIRED_SCALE
-            : `${key} is not an option on this tool. Send only the options it lists.`)
-            .join(" ");
-    },
-});
+function twoDRenderInput(kind, shape) {
+    const refused = TWO_D_REFUSED_OPTIONS[kind];
+    return z.strictObject(shape, {
+        error: (issue) => {
+            if (issue.code !== "unrecognized_keys")
+                return undefined;
+            return issue.keys
+                .map((key) => refused[key] ??
+                `${key} is not an option on this tool. Send only the options it lists, and read them from the tool's own arguments rather than from another tool's.`)
+                .join(" ");
+        },
+    });
+}
 /**
  * Refuse a placement that answers the sizing question more than once, or half.
  *
- * A default invents a value the caller never typed and quietly changes the
- * render when it drifts from the renderer's; a refusal invents nothing, and if
- * it ever drifts it drifts into refusing out loud, with the API still refusing
- * behind it.
+ * The API refuses these too, and refusing them here as well is deliberate. A
+ * client that can put a shape on the wire the API is guaranteed to reject has
+ * spent the caller's round trip telling them something it already knew.
+ *
+ * This is not the thing that was taken out of here. A default invents a value
+ * the caller never typed and quietly changes the render when it drifts from
+ * the renderer's; a refusal invents nothing, and if it ever drifts it drifts
+ * into refusing out loud, with the API still refusing behind it. It also
+ * cannot drift unnoticed: the contract test reads the shared placement wire
+ * fixture and asserts every shape listed there as rejected is still
+ * unreachable from every tool, and the wording below is the wording the API
+ * answers with, so a caller reads the same reason from either side.
  *
  * `relativeSizing` is whichever proportional option belongs to this kind of
  * target -- `coverage` on a surface, `fit` on a print area.
@@ -1200,15 +1429,16 @@ function assertOneSizingAnswer(placement, relativeSizing) {
 /**
  * Send one render and hand back what the caller can act on.
  *
- * `target` carries the address field, `placement` the sizing dials that
- * belong to that kind of target. Neither is inspected here: the handler has
- * already settled which target this is and which dials it may carry.
+ * `target` carries the address field, `placement` the dials that belong to that
+ * kind of target. Neither is inspected here: the dials a caller may turn are
+ * settled by which tool they called, so there is nothing left to check.
  */
-async function renderPhotoMockup(args, target, placement) {
-    // Anchoring belongs to both kinds of target; only sizing is split. What the
-    // caller did not name is absent, and a placement nobody touched is absent
-    // entirely rather than sent as an empty object -- an empty object still
-    // claims the caller reached for placement.
+async function renderTwoD(args, target, placement) {
+    // Anchoring belongs to both kinds of target; only sizing is split, and the
+    // caller's tool already settled which sizing options exist. What the caller
+    // did not name is absent, and a placement nobody touched is absent entirely
+    // rather than sent as an empty object -- an empty object still claims the
+    // caller reached for placement.
     const sent = {
         ...(args.position === undefined ? {} : { position: args.position }),
         ...(args.offset_x === undefined ? {} : { offset_x: args.offset_x }),
@@ -1223,6 +1453,7 @@ async function renderPhotoMockup(args, target, placement) {
                 artwork_url: args.artwork_url,
                 ...(args.remove_background ? { remove_background: true } : {}),
                 adjustments: {
+                    ...(args.blend_mode === undefined ? {} : { blend_mode: args.blend_mode }),
                     opacity: args.opacity,
                     brightness: args.brightness,
                     contrast: args.contrast,
@@ -1241,13 +1472,13 @@ async function renderPhotoMockup(args, target, placement) {
         body.is_async = true;
     const result = await apiRequest({
         method: "POST",
-        path: `/api/v1/photo-mockups/${args.mockup_id}/render`,
+        path: `/api/v1/sudoai/2d-mockups/${args.mockup_uuid}/render`,
         body,
         timeout: RENDER_TIMEOUT,
     });
-    // is_async=true -> 202 + job_id (kind "photo_mockup_render" on this path);
-    // hand back the poll contract. Reuse get_job / wait_for_job to reach the
-    // terminal job (result_url).
+    // is_async=true -> 202 + job_id (kind "2d_render" on this path; the family
+    // spelling is "photo_mockup_render"); hand back the poll contract.
+    // Reuse get_job / wait_for_job to reach the terminal job (result_url).
     if (args.is_async) {
         return { content: [{ type: "text", text: formatJobAccepted(result) }] };
     }
@@ -1267,23 +1498,71 @@ async function renderPhotoMockup(args, target, placement) {
     };
     return { content: [{ type: "text", text: JSON.stringify(rendered, null, 2) }] };
 }
-server.registerTool("render_photo_mockup", {
-    description: "Render artwork onto a saved photo mockup. Name exactly one target: a print_area_uuid (a bounded zone somebody drew on the product, such as a chest logo; sized by fit or by width + height) or a surface_uuid (a whole printable product, for an all-over print; sized by coverage or by width + height). Read both from get_photo_mockup. Returns print_files (each with an export_path) and a render_uuid. Costs 5 credits. Use the dashboard for visual fine-tuning.",
-    inputSchema: renderPhotoMockupInput,
+// ---------------------------------------------------------------------------
+// Tool: render_2d_surface
+// ---------------------------------------------------------------------------
+server.registerTool("render_2d_surface", {
+    description: "Render artwork across a whole product surface -- an all-over print. Every printable product in the photo is a surface with its own surface_uuid, listed by get_2d_mockup. Returns print_files (each with an export_path) and a render_uuid. Costs 5 credits. Use the dashboard for visual fine-tuning.",
+    inputSchema: twoDRenderInput("surface", {
+        ...TWO_D_SHARED,
+        surface_uuid: z.string().describe("UUID of a product surface from get_2d_mockup's surfaces[]."),
+        coverage: z
+            .number()
+            .min(10)
+            .max(100)
+            .optional()
+            .describe("How much of the surface the artwork spans, as a percentage (10-100). Omit to span the whole surface, which is what an all-over print usually wants. Send width and height instead to give the artwork an exact size."),
+        // A percentage cannot express a box whose proportions differ from the
+        // surface's, which is exactly what an artwork resized on a canvas is.
+        width: z
+            .number()
+            .min(1)
+            .max(30000)
+            .optional()
+            .describe("Artwork width in pixels, drawn at that exact size rather than as a percentage of the surface. Send together with height, and without coverage."),
+        height: z
+            .number()
+            .min(1)
+            .max(30000)
+            .optional()
+            .describe("Artwork height in pixels. Send together with width, and without coverage. The two axes are independent, so any aspect ratio is allowed."),
+    }),
 }, async (args) => {
-    const hasPrintArea = args.print_area_uuid !== undefined;
-    const hasSurface = args.surface_uuid !== undefined;
-    if (hasPrintArea === hasSurface)
-        throw new Error(ONE_TARGET);
-    // The dial of the other kind of target is refused by name. Refusing is
-    // keyed on the argument being written rather than on the value it holds:
-    // writing it is the caller naming the option.
-    if (hasSurface && args.fit !== undefined)
-        throw new Error(FIT_ON_SURFACE);
-    if (hasPrintArea && args.coverage !== undefined)
-        throw new Error(COVERAGE_ON_PRINT_AREA);
     const sizing = {
         ...(args.coverage === undefined ? {} : { coverage: args.coverage }),
+        ...(args.width === undefined ? {} : { width: args.width }),
+        ...(args.height === undefined ? {} : { height: args.height }),
+    };
+    assertOneSizingAnswer(sizing, "coverage");
+    return renderTwoD(args, { surface_uuid: args.surface_uuid }, sizing);
+});
+// ---------------------------------------------------------------------------
+// Tool: render_2d_print_area
+// ---------------------------------------------------------------------------
+server.registerTool("render_2d_print_area", {
+    description: "Render artwork onto one saved print area -- a bounded zone somebody drew on the product, such as a chest logo. Read the print_area_id values from get_2d_mockup. Returns print_files (each with an export_path) and a render_uuid. Costs 5 credits. Use the dashboard for visual fine-tuning.",
+    inputSchema: twoDRenderInput("print_area", {
+        ...TWO_D_SHARED,
+        print_area_uuid: z.string().describe("UUID of a saved print area from get_2d_mockup's print_areas[] (its print_area_id)."),
+        fit: z
+            .enum(FIT_MODES)
+            .optional()
+            .describe("How the artwork meets the print area, which it always fills edge to edge: 'fit' keeps the proportions and fits inside (the default), 'fill' stretches to the edges, 'crop' fills and crops the overflow. 'contain' and 'cover' are the older names for 'fit' and 'crop' and are still accepted. Leave it out to get 'fit'. To sit inside the area with room around it, send width and height instead."),
+        width: z
+            .number()
+            .min(1)
+            .max(30000)
+            .optional()
+            .describe("Artwork width in print-area pixels. Send together with height, and without fit. Width and height are independent, so any aspect ratio is allowed - stretching on one axis only is a supported placement."),
+        height: z
+            .number()
+            .min(1)
+            .max(30000)
+            .optional()
+            .describe("Artwork height in print-area pixels. Send together with width. Sending only one of the two is rejected rather than silently completed, so the aspect ratio is never guessed for you."),
+    }),
+}, async (args) => {
+    const sizing = {
         ...(args.fit === undefined ? {} : { fit: args.fit }),
         ...(args.width === undefined ? {} : { width: args.width }),
         ...(args.height === undefined ? {} : { height: args.height }),
@@ -1292,20 +1571,20 @@ server.registerTool("render_photo_mockup", {
     // the half instead would render a size the caller never asked for with no
     // error to notice, and forwarding it spends a round trip to be told what
     // the shape already said.
-    assertOneSizingAnswer(sizing, hasSurface ? "coverage" : "fit");
-    return renderPhotoMockup(args, hasSurface ? { surface_uuid: args.surface_uuid } : { uuid: args.print_area_uuid }, sizing);
+    assertOneSizingAnswer(sizing, "fit");
+    return renderTwoD(args, { uuid: args.print_area_uuid }, sizing);
 });
 // ---------------------------------------------------------------------------
-// Tool: list_photo_mockups
+// Tool: list_2d_mockups
 // ---------------------------------------------------------------------------
-server.tool("list_photo_mockups", "List your saved photo mockup templates, made from product photos with no PSD. Returns each mockup's mockup_id, name, status, thumbnail, dimensions, and print_areas. Use the mockup_id with get_photo_mockup to read the print-area and surface UUIDs a render needs. Costs 0 credits.", {
+server.tool("list_2d_mockups", "List your saved photo mockup templates (no PSD). Returns each mockup's mockup_id, name, status, thumbnail, dimensions, and print_areas. Use the mockup_id with get_2d_mockup to read the print-area and surface UUIDs a render needs. Costs 0 credits.", {
     limit: z.number().min(1).max(100).default(20).describe("Results per page (1-100, default 20)"),
     offset: z.number().min(0).default(0).describe("Pagination offset (default 0)"),
     customizable_only: z.boolean().default(false).describe("Return only mockups ready for shopper customization"),
 }, async ({ limit, offset, customizable_only }) => {
     const result = await apiRequest({
         method: "GET",
-        path: "/api/v1/photo-mockups",
+        path: "/api/v1/sudoai/2d-mockups",
         params: { limit, offset, customizable_only },
     });
     return {
@@ -1316,14 +1595,14 @@ server.tool("list_photo_mockups", "List your saved photo mockup templates, made
     };
 });
 // ---------------------------------------------------------------------------
-// Tool: get_photo_mockup
+// Tool: get_2d_mockup
 // ---------------------------------------------------------------------------
-server.tool("get_photo_mockup", "Get one photo mockup's full details: the saved print_areas[] somebody drew on it, and the surfaces[] -- one entry per printable product in the photo. Pass a print_area_id as print_area_uuid, or a surfaces[].surface_uuid, to render_photo_mockup. Costs 0 credits.", {
-    mockup_id: z.string().describe("UUID of the photo mockup (mockup_id from list_photo_mockups)"),
+server.tool("get_2d_mockup", "Get one photo mockup's full details: the saved print_areas[] somebody drew on it, and the surfaces[], one entry per printable product in the photo. Pass a print_area_id to render_2d_print_area, or a surfaces[].surface_uuid to render_2d_surface. Costs 0 credits.", {
+    mockup_id: z.string().describe("UUID of the photo mockup (mockup_id from list_2d_mockups)"),
 }, async ({ mockup_id }) => {
     const result = await apiRequest({
         method: "GET",
-        path: `/api/v1/photo-mockups/${mockup_id}`,
+        path: `/api/v1/sudoai/2d-mockups/${mockup_id}`,
     });
     return {
         content: [{
@@ -1333,9 +1612,9 @@ server.tool("get_photo_mockup", "Get one photo mockup's full details: the saved
     };
 });
 // ---------------------------------------------------------------------------
-// Tool: update_photo_mockup_print_areas
+// Tool: update_2d_print_areas
 // ---------------------------------------------------------------------------
-server.tool("update_photo_mockup_print_areas", "Replace a photo mockup's print areas with up to 8 four-point quads and return the updated geometry. An empty list is accepted only for verified full product surfaces. Costs 0 credits.", {
+server.tool("update_2d_print_areas", "Replace a photo mockup's print areas with up to 8 four-point quads and return the updated geometry. An empty list is accepted only for verified full product surfaces. Costs 0 credits.", {
     mockup_id: z.string().describe("UUID of the photo mockup to update"),
     print_areas: z
         .array(z.object({
@@ -1351,7 +1630,7 @@ server.tool("update_photo_mockup_print_areas", "Replace a photo mockup's print a
 }, async ({ mockup_id, print_areas }) => {
     const result = await apiRequest({
         method: "PUT",
-        path: `/api/v1/photo-mockups/${mockup_id}/print-areas`,
+        path: `/api/v1/sudoai/2d-mockups/${mockup_id}/print-areas`,
         body: { print_areas },
     });
     const envelope = asRecord(result);
@@ -1368,14 +1647,14 @@ server.tool("update_photo_mockup_print_areas", "Replace a photo mockup's print a
     return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
 });
 // ---------------------------------------------------------------------------
-// Tool: delete_photo_mockup
+// Tool: delete_2d_mockup
 // ---------------------------------------------------------------------------
-server.tool("delete_photo_mockup", "Permanently delete a photo mockup template and all of its data. Cannot be undone. Costs 0 credits.", {
-    mockup_id: z.string().describe("UUID of the photo mockup to delete (mockup_id from list_photo_mockups)"),
+server.tool("delete_2d_mockup", "Permanently delete a photo mockup template and all of its data. Cannot be undone. Costs 0 credits.", {
+    mockup_id: z.string().describe("UUID of the photo mockup to delete (mockup_id from list_2d_mockups)"),
 }, async ({ mockup_id }) => {
     const result = await apiRequest({
         method: "DELETE",
-        path: `/api/v1/photo-mockups/${mockup_id}`,
+        path: `/api/v1/sudoai/2d-mockups/${mockup_id}`,
     });
     const envelope = asRecord(result);
     const data = asRecord(envelope.data ?? result);
@@ -1423,7 +1702,7 @@ server.tool("upload_psd", "Upload a Photoshop PSD/PSB file as a new mockup templ
 // ---------------------------------------------------------------------------
 // Tool: get_job
 // ---------------------------------------------------------------------------
-server.tool("get_job", "Get the current status of any async render, video, upload, or photo mockup (2D) job by its job_id. Returns status (queued|dispatched|running|succeeded|failed|cancelled), completed-result details and credits charged, or an error if failed. To block until done, use wait_for_job instead.", {
+server.tool("get_job", "Get the current status of any async render, video, upload, or photo mockup job by its job_id. Returns status (queued|running|succeeded|failed), completed-result details and credits charged, or an error if failed. To block until done, use wait_for_job instead.", {
     job_id: z.string().describe("The job_id returned by any async submission"),
 }, async ({ job_id }) => {
     const result = await getJob(job_id);
@@ -1432,7 +1711,7 @@ server.tool("get_job", "Get the current status of any async render, video, uploa
 // ---------------------------------------------------------------------------
 // Tool: list_jobs
 // ---------------------------------------------------------------------------
-server.tool("list_jobs", "List your async jobs, including PSD renders, videos, uploads, and photo mockup (2D) creation/renders, newest first. Use this when you do not already hold a job_id. Pass the returned next_cursor to fetch the next page.", {
+server.tool("list_jobs", "List your async jobs, including PSD renders, videos, uploads, and photo mockup creation and renders, newest first. Use this when you do not already hold a job_id. Pass the returned next_cursor to fetch the next page.", {
     kind: z
         .enum(["video", "render", "upload", "2d_create", "2d_render", "photo_mockup_create", "photo_mockup_render"])
         .optional()
@@ -1455,7 +1734,7 @@ server.tool("list_jobs", "List your async jobs, including PSD renders, videos, u
 // ---------------------------------------------------------------------------
 // Tool: wait_for_job
 // ---------------------------------------------------------------------------
-server.tool("wait_for_job", "Poll any async render, video, upload, or photo mockup (2D) job until it succeeds, fails, or is cancelled, then return the final result and credits charged. Blocks while polling.", {
+server.tool("wait_for_job", "Poll any async render, video, upload, or photo mockup job until it succeeds or fails, then return the final result and credits charged. Blocks while polling.", {
     job_id: z.string().describe("The job_id to wait on (from an async submission or render_video)"),
     poll_interval_seconds: z
         .number()
@@ -1493,13 +1772,13 @@ server.tool("wait_for_job", "Poll any async render, video, upload, or photo mock
 // Tool: render_video
 // ---------------------------------------------------------------------------
 server.tool("render_video", "Create a short AI video from either a mockup with artwork or a public image URL. Supply exactly one input mode. Always async: returns a job_id immediately for get_job or wait_for_job. Credit cost depends on clip length, audio, and the automatically selected quality. Unsupported durations are rejected.", {
-    mockup_uuid: z.string().optional().describe("RENDER MODE: UUID of the PSD mockup to animate (from list_psd_mockups or upload_psd). Required in render mode. In raw-image mode it is an optional association (groups the clip under that mockup's 'Past clips')."),
-    smart_object_uuid: z.string().optional().describe("RENDER MODE: UUID of the smart object layer to place artwork on (from get_psd_mockup). Required in render mode; omit in raw-image mode."),
+    mockup_uuid: z.string().optional().describe("RENDER MODE: UUID of the mockup to animate (from list_mockups or upload_psd). Required in render mode. In raw-image mode it is an optional association (groups the clip under that mockup's 'Past clips')."),
+    smart_object_uuid: z.string().optional().describe("RENDER MODE: UUID of the smart object layer to place artwork on (from get_mockup_details). Required in render mode; omit in raw-image mode."),
     artwork_url: z.string().optional().describe("RENDER MODE: public URL of the artwork image (PNG/JPG/WebP) to place on the mockup before animating. Provide this OR artwork_base64. Omit in raw-image mode."),
     artwork_base64: z.string().optional().describe("RENDER MODE: raw base64-encoded artwork bytes (no data: prefix). Provide this OR artwork_url."),
     artwork_content_type: z.enum(["image/png", "image/jpeg", "image/webp", "image/gif"]).optional().describe("MIME type for artwork_base64 (defaults to image/png if omitted)."),
     image_url: z.string().optional().describe("RAW-IMAGE MODE: a public https png/jpg URL to animate without a mockup. Supply this OR (mockup_uuid + smart_object_uuid + artwork), never both."),
-    fit: z.enum(["fill", "contain", "cover"]).default("fill").describe("RENDER MODE: how artwork fills the smart object area in the still frame"),
+    fit: z.enum(FIT_MODES).default("fill").describe(`RENDER MODE: how the artwork meets the smart object area in the still frame. ${SMART_OBJECT_FIT_HELP}`),
     asset_width: z.number().int().min(1).optional().describe("RENDER MODE: custom artwork width in pixels (overrides fit sizing)."),
     asset_height: z.number().int().min(1).optional().describe("RENDER MODE: custom artwork height in pixels (overrides fit sizing)."),
     asset_top: z.number().int().optional().describe("RENDER MODE: artwork top offset in pixels within the smart object area."),
@@ -1519,6 +1798,10 @@ server.tool("render_video", "Create a short AI video from either a mockup with a
         .enum(["ambient", "showcase"])
         .default("ambient")
         .describe("'ambient' = subtle looping hero motion that keeps the print readable; 'showcase' = one deliberate camera/product move."),
+    advanced_model: z
+        .string()
+        .optional()
+        .describe("Advanced override for the automatic quality selection. Unsupported values are rejected. Omit for automatic selection (recommended)."),
     image_format: z.enum(["webp", "png", "jpg"]).default("webp").describe("Output format of the still input frame"),
     image_size: z.number().min(100).max(10000).default(2048).describe("Width in pixels of the still input frame (default 2048)"),
     quality: z.number().min(1).max(100).default(90).describe("Compression quality for the still input frame (webp/jpg, default 90)"),
@@ -1532,6 +1815,8 @@ server.tool("render_video", "Create a short AI video from either a mockup with a
         audio: args.audio,
         motion: args.motion,
     };
+    if (args.advanced_model)
+        video.advanced_model = args.advanced_model;
     const body = {
         export_options: {
             image_format: args.image_format,
@@ -1581,7 +1866,7 @@ server.tool("render_video", "Create a short AI video from either a mockup with a
 // ---------------------------------------------------------------------------
 // Tool 8: get_account
 // ---------------------------------------------------------------------------
-server.tool("get_account", "Get your account info: subscription plan, remaining credits, prepaid balance, usage stats, billing period, and API key details. An account is funded by a subscription allowance or by a prepaid balance, so read both: an account paying as it goes reports 0 credits and pays from its balance. Quote funding_summary rather than reading the credits fields alone.", {}, async () => {
+server.tool("get_account", "Get your account info: the organization the API key belongs to, subscription plan, remaining credits, prepaid balance, usage stats, billing period, and API key details. The plan, credits and balance belong to that organization, so name it when you report them. An account is funded by a subscription allowance or by a prepaid balance, so read both: an account paying as it goes reports 0 credits and pays from its balance. Quote funding_summary rather than reading the credits fields alone.", {}, async () => {
     const result = await apiRequest({
         method: "GET",
         path: "/api/v1/me",
@@ -1614,10 +1899,11 @@ server.tool("get_account", "Get your account info: subscription plan, remaining
 // 2d_render.failed). Both spellings are subscribable; which one a delivery
 // carries is the endpoint's `event_naming` pin ('current' = family names,
 // 'legacy' = 2d_* names), and the payload's `kind` follows the same pin.
-// Endpoints created before the pin existed are 'legacy'; new endpoints default
-// to 'current' on the API side. The pin is set at create and changed at update;
-// a re-pin sent alone re-spells the stored subscription list to match. The list
-// below is in the API's own order.
+// Endpoints created before the pin existed are 'legacy'. A create without a pin
+// takes 'current' only when event_types names photo mockup events by their
+// family names alone, and 'legacy' otherwise. The pin is set at create and
+// changed at update; a re-pin sent alone re-spells the stored subscription list
+// to match. The list below is in the API's own order.
 // ---------------------------------------------------------------------------
 const WEBHOOK_EVENT_TYPES = [
     "render.succeeded",
@@ -1647,7 +1933,7 @@ server.tool("create_webhook_endpoint", "Register a webhook endpoint that SudoMoc
     event_naming: z
         .enum(WEBHOOK_EVENT_NAMINGS)
         .optional()
-        .describe("Which spelling of the photo mockup events this endpoint receives: 'current' (photo_mockup.*, photo_mockup_render.*, kind photo_mockup_create/photo_mockup_render) or 'legacy' (2d_mockup.*, 2d_render.*, kind 2d_create/2d_render). Omit to take the API default ('current'). Pick 'legacy' only for a receiver written against the old names."),
+        .describe("Which spelling of the photo mockup events this endpoint receives: 'current' (photo_mockup.*, photo_mockup_render.*, kind photo_mockup_create/photo_mockup_render) or 'legacy' (2d_mockup.*, 2d_render.*, kind 2d_create/2d_render). Omit to let event_types decide: 'current' when it names photo mockup events by their family names only, otherwise 'legacy' (an empty list, a list of events spelled the same either way, or any legacy name). Pick 'legacy' only for a receiver written against the old names."),
     description: z.string().max(255).optional().describe("Optional human-readable label for this endpoint"),
 }, async ({ url, event_types, event_naming, description }) => {
     const body = { url, event_types };
@@ -1780,6 +2066,20 @@ server.tool("replay_webhook_delivery", "Replay a single webhook delivery while p
             }],
     };
 });
+server.tool("replay_failed_webhook_deliveries", "Re-send every failed or dead delivery for a webhook endpoint in one call, e.g. after fixing your endpoint. Returns status and count: how many deliveries were queued to be sent again. To re-send a single delivery, use replay_webhook_delivery.", {
+    endpoint_id: z.string().describe("The id of the webhook endpoint whose failed deliveries are all sent again (from list_webhook_endpoints)"),
+}, async ({ endpoint_id }) => {
+    const result = await apiRequest({
+        method: "POST",
+        path: `/api/v1/webhook-endpoints/${endpoint_id}/deliveries/replay-failed`,
+    });
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify(publicWebhookBulkReplay(result), null, 2),
+            }],
+    };
+});
 // ---------------------------------------------------------------------------
 // Local file upload
 //
@@ -1887,6 +2187,242 @@ server.tool("upload_local_file", "Upload a file from this machine and get back a
             }],
     };
 });
+// The same signing call as upload_local_file, with the upload itself left to the
+// caller: the upload URL comes back in the result instead of being used here.
+// It is the tool for a file this process cannot read, and the name the hosted
+// server publishes for the same step.
+server.tool("create_upload_url", "Get a place to send a file that only exists on your machine. Every other tool takes a URL, so a local file has to be uploaded first. Returns an upload_url to PUT the bytes to and the file_url they will have afterwards; pass that file_url as psd_file_url to upload_psd, or as artwork_url to any render tool. Set kind to \"psd\" for a .psd or .psb template, or \"artwork\" for a .png, .jpg, .webp or .gif image. The upload target is scoped to a single file and cannot be overwritten or read back through the same URL. When the file is on the machine running this server, upload_local_file uploads it in one step. Costs 0 credits.", {
+    filename: z.string().describe("The file's name, e.g. shirt.psd. Only its extension is read, and a type that cannot be processed is refused."),
+    kind: z
+        .enum(["psd", "artwork"])
+        .default("psd")
+        .describe("\"psd\" for a .psd or .psb template, \"artwork\" for a .png, .jpg, .webp or .gif image."),
+}, async ({ filename, kind }) => {
+    const result = await apiRequest({
+        method: "POST",
+        path: "/api/v1/uploads/sign",
+        body: { filename, kind },
+    });
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify(publicUploadTarget(result), null, 2),
+            }],
+    };
+});
+// ---------------------------------------------------------------------------
+// Family names, added beside the names above
+// ---------------------------------------------------------------------------
+// The product names its two kinds of template PSD mockups and photo mockups,
+// and the tools are spelled that way too. Added, not substituted: a name that
+// shipped once is answered to forever, because a setup written against it is
+// not something we can see from here, and a caller who reached for the family
+// spelling in the window it existed is owed the same. Both spellings are
+// registered, both are supported, and neither is deprecated.
+/**
+ * Publish an already-registered tool under a second name.
+ *
+ * The two names share one handler and one input schema: the registration
+ * arguments are replayed with a different name, so there is no second copy to
+ * keep in step and no way for the two to drift apart. The original
+ * registration is not touched, including its description. `relation` is how
+ * the added description names the pairing.
+ */
+function alsoRegisterAs(existing, secondName, relation = "Family-name spelling") {
+    const source = registrations.get(existing);
+    if (source === undefined || source.method !== "tool") {
+        throw new Error(`Cannot publish ${secondName}: ${existing} has no replayable registration.`);
+    }
+    const [, description, ...rest] = source.args;
+    if (typeof description !== "string") {
+        throw new Error(`Cannot publish ${secondName}: ${existing} was registered without a description, ` +
+            "so replaying its arguments would drop the input schema and take any argument.");
+    }
+    server.tool(secondName, `${description} ${relation} of ${existing}: one tool under two names, same arguments, same behavior. Either name works.`, ...rest);
+}
+for (const [existing, familyName] of [
+    // PSD mockups.
+    ["list_mockups", "list_psd_mockups"],
+    ["get_mockup_details", "get_psd_mockup"],
+    ["update_mockup", "update_psd_mockup"],
+    ["delete_mockup", "delete_psd_mockup"],
+    ["render_mockup", "render_psd_mockup"],
+    // Photo mockups.
+    ["create_2d_mockup", "create_photo_mockup"],
+    ["list_2d_mockups", "list_photo_mockups"],
+    ["get_2d_mockup", "get_photo_mockup"],
+    ["update_2d_print_areas", "update_photo_mockup_print_areas"],
+    ["delete_2d_mockup", "delete_photo_mockup"],
+]) {
+    alsoRegisterAs(existing, familyName);
+}
+// ---------------------------------------------------------------------------
+// Names the hosted server publishes for tools this package already has
+// ---------------------------------------------------------------------------
+// The hosted server and this package offer one set of tools, so a setup moved
+// from one to the other keeps working. Where the hosted server calls a tool
+// that exists here by another name, that name is added here the same way the
+// family names are: the same handler and the same input schema.
+for (const [existing, secondName] of [
+    ["get_2d_mockup", "get_2d_mockup_details"],
+    ["test_webhook_endpoint", "send_webhook_test_event"],
+]) {
+    alsoRegisterAs(existing, secondName, "Second name");
+}
+// ---------------------------------------------------------------------------
+// Tool: render_photo_mockup
+// ---------------------------------------------------------------------------
+// The one family name that is not a second name for a single tool. Under the
+// 2D spelling a render picks its target by picking a tool; under the family
+// spelling one tool takes both kinds and the target is an argument, which is
+// the shape this name was published with. It is a dispatcher and nothing more:
+// the sizing rules, the refusals and the request itself are the same functions
+// `render_2d_surface` and `render_2d_print_area` call, so there is one
+// implementation of a 2D render on this side no matter which name reaches it.
+// The one field the two single-target tools do not offer is blend_mode, which
+// the hosted server publishes on this tool and on render_2d_mockup.
+const ONE_TARGET = "Provide exactly one of print_area_uuid or surface_uuid";
+// Every shared field belongs to this tool too; only the mockup's own argument
+// is spelled differently, as `mockup_id` -- the name this tool was published
+// with, and the name the photo mockup tools return the id under. `mockup_uuid`
+// is accepted beside it (see renderPhotoMockupInput).
+const { mockup_uuid: _twoDMockupUuid, ...PHOTO_RENDER_SHARED } = TWO_D_SHARED;
+// The target and the dials that size it. They are the same fields whichever
+// name the render is reached by, so they are written down once.
+const PHOTO_RENDER_TARGET = {
+    print_area_uuid: z
+        .string()
+        .optional()
+        .describe("UUID of a saved print area from get_photo_mockup's print_areas[] (its print_area_id): a bounded zone somebody drew on the product, such as a chest logo. Omit when surface_uuid is used."),
+    surface_uuid: z
+        .string()
+        .optional()
+        .describe("UUID of a product surface from get_photo_mockup's surfaces[]: a whole printable product, for an all-over print. Omit when print_area_uuid is used."),
+    coverage: z
+        .number()
+        .min(10)
+        .max(100)
+        .optional()
+        .describe("How much of the surface the artwork spans, as a percentage (10-100). Belongs to surface_uuid; sending it with print_area_uuid is refused. Omit to span the whole surface, which is what an all-over print usually wants. Send width and height instead to give the artwork an exact size."),
+    fit: z
+        .enum(FIT_MODES)
+        .optional()
+        .describe("How the artwork meets the print area, which it always fills edge to edge: 'fit' keeps the proportions and fits inside (the default), 'fill' stretches to the edges, 'crop' fills and crops the overflow. 'contain' and 'cover' are the older names for 'fit' and 'crop' and are still accepted. Belongs to print_area_uuid; sending it with surface_uuid is refused. Leave it out to get 'fit'. To sit inside the area with room around it, send width and height instead."),
+    // A percentage cannot express a box whose proportions differ from the
+    // target's, which is exactly what an artwork resized on a canvas is, so
+    // the exact box belongs to both kinds of target.
+    width: z
+        .number()
+        .min(1)
+        .max(30000)
+        .optional()
+        .describe("Artwork width in pixels, drawn at that exact size instead of by coverage or fit. Send together with height, and without coverage or fit. Width and height are independent, so any aspect ratio is allowed - stretching on one axis only is a supported placement."),
+    height: z
+        .number()
+        .min(1)
+        .max(30000)
+        .optional()
+        .describe("Artwork height in pixels. Send together with width. Sending only one of the two is rejected rather than silently completed, so the aspect ratio is never guessed for you."),
+};
+/** The strict input of a one-tool photo mockup render, refusing unknown options by name. */
+function photoRenderInput(shape) {
+    return z.strictObject(shape, {
+        error: (issue) => {
+            if (issue.code !== "unrecognized_keys")
+                return undefined;
+            return issue.keys
+                .map((key) => key === "scale"
+                ? RETIRED_SCALE
+                : `${key} is not an option on this tool. Send only the options it lists.`)
+                .join(" ");
+        },
+    });
+}
+// The blend the hosted server publishes on its one-tool photo mockup render,
+// under both of its names. Left out, nothing is sent and the API's default,
+// 'multiply', applies; the values are the ones the API accepts.
+const PHOTO_BLEND_MODE = {
+    blend_mode: z
+        .enum(["multiply", "normal", "screen", "lighten", "soft_light", "overlay", "darken"])
+        .optional()
+        .describe("How the artwork sits on the product: 'multiply' (the default) keeps the material texture visible, 'normal' reproduces the artwork colors exactly. 'screen', 'lighten', 'soft_light', 'overlay' and 'darken' are also accepted."),
+};
+// The mockup travels as `mockup_id`, the name this tool was published with, or
+// as `mockup_uuid`, the name the hosted server publishes it under. One of the
+// two is needed; both are accepted when they agree.
+const renderPhotoMockupInput = photoRenderInput({
+    mockup_id: z
+        .string()
+        .optional()
+        .describe("UUID of the photo mockup (mockup_id from list_photo_mockups, get_photo_mockup or create_photo_mockup). Send this or mockup_uuid."),
+    mockup_uuid: z
+        .string()
+        .optional()
+        .describe("Same as mockup_id, under the name the hosted server uses. Send this or mockup_id; if both are sent they must match."),
+    ...PHOTO_RENDER_SHARED,
+    ...PHOTO_RENDER_TARGET,
+    ...PHOTO_BLEND_MODE,
+});
+/** The photo mockup a render_photo_mockup call names, by either spelling. */
+function photoMockupId(mockupId, mockupUuid) {
+    if (mockupId !== undefined && mockupUuid !== undefined && mockupId !== mockupUuid) {
+        throw new Error("mockup_id and mockup_uuid name the same photo mockup but hold different values. Send one of them.");
+    }
+    const id = mockupId ?? mockupUuid;
+    if (id === undefined) {
+        throw new Error("Provide mockup_id (or mockup_uuid): the UUID of the photo mockup to render.");
+    }
+    return id;
+}
+/**
+ * Render one photo mockup target named by argument rather than by tool.
+ *
+ * Shared by every name that takes the target as an argument, so the refusals
+ * and the request are one implementation whichever of them is called.
+ */
+async function renderNamedTarget(args, mockupUuid) {
+    const hasPrintArea = args.print_area_uuid !== undefined;
+    const hasSurface = args.surface_uuid !== undefined;
+    if (hasPrintArea === hasSurface)
+        throw new Error(ONE_TARGET);
+    // The dial of the other kind of target is refused by name, in the words
+    // the tool that owns that dial already refuses it with. Refusing is keyed
+    // on the argument being written rather than on the value it holds: writing
+    // it is the caller naming the option.
+    if (hasSurface && args.fit !== undefined)
+        throw new Error(TWO_D_REFUSED_OPTIONS.surface.fit);
+    if (hasPrintArea && args.coverage !== undefined) {
+        throw new Error(TWO_D_REFUSED_OPTIONS.print_area.coverage);
+    }
+    const sizing = {
+        ...(args.coverage === undefined ? {} : { coverage: args.coverage }),
+        ...(args.fit === undefined ? {} : { fit: args.fit }),
+        ...(args.width === undefined ? {} : { width: args.width }),
+        ...(args.height === undefined ? {} : { height: args.height }),
+    };
+    assertOneSizingAnswer(sizing, hasSurface ? "coverage" : "fit");
+    return renderTwoD({ ...args, mockup_uuid: mockupUuid }, hasSurface ? { surface_uuid: args.surface_uuid } : { uuid: args.print_area_uuid }, sizing);
+}
+server.registerTool("render_photo_mockup", {
+    description: "Render artwork onto a saved photo mockup. Name exactly one target: a print_area_uuid (a bounded zone somebody drew on the product, such as a chest logo; sized by fit or by width + height) or a surface_uuid (a whole printable product, for an all-over print; sized by coverage or by width + height). Read both from get_photo_mockup. Returns print_files (each with an export_path) and a render_uuid. Costs 5 credits. Family-name spelling of render_2d_surface and render_2d_print_area, which stay available and behave exactly as they did. Use the dashboard for visual fine-tuning.",
+    inputSchema: renderPhotoMockupInput,
+}, async (args) => renderNamedTarget(args, photoMockupId(args.mockup_id, args.mockup_uuid)));
+// ---------------------------------------------------------------------------
+// Tool: render_2d_mockup
+// ---------------------------------------------------------------------------
+// The name the hosted server publishes render_photo_mockup under, and the name
+// this package's single render tool had before the render was split in two.
+// It is render_photo_mockup under a second name, with one difference in
+// spelling: the mockup travels as `mockup_uuid`, as it does on
+// render_2d_surface and render_2d_print_area and as that name always took it.
+server.registerTool("render_2d_mockup", {
+    description: "Render artwork onto a saved photo mockup. Name exactly one target: a print_area_uuid (a bounded zone somebody drew on the product, such as a chest logo; sized by fit or by width + height) or a surface_uuid (a whole printable product, for an all-over print; sized by coverage or by width + height). Read both from get_2d_mockup. Returns print_files (each with an export_path) and a render_uuid. Costs 5 credits. Second name of render_photo_mockup: the same tool and behavior, with the mockup passed as mockup_uuid. Use the dashboard for visual fine-tuning.",
+    inputSchema: photoRenderInput({
+        ...TWO_D_SHARED,
+        ...PHOTO_RENDER_TARGET,
+        ...PHOTO_BLEND_MODE,
+    }),
+}, async (args) => renderNamedTarget(args, args.mockup_uuid));
 // ---------------------------------------------------------------------------
 // Start server
 // ---------------------------------------------------------------------------