applaunchflow 0.3.1

package/build/tools/layouts.js

@@ -0,0 +1,283 @@
+import { z } from "zod";
+import { createHostedReadReceipt, fail, hostedMcpEnabled, ok, verifyHostedReadReceipt, } from "./utils.js";
+const transformOperationSchema = z.object({
+    type: z.enum([
+        "update_node",
+        "delete_node",
+        "add_node",
+        "reorder",
+        "replace_color",
+    ]).describe("Operation type. replace_color is a find-and-replace for colors across the layout — use it for bulk color changes instead of updating each text node individually. " +
+        "Example: {type:'replace_color', target:{nodeType:'screen'}, changes:{find:'#F6EFE9', replace:'#7C3AED'}} replaces that color everywhere (text marks, icon colors, backgrounds). " +
+        "Use screens:'all' to replace across all screens, or screens:[6] for a single screen."),
+    target: z.object({
+        nodeType: z
+            .string()
+            .describe("REQUIRED. The node type to target: 'screen', 'text', 'screenshot', 'illustration', 'pill', 'badge', 'blob', 'rating', 'logo', 'emoji', 'header', 'panoramaBackground', 'backgroundImage'."),
+        nodeId: z
+            .string()
+            .optional()
+            .describe("Optional. Target a specific node by id. If omitted, the operation applies to ALL nodes of nodeType in the target screens."),
+        selector: z
+            .string()
+            .optional()
+            .describe("Optional. Target screens by id: 'screenId:<id>'. Do NOT use '#' prefix."),
+        screens: z
+            .union([z.literal("all"), z.array(z.number())])
+            .optional()
+            .describe("Optional. Target specific screens by index array (e.g. [0, 1, 2]) or 'all' for every screen. If omitted, targets all screens."),
+    }),
+    changes: z.record(z.any()),
+}).superRefine((operation, ctx) => {
+    // Require nodeType for all operations except replace_color
+    if (!operation.target.nodeType && operation.type !== "replace_color") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["target", "nodeType"],
+            message: "nodeType is required in target",
+        });
+        return;
+    }
+    const payload = operation.changes?.node &&
+        typeof operation.changes.node === "object" &&
+        !Array.isArray(operation.changes.node)
+        ? operation.changes.node
+        : operation.changes;
+    if (operation.type === "add_node") {
+        if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["changes"],
+                message: "add_node requires a node object in changes or changes.node",
+            });
+            return;
+        }
+        if (typeof payload.id !== "string" || payload.id.trim().length === 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["changes", "id"],
+                message: "add_node requires a non-empty id field",
+            });
+        }
+        if (operation.target.nodeType === "screen" &&
+            ("text" in payload || "screenshotPath" in payload)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["changes"],
+                message: "When adding a screen, only provide the screen container fields. Add screenshot and text nodes with separate add_node operations targeting that screen index.",
+            });
+        }
+    }
+});
+export function registerLayoutTools(server, client) {
+    const layoutReadReceipts = new Map();
+    function buildReadReceiptKey(args) {
+        return [args.generationId, args.language, args.variantId || "default"].join("::");
+    }
+    function buildEditorUrl(args) {
+        const params = new URLSearchParams({
+            projectId: args.generationId,
+            device: "phone",
+        });
+        if (args.variantId) {
+            params.set("variantId", args.variantId);
+        }
+        if (args.language) {
+            params.set("language", args.language);
+        }
+        return `${client.credentials.baseUrl}/editor?${params.toString()}`;
+    }
+    function buildVariantPreviewUrl(args) {
+        if (!args.variantId) {
+            return null;
+        }
+        const params = new URLSearchParams({
+            device: "phone",
+        });
+        if (args.language) {
+            params.set("language", args.language);
+        }
+        return `${client.credentials.baseUrl}/api/variants/${args.variantId}/preview?${params.toString()}`;
+    }
+    server.registerTool("get_layout", {
+        title: "Get Layout",
+        description: "Get layout JSON for the current translation before editing or reviewing a variant. " +
+            "This is mandatory before every direct transform_layout call. " +
+            "Returns the editor URL as a reference link — do NOT auto-open it. The user already has the editor open from the initial generation. " +
+            "The returned JSON follows the layout schema documented in the resource applaunchflow://schema/layout — read it to learn which fields exist and their valid ranges, not just which ones happen to be set here.",
+        inputSchema: {
+            generationId: z.string().uuid(),
+            language: z.string().optional(),
+            variantId: z.string().uuid().optional(),
+            sign: z.boolean().optional(),
+        },
+    }, async ({ generationId, language, variantId, sign }, extra) => {
+        try {
+            const layout = await client.getLayout({
+                generationId,
+                language,
+                variantId,
+                sign,
+            });
+            const hasEditReceipt = Boolean(language);
+            let readReceipt;
+            if (language) {
+                const receiptKey = buildReadReceiptKey({
+                    generationId,
+                    language,
+                    variantId,
+                });
+                layoutReadReceipts.set(receiptKey, Date.now());
+                if (hostedMcpEnabled()) {
+                    readReceipt = createHostedReadReceipt(receiptKey, client.credentials.token);
+                }
+            }
+            const editorUrl = buildEditorUrl({ generationId, language, variantId });
+            const previewUrl = buildVariantPreviewUrl({ language, variantId });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Fetched layout data.",
+                            `Editor URL: ${editorUrl}`,
+                            previewUrl ? `Preview URL: ${previewUrl}` : null,
+                            hasEditReceipt
+                                ? "A fresh get_layout read is now recorded for this generation/language/variant and can be used for one transform_layout call."
+                                : "No edit receipt was recorded because language was omitted. Provide language when reading a layout you intend to transform.",
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    data: {
+                        layout,
+                        editorUrl,
+                        previewUrl,
+                        readBeforeEditSatisfied: hasEditReceipt,
+                        readReceipt,
+                    },
+                    message: "Fetched layout data",
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("save_layout", {
+        title: "Save Layout",
+        description: "Persist a full translation layout payload. Whole-layout replace per device size — prefer transform_layout for targeted edits. " +
+            "Each layout must be a complete, valid Layout object; see the resource applaunchflow://schema/layout for every field and valid value range.",
+        inputSchema: {
+            generationId: z.string().uuid(),
+            language: z.string(),
+            variantId: z.string().uuid().optional(),
+            mobileLayout: z
+                .record(z.any())
+                .describe("Complete Layout object for the phone canvas. Shape documented in applaunchflow://schema/layout."),
+            tabletLayout: z
+                .record(z.any())
+                .describe("Complete Layout object for the tablet canvas. Same shape as mobileLayout, different canvasWidth/canvasHeight."),
+            desktopLayout: z
+                .record(z.any())
+                .nullable()
+                .optional()
+                .describe("Optional complete Layout object for the desktop canvas. Same shape as mobileLayout."),
+        },
+    }, async (args, extra) => {
+        try {
+            return ok(await client.saveLayout(args), "Saved layout");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("transform_layout", {
+        title: "Transform Layout",
+        description: "Apply transform operations to an existing layout. Primary editing tool for text, screenshots, colors, and structure changes. " +
+            "IMPORTANT: Always call get_layout FIRST to inspect the current layout state before using this tool. Never transform blindly. " +
+            "ENFORCED RULE: each transform_layout call requires a fresh get_layout call for the same generationId, language, and variantId immediately beforehand. " +
+            "RULES: " +
+            "1. nodeType is REQUIRED in every operation target. " +
+            "2. Omit nodeId to update ALL nodes of that type in the target screens. " +
+            "3. Use screens:'all' to target every screen at once. Do NOT send one operation per screen when the same change applies to all. " +
+            "4. Dot-notation is supported for deep updates without replacing the whole object. Example: {'richContent.attrs.defaultFontSize': 96} updates only the font size inside richContent.attrs, preserving all other fields. Always use dot-notation for nested property changes. " +
+            "5. For add_node, changes MUST include an 'id' field. " +
+            "6. To add new screens, first add empty screen containers, then populate them in a SECOND call using selector 'screenId:<id>'. " +
+            "7. Default to layouts:['mobile']. Only include tablet/desktop if the user asks. " +
+            "8. FONT SIZE: The rendered font size is controlled ONLY by 'richContent.attrs.defaultFontSize' (pixel value). To change font size, use dot-notation: {'richContent.attrs.defaultFontSize': 80}. Do NOT use 'fontSizeScale' — that property is for promo videos only and has NO effect on screenshot rendering. " +
+            "SCHEMA REFERENCE: read the resource applaunchflow://schema/transforms for the full operation and selector reference, and applaunchflow://schema/layout for every node type's fields and valid value ranges. Read them before any non-trivial edit rather than guessing field names.",
+        inputSchema: {
+            generationId: z.string().uuid(),
+            language: z.string(),
+            variantId: z.string().uuid().optional(),
+            atomic: z.boolean().optional(),
+            layouts: z
+                .array(z.enum(["mobile", "tablet", "desktop"]))
+                .optional()
+                .describe("Which layout sizes to transform. Default to ['mobile'] unless the user explicitly asks for tablet or desktop."),
+            operations: z.array(transformOperationSchema).min(1),
+            readReceipt: z
+                .string()
+                .optional()
+                .describe("Hosted connector only: pass the readReceipt returned by the immediately preceding get_layout call."),
+        },
+    }, async (args, extra) => {
+        try {
+            const receiptKey = buildReadReceiptKey({
+                generationId: args.generationId,
+                language: args.language,
+                variantId: args.variantId,
+            });
+            const hasReceipt = hostedMcpEnabled()
+                ? verifyHostedReadReceipt(args.readReceipt, receiptKey, client.credentials.token)
+                : layoutReadReceipts.has(receiptKey);
+            if (!hasReceipt) {
+                return fail(new Error("Call get_layout first for this generation/language/variant before transform_layout. Direct layout editing is locked until the current layout has been read."));
+            }
+            const { readReceipt: _readReceipt, ...transformArgs } = args;
+            const transformed = await client.transformLayout(transformArgs);
+            layoutReadReceipts.delete(receiptKey);
+            const editorUrl = buildEditorUrl({
+                generationId: args.generationId,
+                language: args.language,
+                variantId: args.variantId,
+            });
+            const previewUrl = buildVariantPreviewUrl({
+                language: args.language,
+                variantId: args.variantId,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Applied layout transform.",
+                            `Editor URL (already open — do NOT run \`open\` again): ${editorUrl}`,
+                            previewUrl ? `Preview URL: ${previewUrl}` : null,
+                            "This transform consumed the current read receipt. Call get_layout again before the next direct edit.",
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    data: {
+                        result: transformed,
+                        editorUrl,
+                        previewUrl,
+                        nextEditRequiresFreshRead: true,
+                    },
+                    message: "Applied layout transform",
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/build/tools/localization.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { fail, ok } from "./utils.js";
+const SUPPORTED_LANGUAGE_CODES = [
+    "en", "es", "fr", "de", "it", "pt", "pt-BR", "ja", "ko",
+    "zh-CN", "zh-TW", "nl", "ru", "ar", "tr", "pl", "sv",
+    "no", "da", "fi", "cs", "hi", "hu", "ro", "uk",
+];
+export function registerLocalizationTools(server, client) {
+    server.registerTool("translate_layouts", {
+        title: "Translate Layouts",
+        description: "Translate screenshot layouts into one or more target languages using AI. " +
+            "This is the PREFERRED way to localize screenshots — do NOT manually edit text nodes for translation. " +
+            "The backend translates all text in the layout while preserving positioning, styling, and screenshots. " +
+            "Requires a source screenshot layout to already exist — created via apply_screenshot_style (the normal flow) or generate_layouts. " +
+            "Pass the variantId returned by apply_screenshot_style/generate_layouts to translate that exact variant; if omitted, the active variant is used.",
+        inputSchema: {
+            generationId: z.string().uuid().describe("The project/generation UUID."),
+            variantId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Variant to translate. If omitted, uses the active variant."),
+            targetLanguages: z
+                .array(z.enum(SUPPORTED_LANGUAGE_CODES))
+                .min(1)
+                .describe("Array of target language codes (e.g. ['en', 'ja', 'de']). The source language is auto-detected and excluded."),
+            layouts: z
+                .array(z.enum(["mobile", "tablet", "desktop"]))
+                .optional()
+                .describe("Which layout sizes to translate. Defaults to ['mobile', 'tablet']. Include 'desktop' only if the project has a desktop layout."),
+        },
+    }, async (args) => {
+        try {
+            const body = {
+                ...args,
+                layouts: args.layouts || ["mobile", "tablet"],
+            };
+            return ok(await client.translateLayouts(body), "Translated layouts");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("list_translations", {
+        title: "List Translations",
+        description: "List available translations for a project variant. Returns which languages have been translated.",
+        inputSchema: {
+            generationId: z.string().uuid(),
+            variantId: z.string().uuid().optional(),
+        },
+    }, async ({ generationId, variantId }) => {
+        try {
+            return ok(await client.getLayout({ generationId, variantId }), "Fetched translations");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/build/tools/mockups.js

@@ -0,0 +1,324 @@
+import { z } from "zod";
+import { createHostedReadReceipt, createReadReceiptStore, fail, hostedMcpEnabled, ok, openUrl, verifyHostedReadReceipt, } from "./utils.js";
+const mockupReceiptKey = (generationId, variantId) => ["mockup", generationId, variantId || "active"].join("::");
+const SCENE_PRESET_IDS = [
+    "hero-launch",
+    "pivot-showcase",
+    "slow-rotate",
+    "drifting-tilt",
+];
+const OUTPUT_RATIOS = ["1:1", "4:3", "16:9", "9:16"];
+const MOCKUP_PRESETS_DATA = {
+    motions: [
+        { id: "hero-reveal", label: "Hero reveal", durationSeconds: 6 },
+        { id: "feature-sweep", label: "Feature sweep", durationSeconds: 7 },
+        { id: "showcase-orbit", label: "Showcase orbit", durationSeconds: 10 },
+        { id: "parallax-tilt", label: "Parallax tilt", durationSeconds: 8 },
+    ],
+    finishes: [
+        { id: "silver", label: "Silver" },
+        { id: "cosmic-orange", label: "Cosmic Orange" },
+        { id: "deep-blue", label: "Deep Blue" },
+    ],
+    backgroundPresets: [
+        { id: "soft", label: "Soft" },
+        { id: "paper", label: "Paper" },
+        { id: "midnight", label: "Midnight" },
+        { id: "transparent", label: "Transparent" },
+    ],
+    backgroundModes: ["color", "gradient", "image"],
+    outputRatios: [
+        { id: "4:3", label: "Classic", detail: "1440×1080 (default)" },
+        { id: "1:1", label: "Square", detail: "1080×1080" },
+        { id: "16:9", label: "Landscape", detail: "1920×1080" },
+        { id: "9:16", label: "Portrait", detail: "1080×1920" },
+    ],
+    easings: ["linear", "ease-in", "ease-out", "ease-in-out"],
+    scenePresets: [
+        {
+            id: "hero-launch",
+            label: "Cinematic swing",
+            motion: "hero-reveal",
+            keyframeCount: 4,
+            motionDurationSeconds: 6,
+        },
+        {
+            id: "pivot-showcase",
+            label: "Spin reveal",
+            motion: "feature-sweep",
+            keyframeCount: 4,
+            motionDurationSeconds: 7,
+        },
+        {
+            id: "slow-rotate",
+            label: "Drop & zoom",
+            motion: "showcase-orbit",
+            keyframeCount: 5,
+            motionDurationSeconds: 10,
+        },
+        {
+            id: "drifting-tilt",
+            label: "Punch zoom",
+            motion: "parallax-tilt",
+            keyframeCount: 4,
+            motionDurationSeconds: 8,
+        },
+    ],
+    stateBounds: {
+        speed: { min: 0.7, max: 1.4 },
+        motionDuration: { min: 1, max: 60 },
+        deviceScale: { min: 0.7, max: 1.3 },
+        primaryKeyframes: { minCount: 2, maxCount: 8 },
+    },
+    keyframeBounds: {
+        time: { min: 0, max: 1, note: "Normalized position along the animation." },
+        x: { min: -3, max: 3 },
+        y: { min: -3, max: 3 },
+        rotationX: { min: -6.283185307179586, max: 6.283185307179586 },
+        rotationY: { min: -6.283185307179586, max: 6.283185307179586 },
+        rotationZ: { min: -6.283185307179586, max: 6.283185307179586 },
+        scale: { min: 0.2, max: 3 },
+    },
+};
+function buildMockupEditorUrl(client, args) {
+    const params = new URLSearchParams({ projectId: args.generationId });
+    if (args.variantId) {
+        params.set("variantId", args.variantId);
+    }
+    return `${client.credentials.baseUrl}/mockups?${params.toString()}`;
+}
+export function registerMockupTools(server, client) {
+    const mockupReadReceipts = createReadReceiptStore();
+    server.registerTool("create_mockup_animation", {
+        title: "Create Mockup Animation",
+        description: "Create a new mockup-animation variant seeded from a SCENE_PRESETS preset and a specific screenshot/recording path. " +
+            "Always omit variantId — this tool always creates a new variant. Never overwrites an existing mockup variant. " +
+            "Call list_mockup_media first to pick a valid screenshotPath and list_mockup_presets to pick a presetId. " +
+            "The editor opens automatically after creation.",
+        inputSchema: {
+            projectId: z.string().uuid().describe("Project / generation UUID."),
+            screenshotPath: z
+                .string()
+                .min(1)
+                .describe('Storage-relative path for the device screen content, e.g. "mockups/1715191234567-clip.mp4" or "mobile/ios/1715191234567-home.png". Returned by list_mockup_media.'),
+            presetId: z
+                .enum(SCENE_PRESET_IDS)
+                .describe("Scene preset id: 'hero-launch' (cinematic swing), 'pivot-showcase' (spin reveal), 'slow-rotate' (drop & zoom), or 'drifting-tilt' (punch zoom)."),
+            outputRatio: z
+                .enum(OUTPUT_RATIOS)
+                .optional()
+                .describe("Optional output aspect ratio. Defaults to 4:3 (classic)."),
+            motionDurationSeconds: z
+                .number()
+                .min(1)
+                .max(60)
+                .optional()
+                .describe("Optional override for the animation loop length (seconds). For video screenshotPath, pass the recording duration so the loop matches one cycle."),
+            label: z
+                .string()
+                .min(1)
+                .max(120)
+                .optional()
+                .describe("Optional variant label shown in the studio's variant dropdown."),
+        },
+    }, async (args, extra) => {
+        try {
+            const result = await client.createMockupAnimation({
+                generationId: args.projectId,
+                screenshotPath: args.screenshotPath,
+                presetId: args.presetId,
+                outputRatio: args.outputRatio,
+                motionDurationSeconds: args.motionDurationSeconds,
+                label: args.label,
+            });
+            const variantId = result?.variantId || "";
+            const editorUrl = buildMockupEditorUrl(client, {
+                generationId: args.projectId,
+                variantId,
+            });
+            await openUrl(server, editorUrl, "Opening the new mockup animation in the editor.", { signal: extra.signal });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Created mockup animation variant.",
+                            `Editor URL: ${editorUrl}`,
+                            "IMPORTANT: Paste this exact editor URL in the reply so the user can open it.",
+                            "To fine-tune the animation, call get_mockup_animation for this variant before update_mockup_animation.",
+                        ].join("\n"),
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    data: { ...result, editorUrl },
+                    message: "Created mockup animation",
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("get_mockup_animation", {
+        title: "Get Mockup Animation",
+        description: "Fetch the current mockup animation state (MockupProjectState shape) for a project. " +
+            "Required before update_mockup_animation so edits operate on fresh state.",
+        inputSchema: {
+            generationId: z.string().uuid(),
+            variantId: z.string().uuid().optional(),
+        },
+    }, async ({ generationId, variantId }) => {
+        try {
+            const result = await client.getMockupAnimation(generationId, variantId);
+            const editorUrl = buildMockupEditorUrl(client, {
+                generationId,
+                variantId,
+            });
+            mockupReadReceipts.record({ generationId, variantId });
+            const readReceipt = hostedMcpEnabled()
+                ? createHostedReadReceipt(mockupReceiptKey(generationId, variantId), client.credentials.token)
+                : undefined;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Fetched mockup animation.",
+                            `Editor URL: ${editorUrl}`,
+                            "A fresh read receipt was recorded and can be used for one update_mockup_animation call.",
+                        ].join("\n"),
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    data: {
+                        ...result,
+                        editorUrl,
+                        readBeforeEditSatisfied: true,
+                        readReceipt,
+                    },
+                    message: "Fetched mockup animation",
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("update_mockup_animation", {
+        title: "Update Mockup Animation",
+        description: "Persist a mockup animation state (the same MockupProjectState shape returned by get_mockup_animation). " +
+            "This is a full-state replace — fetch the current state with get_mockup_animation, mutate the parts you want to change, then call this tool with the updated object. " +
+            "There is no granular per-keyframe transform; whole-state replace is the supported edit path. " +
+            "ENFORCED: each call requires a fresh get_mockup_animation for the same projectId/variantId immediately beforehand. " +
+            "Validation bounds (see list_mockup_presets for the full reference): primaryKeyframes count 2–8, time 0–1, x/y -3..3, rotations -2π..2π, scale 0.2..3, speed 0.7..1.4, motionDuration 1..60, deviceScale 0.7..1.3.",
+        inputSchema: {
+            projectId: z.string().uuid(),
+            variantId: z.string().uuid().optional(),
+            state: z
+                .record(z.any())
+                .describe("Full MockupProjectState object (selectedMediaPath, motion, finish, speed, background, backgroundMode, backgroundColor, backgroundGradient, backgroundImage, showDynamicIsland, outputRatio, motionDuration, deviceScale, primaryKeyframes, isPlaying). Use the object returned by get_mockup_animation as a starting point."),
+            readReceipt: z
+                .string()
+                .optional()
+                .describe("Hosted connector only: pass the readReceipt returned by the immediately preceding get_mockup_animation call."),
+        },
+    }, async (args) => {
+        try {
+            const receiptArgs = {
+                generationId: args.projectId,
+                variantId: args.variantId,
+            };
+            const hasReceipt = hostedMcpEnabled()
+                ? verifyHostedReadReceipt(args.readReceipt, mockupReceiptKey(args.projectId, args.variantId), client.credentials.token)
+                : mockupReadReceipts.has(receiptArgs);
+            if (!hasReceipt) {
+                return fail(new Error("Call get_mockup_animation first for this project/variant before update_mockup_animation. Direct editing is locked until the current state has been read."));
+            }
+            const result = await client.updateMockupAnimation({
+                generationId: args.projectId,
+                variantId: args.variantId,
+                state: args.state,
+            });
+            mockupReadReceipts.consume(receiptArgs);
+            const editorUrl = buildMockupEditorUrl(client, {
+                generationId: args.projectId,
+                variantId: args.variantId,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Updated mockup animation.",
+                            `Editor URL (already open — do NOT run \`open\` again): ${editorUrl}`,
+                            "This update consumed the current read receipt. Call get_mockup_animation again before the next direct edit.",
+                        ].join("\n"),
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    data: {
+                        result,
+                        editorUrl,
+                        nextEditRequiresFreshRead: true,
+                    },
+                    message: "Updated mockup animation",
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("list_mockup_media", {
+        title: "List Mockup Media",
+        description: "List the screenshots and screen recordings uploaded under the project's mockups/ storage folder. " +
+            "Call this before create_mockup_animation to discover valid screenshotPath values. " +
+            "Returns media items with { path, signedUrl, kind: 'image' | 'video' }.",
+        inputSchema: {
+            projectId: z.string().uuid(),
+        },
+    }, async ({ projectId }) => {
+        try {
+            const result = await client.listMockupMedia(projectId);
+            return ok(result, "Listed mockup media");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("list_mockup_presets", {
+        title: "List Mockup Presets",
+        description: "Return the structured set of valid mockup configuration values: motion presets, device finishes, background presets, output ratios, scene presets, and validation bounds. " +
+            "Use before constructing an update_mockup_animation payload to pick valid enum values without round-tripping through the server validator. " +
+            "If projectId is supplied, also returns the active screenshots variant's themeColors so the LLM can pick on-brand swatches for backgroundColor / gradient.",
+        inputSchema: {
+            projectId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Optional generation UUID to also fetch theme colors."),
+        },
+    }, async ({ projectId }) => {
+        try {
+            let themeColors = null;
+            if (projectId) {
+                try {
+                    const themeResult = await client.getMockupThemeColors(projectId);
+                    themeColors = themeResult?.themeColors ?? null;
+                }
+                catch {
+                    // Theme colors are optional — a missing screenshots variant is not
+                    // a failure for the presets lookup.
+                    themeColors = null;
+                }
+            }
+            return ok({ ...MOCKUP_PRESETS_DATA, themeColors }, "Mockup preset reference");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}