@sudomock/mcp 3.0.0 → 3.1.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,19 +802,19 @@ 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
 // ---------------------------------------------------------------------------
 const smartObjectInputSchema = z
     .object({
@@ -811,7 +879,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({
@@ -858,8 +926,8 @@ 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)"),
+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. 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. 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."),
     smart_objects: z
@@ -872,7 +940,7 @@ server.tool("render_psd_mockup", "Render a PSD mockup with artwork, editable tex
         .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."),
+        .describe("Editable text overrides from get_mockup_details. 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"),
     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)"),
@@ -1002,9 +1070,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 +1119,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 +1153,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 +1205,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.
 //
-// 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
+// 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 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 +1290,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 }),
@@ -1241,13 +1332,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 +1358,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(["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. Leave it out to get 'contain'. 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 +1431,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 +1455,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 +1472,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 +1490,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 +1507,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 +1562,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 +1571,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 +1594,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,8 +1632,8 @@ 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)."),
@@ -1581,7 +1720,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",
@@ -1780,6 +1919,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 +2040,209 @@ 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.
+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.
+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(["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
+    // 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(" ");
+        },
+    });
+}
+const renderPhotoMockupInput = photoRenderInput({
+    mockup_id: z
+        .string()
+        .describe("UUID of the photo mockup (mockup_id from list_photo_mockups, get_photo_mockup or create_photo_mockup)."),
+    ...PHOTO_RENDER_SHARED,
+    ...PHOTO_RENDER_TARGET,
+});
+/**
+ * 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, args.mockup_id));
+// ---------------------------------------------------------------------------
+// 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,
+    }),
+}, async (args) => renderNamedTarget(args, args.mockup_uuid));
 // ---------------------------------------------------------------------------
 // Start server
 // ---------------------------------------------------------------------------