applaunchflow 0.3.2 → 0.3.4

package/README.md

@@ -86,8 +86,10 @@ For App Store screenshots:
 
 1. `list_source_screenshots`
 2. `prepare_screenshot_styles` with 3-7 ordered paths
-3. `browse_templates` with the returned `templateIds`, `generationId`, and `catalogKey`
-4. `apply_screenshot_style` with the returned `catalogKey`
+3. The personalized gallery opens automatically. Compare each template's V1/V2 render and confirm the choice; the gallery creates the new variant from cache and opens the editor.
+
+`browse_templates` can reopen a prepared catalog, and `apply_screenshot_style`
+remains available when an API client supplies a template id directly.
 
 For social graphics:
 

package/build/index.js

@@ -42,7 +42,7 @@ Schema references (MCP resources — read them, they are not loaded automaticall
 Screenshot workflows:
 - Entry point without a known project: ask whether the user wants to create a new app or edit an existing project. If they want existing, list/select projects. If they want new, create the project first.
 - For the normal style-choice flow, call list_source_screenshots, choose 3-7 real screenshots in story order, then call prepare_screenshot_styles. This generates or reuses one personalized catalog containing every template for phone, tablet, and desktop.
-- After preparation, call browse_templates with exactly the returned templateIds plus generationId and catalogKey so the gallery renders the real personalized results. Then immediately call apply_screenshot_style with the returned catalogKey and selected templateId. Applying creates a new variant from cache without another AI call. Never overwrite an existing variant.
+- prepare_screenshot_styles opens the personalized gallery automatically. The user compares the real v1/v2 renders there; confirming a style creates a new variant from cache and opens the editor. Do not ask the user to paste a template id back into chat. Use browse_templates only to reopen the gallery, and apply_screenshot_style only when a template id was supplied directly in chat or by an API client. Never overwrite an existing variant.
 - Use generate_layouts only for an explicitly requested legacy/direct single-template generation. Do not use it for the normal visual style chooser.
 - For small, precise edits to existing known nodes, transform_layout can be used directly.
 - For any composition-sensitive edit, inspect the current layout first with get_layout. This includes adding screens, reusing screenshots, changing screenshot placement, moving text, changing spacing, or anything that should match the existing visual system.
@@ -53,13 +53,13 @@ Screenshot workflows:
 - When adding or editing elements, ensure text and screenshots do not overlap. Verify that positions place elements in distinct, non-conflicting areas of the canvas.
 - After composition-sensitive edits, inspect the returned translation or re-fetch the layout before reporting success. If elements overlap or are poorly positioned, fix them before telling the user the edit is done.
 - get_layout is mandatory before every direct transform_layout call. Do not edit a layout without a fresh read of the current state first.
-- ALWAYS use browse_templates after prepare_screenshot_styles when a screenshot template choice is needed. Pass the prepared templateIds, generationId, and catalogKey. Never offer templates via text bullet points. The connector returns a gallery URL, which you must show to the user before waiting for the selected template id.
+- Never offer screenshot templates via text bullet points. prepare_screenshot_styles opens the personalized picker automatically. If browser opening is unsupported, show its exact fallback gallery URL. Do not wait for a selected template id because the picker applies the choice directly.
 - When you need visual context about a screenshot (e.g. to extract colors, understand the app UI, or make context-specific edits), use view_screenshot to look at the actual image.
 - After generating a new variant, include the editor URL in the reply.
 
 Social graphics workflows (mirror the screenshot flow):
 - Call list_source_screenshots, select 3-7 real screenshots in story order, then call prepare_social_graphics_styles. This generates or reuses every social template across all six formats in one catalog.
-- Call browse_social_templates with the returned templateIds plus generationId and catalogKey so the gallery renders the personalized graphics, then immediately call apply_social_graphics_style with the selected templateId and catalogKey. Applying creates a fresh variant containing all six formats without another AI call.
+- prepare_social_graphics_styles opens the personalized gallery automatically. Confirming a style creates a fresh variant containing all six formats and opens the graphics editor. Do not ask the user to paste a template id back into chat. Use browse_social_templates only to reopen the gallery, and apply_social_graphics_style only when a template id was supplied directly in chat or by an API client.
 - Use generate_graphics only for an explicitly requested legacy/direct single-template generation. Never overwrite an existing graphics variant.
 - For edits to existing social graphics, ALWAYS call get_graphics_format first, then save_graphics_format. Mutate JSON for exactly one format in memory and save only that one format. The same get-before-edit receipt rule applies as for screenshots.
 - Default to the variant's primary format unless the user explicitly asks to edit another format.
@@ -68,7 +68,8 @@ Social graphics workflows (mirror the screenshot flow):
 - Use create_variant with contentType:"socialGraphics" or duplicate_variant to create a copy / fresh take without overwriting the current graphics variant.
 
 Promo video workflows:
-- generate_promo_video runs the AI generation pipeline against the project's screenshots and produces a complete Remotion video config. Omit variantId to create a new variant.
+- generate_promo_video prepares three transient, personalized candidates and opens the same dashboard picker used by the web app. No saved variant is created until the user chooses one. Do not summarize the three options in chat or ask for a candidate id.
+- To replace an existing promo-video variant, pass replaceVariantId only after explicit user approval. The chosen candidate is created first and the old variant is retired only after the new one saves successfully, so replacement works safely at the plan limit.
 - For edits to an existing promo video, ALWAYS call get_promo_video first to fetch the current config, mutate the config object in memory, then call update_promo_video with the full updated config. There is no granular transform tool for promo videos at this stage — full-config replace is the supported edit path. The same get-before-edit receipt rule as graphics applies: update_promo_video is locked until a fresh get_promo_video has been called for the same project/variant.
 - Use clear_promo_video to wipe a variant's video config when the user wants to start over.
 - Use create_variant with contentType:"promoVideo" or duplicate_variant for copies / A-B tests. duplicate_variant clones the source promo-video variant, including its config.
@@ -97,7 +98,7 @@ HOSTED CONNECTOR SAFETY RULES:
 - Never reveal, repeat, log, or place OAuth access tokens, refresh tokens, authorization codes, PKCE verifiers, or read receipts in user-facing text.
 - A readReceipt returned inside structured tool data is an opaque safety input. Pass it only to the matching edit tool, for the exact same project, variant, language, and format.
 - Before deleting, clearing, overwriting, or replacing user content, require clear user intent for that exact action. Do not infer destructive intent from a broad request.
-- Hosted gallery tools return a URL instead of opening a local browser. Show the exact URL, stop, and wait for the user's chosen template id. Do not guess or apply a style before the user selects it.
+- Hosted gallery tools request the MCP client to open the browser and always return the exact URL as a fallback. Personalized screenshot galleries apply the user's v1/v2 choice directly and open the new variant in the editor. Do not ask the user to relay the template id.
 
 ${SERVER_INSTRUCTIONS}
 `.trim();
@@ -105,7 +106,7 @@ export function createAppLaunchFlowServer(credentials) {
     const client = new AppLaunchFlowClient(credentials);
     const server = new McpServer({
         name: "applaunchflow-mcp",
-        version: "0.3.0",
+        version: "0.3.3",
     }, {
         instructions: HOSTED_SERVER_INSTRUCTIONS,
     });

package/build/promovideo-picker.test.js

@@ -0,0 +1,18 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { buildPromoVideoCandidateRequest, buildPromoVideoEditorUrl, } from "./tools/promovideo.js";
+test("generate_promo_video requests three transient candidates", () => {
+    assert.deepEqual(buildPromoVideoCandidateRequest({ projectId: "project", message: "fresh" }), { projectId: "project", message: "fresh", candidateCount: 3 });
+});
+test("the MCP opens the dashboard candidate picker instead of a saved variant", () => {
+    const url = new URL(buildPromoVideoEditorUrl({
+        credentials: { baseUrl: "https://dashboard.applaunchflow.com" },
+    }, {
+        generationId: "11111111-1111-4111-8111-111111111111",
+        candidateKey: "candidate-key",
+        replaceVariantId: "22222222-2222-4222-8222-222222222222",
+    }));
+    assert.equal(url.pathname, "/promovideo");
+    assert.equal(url.searchParams.get("candidateKey"), "candidate-key");
+    assert.equal(url.searchParams.get("replaceVariantId"), "22222222-2222-4222-8222-222222222222");
+});

package/build/resources/data.js

@@ -661,7 +661,7 @@ export const WORKFLOW_GUIDE_RESOURCE = {
             preferredSteps: [
                 "browse_templates",
             ],
-            notes: "Use browse_templates when the user needs to pick a template from the hosted visual gallery. Keep the full template catalog available unless the user asks for a shortlist.",
+            notes: "Use browse_templates for static discovery or to reopen a prepared catalog. It asks the MCP client to open the hosted visual gallery automatically. Keep the full template catalog available unless the user asks for a shortlist.",
         },
         {
             name: "Start screenshot work",
@@ -677,10 +677,8 @@ export const WORKFLOW_GUIDE_RESOURCE = {
             preferredSteps: [
                 "list_source_screenshots",
                 "prepare_screenshot_styles",
-                "browse_templates",
-                "apply_screenshot_style",
             ],
-            notes: "Select 3-7 real screenshots in story order and prepare the personalized catalog once. Browse only the returned template ids, then apply the selection from the catalog cache. The new variant includes phone, tablet, and desktop without a second AI call.",
+            notes: "Select 3-7 real screenshots in story order and prepare the personalized catalog once. Preparation opens the personalized v1/v2 gallery automatically; confirming there creates the cached selection as a new phone, tablet, and desktop variant without a second AI call.",
         },
         {
             name: "Prepare and apply personalized social graphics",
@@ -714,9 +712,9 @@ export const WORKFLOW_GUIDE_RESOURCE = {
         "Do not force menu-based interaction when the user already gave a concrete natural-language edit request.",
         "Do not reduce the template catalog to a tiny recommendation list unless the user explicitly asks for that.",
         "Do not describe templates without showing preview resources when template previews are available.",
-        "Do not read template previews one by one when browse_templates can show the full gallery in one step.",
+        "Do not read template previews one by one when prepare_screenshot_styles or browse_templates can open the full gallery.",
         "Do not begin a screenshot session with template browsing before the user has chosen create new app or edit existing project.",
-        "Do not use legacy generate_layouts or generate_graphics for the normal style chooser. Prepare a personalized catalog and apply the selected cached style instead.",
+        "Do not use legacy generate_layouts or generate_graphics for the normal style chooser. Prepare a personalized catalog and let its gallery apply the selected cached screenshot style.",
         "Do not invent fresh x/y positions, widths, screenshot scale values, or headline styling for new screens when the user wants to preserve the current design language.",
         "Do not report success for new screens or composition edits without checking that the new nodes match the surrounding screens and do not overlap key content.",
     ],

package/build/social-template-previews.js

@@ -40,6 +40,9 @@ export function buildSocialTemplateGalleryUrl(baseUrl, options) {
         url.searchParams.set("generationId", options.generationId);
         url.searchParams.set("catalogKey", options.catalogKey);
     }
+    if (options?.applySelection) {
+        url.searchParams.set("action", "apply");
+    }
     return url.toString();
 }
 function decorateSocialTemplate(template, baseUrl) {

package/build/social-template-previews.test.js

@@ -0,0 +1,17 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { buildSocialTemplateGalleryUrl } from "./social-template-previews.js";
+test("personalized social gallery URLs use the direct-apply flow", () => {
+    const url = new URL(buildSocialTemplateGalleryUrl("https://dashboard.applaunchflow.com", {
+        format: "og",
+        templateIds: ["social-orbit", "social-dark"],
+        generationId: "11111111-1111-4111-8111-111111111111",
+        catalogKey: "catalog-key",
+        applySelection: true,
+    }));
+    assert.equal(url.pathname, "/template-gallery");
+    assert.equal(url.searchParams.get("kind"), "social");
+    assert.equal(url.searchParams.get("format"), "og");
+    assert.equal(url.searchParams.get("ids"), "social-orbit,social-dark");
+    assert.equal(url.searchParams.get("action"), "apply");
+});

package/build/template-previews.js

@@ -39,6 +39,9 @@ export function buildTemplateGalleryUrl(baseUrl, options) {
         url.searchParams.set("generationId", options.generationId);
         url.searchParams.set("catalogKey", options.catalogKey);
     }
+    if (options?.applySelection) {
+        url.searchParams.set("action", "apply");
+    }
     return url.toString();
 }
 function decorateTemplate(template, baseUrl) {

package/build/template-previews.test.js

@@ -0,0 +1,18 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { buildTemplateGalleryUrl } from "./template-previews.js";
+test("personalized gallery URLs carry the generated catalog and direct-apply action", () => {
+    const url = new URL(buildTemplateGalleryUrl("https://dashboard.applaunchflow.com", {
+        deviceType: "phone",
+        templateIds: ["bold-frame", "minimal-clean"],
+        generationId: "11111111-1111-4111-8111-111111111111",
+        catalogKey: "catalog-key",
+        applySelection: true,
+    }));
+    assert.equal(url.pathname, "/template-gallery");
+    assert.equal(url.searchParams.get("device"), "phone");
+    assert.equal(url.searchParams.get("ids"), "bold-frame,minimal-clean");
+    assert.equal(url.searchParams.get("generationId"), "11111111-1111-4111-8111-111111111111");
+    assert.equal(url.searchParams.get("catalogKey"), "catalog-key");
+    assert.equal(url.searchParams.get("action"), "apply");
+});

package/build/tools/graphics.js

@@ -17,7 +17,8 @@ export function registerGraphicsTools(server, client) {
         title: "Prepare Personalized Social Graphics Styles",
         description: "Generate or reuse the project's personalized social-graphics style catalog before the user chooses a style. " +
             "This prepares every social template across OG image, social post, Instagram story, Play Store feature graphic, X banner, and LinkedIn banner in one AI call and returns a catalogKey. " +
-            "Next call browse_social_templates with the returned templateIds, generationId, and catalogKey, then apply_social_graphics_style. Repeating the same app context and screenshot paths reuses the cache.",
+            "The personalized gallery opens automatically and creates the chosen variant directly in the graphics editor. " +
+            "Repeating the same app context and screenshot paths reuses the cache.",
         inputSchema: {
             generationId: z.string().uuid(),
             selectedScreenshotPaths: z
@@ -46,6 +47,14 @@ export function registerGraphicsTools(server, client) {
             if (!result.catalogKey || templateIds.length === 0) {
                 throw new Error("The social graphics catalog response did not include a cache key and templates");
             }
+            const galleryUrl = buildSocialTemplateGalleryUrl(client.credentials.baseUrl, {
+                format: primaryFormat,
+                templateIds,
+                generationId,
+                catalogKey: result.catalogKey,
+                applySelection: true,
+            });
+            const opened = await openUrl(server, galleryUrl, "Choose a personalized social-graphics style, then create the new variant in the editor.", { signal: extra.signal });
             return {
                 content: [
                     {
@@ -56,9 +65,19 @@ export function registerGraphicsTools(server, client) {
                                 : "Prepared personalized social graphics across all six formats.",
                             `Catalog key: ${result.catalogKey}`,
                             `Available template ids: ${templateIds.join(", ")}`,
-                            "Next: call browse_social_templates with these templateIds, generationId, and this catalog key so the gallery shows the personalized results; then apply_social_graphics_style with the selected id.",
+                            opened
+                                ? "Opened the personalized social-graphics gallery in the browser."
+                                : `Open the personalized social-graphics gallery: ${galleryUrl}`,
+                            "Confirming a style creates a new variant containing all six formats and opens it in the graphics editor; no template id needs to be pasted back into chat.",
                         ].join("\n"),
                     },
+                    {
+                        type: "resource_link",
+                        uri: galleryUrl,
+                        name: "Open Personalized Social Graphics Gallery",
+                        mimeType: "text/html",
+                        description: "Personalized social-graphics previews with direct variant creation.",
+                    },
                 ],
                 structuredContent: {
                     success: true,
@@ -70,6 +89,8 @@ export function registerGraphicsTools(server, client) {
                         formats: [...SOCIAL_FORMATS],
                         primaryFormat,
                         selectedScreenshotPaths,
+                        galleryUrl,
+                        browserOpened: opened,
                     },
                     message: result.cacheHit
                         ? "Reused personalized social graphics styles"
@@ -147,7 +168,7 @@ export function registerGraphicsTools(server, client) {
     });
     server.registerTool("browse_social_templates", {
         title: "Browse & Select Social Template",
-        description: "Use this visual style gallery after prepare_social_graphics_styles, restricted to its returned templateIds, so the user can choose which prepared result to apply. It can also be used independently for static style discovery. Returns the selected template id. Never offer social templates via text or AskUserQuestion.",
+        description: "Open the visual social style gallery. With generationId and catalogKey from prepare_social_graphics_styles it renders personalized previews and creates the selected variant directly; without them it provides static style discovery. Never offer social templates via text or AskUserQuestion.",
         inputSchema: {
             format: z
                 .enum(SOCIAL_FORMATS)
@@ -177,8 +198,11 @@ export function registerGraphicsTools(server, client) {
                 .optional()
                 .describe("Catalog key from prepare_social_graphics_styles. Pass together with generationId."),
         },
-    }, async ({ format = "og", templateIds, selectedTemplateId, title, generationId, catalogKey, }) => {
+    }, async ({ format = "og", templateIds, selectedTemplateId, title, generationId, catalogKey, }, extra) => {
         try {
+            if (Boolean(generationId) !== Boolean(catalogKey)) {
+                return fail(new Error("generationId and catalogKey must be passed together to open personalized previews."));
+            }
             const payload = decorateSocialTemplatePayload(await client.listSocialTemplates(), client.credentials.baseUrl);
             const availableIds = new Set(payload.templates.map((t) => t.id));
             const filteredTemplateIds = templateIds?.filter((id) => availableIds.has(id)) || [];
@@ -204,15 +228,23 @@ export function registerGraphicsTools(server, client) {
                 title,
                 generationId,
                 catalogKey,
+                applySelection: Boolean(generationId && catalogKey),
             });
+            const opened = await openUrl(server, galleryUrl, generationId && catalogKey
+                ? "Choose a personalized social-graphics style, then create the new variant in the editor."
+                : "Browse social-graphics styles in AppLaunchFlow.", { signal: extra.signal });
             return {
                 content: [
                     {
                         type: "text",
                         text: [
-                            "Paste this exact gallery URL into the user-visible reply.",
+                            opened
+                                ? "Opened the social template gallery in the browser."
+                                : "The client could not open the browser automatically; paste this exact gallery URL into the user-visible reply.",
                             `Social template gallery URL: ${galleryUrl}`,
-                            "After you pick a template, reply with the template name or id.",
+                            generationId && catalogKey
+                                ? "The gallery shows the personalized renders. Confirming a style creates the variant across all six formats and opens the graphics editor directly."
+                                : "Static discovery mode copies the chosen template id.",
                         ].join("\n"),
                     },
                     {
@@ -230,6 +262,8 @@ export function registerGraphicsTools(server, client) {
                         userFacingUrl: galleryUrl,
                         format,
                         templateIds: filteredTemplateIds,
+                        browserOpened: opened,
+                        personalized: Boolean(generationId && catalogKey),
                     },
                     message: "Prepared social template gallery",
                 },

package/build/tools/localization.js

@@ -11,8 +11,8 @@ export function registerLocalizationTools(server, client) {
         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.",
+            "Requires a source screenshot layout to already exist — created by the personalized gallery, apply_screenshot_style, or generate_layouts. " +
+            "Pass the source variantId when available to translate that exact variant; if omitted, the active variant is used.",
         inputSchema: {
             generationId: z.string().uuid().describe("The project/generation UUID."),
             variantId: z

package/build/tools/promovideo.js

@@ -1,62 +1,79 @@
 import { z } from "zod";
 import { createHostedReadReceipt, createReadReceiptStore, fail, hostedMcpEnabled, ok, openUrl, verifyHostedReadReceipt, } from "./utils.js";
 const promoReceiptKey = (generationId, variantId) => ["promo-video", generationId, variantId || "active"].join("::");
-function buildPromoVideoEditorUrl(client, args) {
+export function buildPromoVideoEditorUrl(client, args) {
     const params = new URLSearchParams({ projectId: args.generationId });
     if (args.variantId) {
         params.set("variantId", args.variantId);
     }
+    if (args.candidateKey) {
+        params.set("candidateKey", args.candidateKey);
+    }
+    if (args.replaceVariantId) {
+        params.set("replaceVariantId", args.replaceVariantId);
+    }
     return `${client.credentials.baseUrl}/promovideo?${params.toString()}`;
 }
+export function buildPromoVideoCandidateRequest(args) {
+    return { ...args, candidateCount: 3 };
+}
 export function registerPromoVideoTools(server, client) {
     const promoVideoReadReceipts = createReadReceiptStore();
     server.registerTool("generate_promo_video", {
         title: "Generate Promo Video",
-        description: "Run AI generation against the project's screenshots and produce a complete Remotion promo video config. " +
-            "Omit variantId so a new variant is always created — never overwrite an existing promo-video variant. " +
-            "After generation, the promo video editor opens automatically. " +
-            "Use selectedScreenshotIndices to constrain which uploaded screenshots feed the LLM. " +
-            "Use the optional message field to pass natural-language regeneration feedback when iterating on an existing variant.",
+        description: "Generate or reuse three transient promo-video candidates from the project's screenshots. " +
+            "The dashboard picker opens automatically so the user can preview all three; only the chosen candidate becomes a saved variant. " +
+            "Use replaceVariantId only when the user explicitly chose to replace that existing variant, which also allows a safe swap at the plan limit. " +
+            "Use selectedScreenshotPaths to constrain which uploaded screenshots feed the candidates.",
         inputSchema: {
             projectId: z.string().uuid().describe("Project / generation UUID."),
             message: z
                 .string()
                 .optional()
-                .describe("Optional natural-language feedback for regeneration. Only meaningful when iterating on an existing variant."),
-            variantId: z
+                .describe("Optional creative direction applied to all three candidates."),
+            replaceVariantId: z
                 .string()
                 .uuid()
                 .optional()
-                .describe("DO NOT pass this for fresh takes. Only set when explicitly regenerating an existing variant."),
+                .describe("Existing promo-video variant to replace after the user chooses a candidate. Only pass with explicit user approval."),
+            selectedScreenshotPaths: z
+                .array(z.string().min(1))
+                .min(3)
+                .max(7)
+                .optional()
+                .describe("Optional project-relative phone screenshot paths from list_source_screenshots, in story order."),
             selectedScreenshotIndices: z
                 .array(z.number().int().min(0))
                 .optional()
-                .describe("Optional indices into the project's screenshots array. If omitted, the generator uses the project's default platform set."),
+                .describe("Legacy screenshot positions. Prefer selectedScreenshotPaths."),
         },
     }, async (args, extra) => {
         try {
-            const result = await client.generatePromoVideo(args);
-            const variantId = result?.variantId || args.variantId || "";
+            const result = await client.generatePromoVideo(buildPromoVideoCandidateRequest(args));
+            if (!result?.candidateKey || result?.candidates?.length !== 3) {
+                throw new Error("Promo video generation did not return a reusable three-option picker");
+            }
             const editorUrl = buildPromoVideoEditorUrl(client, {
                 generationId: args.projectId,
-                variantId,
+                candidateKey: result.candidateKey,
+                replaceVariantId: args.replaceVariantId,
             });
-            await openUrl(server, editorUrl, "Opening the generated promo video in the editor.", { signal: extra.signal });
+            await openUrl(server, editorUrl, "Compare three personalized promo-video candidates and choose which one to create.", { signal: extra.signal });
             return {
                 content: [
                     {
                         type: "text",
                         text: [
-                            "Generated promo video successfully.",
-                            `Editor URL: ${editorUrl}`,
-                            "IMPORTANT: Paste this exact editor URL in the reply so the user can open it.",
+                            "Prepared three personalized promo-video candidates without creating a saved variant yet.",
+                            `Candidate picker URL: ${editorUrl}`,
+                            "The dashboard picker previews all three options. Choosing one creates that variant and opens it in the promo-video editor.",
                         ].join("\n"),
                     },
                 ],
                 structuredContent: {
                     success: true,
                     data: { ...result, editorUrl },
-                    message: "Generated promo video",
+                    message: "Prepared promo video candidates",
                 },
             };
         }

package/build/tools/screenshots.js

@@ -1,13 +1,14 @@
 import { Buffer } from "node:buffer";
 import { z } from "zod";
 import { listPublicTemplateIds } from "../catalog.js";
+import { buildTemplateGalleryUrl } from "../template-previews.js";
 import { openUrl, fail, ok, startProgressHeartbeat } from "./utils.js";
 export function registerScreenshotTools(server, client) {
     server.registerTool("prepare_screenshot_styles", {
         title: "Prepare Personalized Screenshot Styles",
         description: "Generate or reuse the project's personalized screenshot-style catalog before the user chooses a style. " +
             "This prepares every screenshot template for phone, tablet, and desktop in one AI call and returns a catalogKey. " +
-            "Next call browse_templates with the returned templateIds, generationId, and catalogKey, then apply_screenshot_style with the selected templateId and catalogKey. " +
+            "The personalized gallery opens automatically, shows the real v1/v2 renders, and creates the chosen variant directly in the browser. " +
             "Repeating this with the same app context and screenshot paths is a cache hit and does not regenerate AI content.",
         inputSchema: {
             generationId: z.string().uuid().describe("Project/generation UUID."),
@@ -37,6 +38,14 @@ export function registerScreenshotTools(server, client) {
             if (!result.catalogKey || templateIds.length === 0) {
                 throw new Error("The screenshot catalog response did not include a cache key and templates");
             }
+            const galleryUrl = buildTemplateGalleryUrl(client.credentials.baseUrl, {
+                deviceType,
+                templateIds,
+                generationId,
+                catalogKey: result.catalogKey,
+                applySelection: true,
+            });
+            const opened = await openUrl(server, galleryUrl, "Choose a personalized screenshot style. Compare v1 and v2, then create the new variant in the editor.", { signal: extra.signal });
             return {
                 content: [
                     {
@@ -47,9 +56,19 @@ export function registerScreenshotTools(server, client) {
                                 : "Prepared personalized screenshot styles for phone, tablet, and desktop.",
                             `Catalog key: ${result.catalogKey}`,
                             `Available template ids: ${templateIds.join(", ")}`,
-                            "Next: call browse_templates with these templateIds, generationId, and this catalog key so the gallery shows the personalized results; then apply_screenshot_style with the selected id.",
+                            opened
+                                ? "Opened the personalized style gallery in the browser."
+                                : `Open the personalized style gallery: ${galleryUrl}`,
+                            "The gallery renders v1 and v2 from this catalog. Confirming a style creates a new variant and opens it in the editor; no template id needs to be pasted back into chat.",
                         ].join("\n"),
                     },
+                    {
+                        type: "resource_link",
+                        uri: galleryUrl,
+                        name: "Open Personalized Style Gallery",
+                        mimeType: "text/html",
+                        description: "Personalized screenshot previews with v1/v2 palette choices and direct variant creation.",
+                    },
                 ],
                 structuredContent: {
                     success: true,
@@ -60,6 +79,8 @@ export function registerScreenshotTools(server, client) {
                         templateIds,
                         devices: ["phone", "tablet", "desktop"],
                         selectedScreenshotPaths,
+                        galleryUrl,
+                        browserOpened: opened,
                     },
                     message: result.cacheHit
                         ? "Reused personalized screenshot styles"
@@ -77,7 +98,7 @@ export function registerScreenshotTools(server, client) {
     server.registerTool("apply_screenshot_style", {
         title: "Apply Personalized Screenshot Style",
         description: "Create a new screenshot variant from a previously prepared personalized style catalog without another AI generation. " +
-            "Use only after prepare_screenshot_styles and browse_templates. The new variant includes phone, tablet, and desktop layouts and opens in the editor.",
+            "Fallback for applying a template id supplied directly in chat or by an API client. The normal prepare_screenshot_styles flow now lets the user compare v1/v2 and create the variant directly in the browser. The new variant includes phone, tablet, and desktop layouts and opens in the editor.",
         inputSchema: {
             generationId: z.string().uuid(),
             catalogKey: z.string().min(1).max(128),
@@ -138,7 +159,7 @@ export function registerScreenshotTools(server, client) {
     });
     server.registerTool("generate_layouts", {
         title: "Generate Layouts",
-        description: "Legacy direct generation for a single screenshot template. For the normal user-facing style chooser, prefer prepare_screenshot_styles → browse_templates → apply_screenshot_style so all personalized previews are generated once and the chosen style is applied from cache. " +
+        description: "Legacy direct generation for a single screenshot template. For the normal user-facing style chooser, prefer prepare_screenshot_styles so all personalized v1/v2 previews are generated once and the browser applies the chosen style from cache. " +
             "Generate screenshot layouts for a project. " +
             "For existing projects, pass generationId (same as projectId) — the API fetches screenshots from storage automatically. " +
             "Do NOT pass screenshots when using generationId. " +

package/build/tools/templates.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { buildTemplateGalleryUrl, TEMPLATE_PREVIEW_DEVICE_TYPES, decorateTemplatePayload, } from "../template-previews.js";
-import { fail } from "./utils.js";
+import { fail, openUrl } from "./utils.js";
 function formatTemplateLine(template, deviceType) {
     const parts = [
         `${template.name} (${template.id})`,
@@ -98,7 +98,7 @@ function buildTemplateDetailsResult(payload) {
 export function registerTemplateTools(server, client) {
     server.registerTool("browse_templates", {
         title: "Browse & Select Template",
-        description: "Use this visual style gallery after prepare_screenshot_styles, restricted to its returned templateIds, so the user can choose which prepared result to apply. It can also be used independently for static style discovery. Returns the selected template id. Never offer templates via text or AskUserQuestion — always open this gallery.",
+        description: "Open the visual style gallery. With generationId and catalogKey from prepare_screenshot_styles it renders personalized v1/v2 previews and creates the selected variant directly; without them it provides static style discovery. Never offer templates via text or AskUserQuestion.",
         inputSchema: {
             deviceType: z
                 .enum(TEMPLATE_PREVIEW_DEVICE_TYPES)
@@ -128,8 +128,11 @@ export function registerTemplateTools(server, client) {
                 .optional()
                 .describe("Catalog key from prepare_screenshot_styles. Pass together with generationId."),
         },
-    }, async ({ deviceType = "phone", templateIds, selectedTemplateId, title, generationId, catalogKey, }) => {
+    }, async ({ deviceType = "phone", templateIds, selectedTemplateId, title, generationId, catalogKey, }, extra) => {
         try {
+            if (Boolean(generationId) !== Boolean(catalogKey)) {
+                return fail(new Error("generationId and catalogKey must be passed together to open personalized previews."));
+            }
             const payload = decorateTemplatePayload(await client.listTemplates(), client.credentials.baseUrl);
             const availableIds = new Set(payload.templates.map((template) => template.id));
             const filteredTemplateIds = templateIds?.filter((templateId) => availableIds.has(templateId)) || [];
@@ -156,16 +159,23 @@ export function registerTemplateTools(server, client) {
                 title,
                 generationId,
                 catalogKey,
+                applySelection: Boolean(generationId && catalogKey),
             });
+            const opened = await openUrl(server, galleryUrl, generationId && catalogKey
+                ? "Choose a personalized screenshot style. Compare v1 and v2, then create the new variant in the editor."
+                : "Browse screenshot styles in AppLaunchFlow.", { signal: extra.signal });
             return {
                 content: [
                     {
                         type: "text",
                         text: [
-                            "Paste this exact gallery URL into the user-visible reply.",
+                            opened
+                                ? "Opened the template gallery in the browser."
+                                : "The client could not open the browser automatically; paste this exact gallery URL into the user-visible reply.",
                             `Template gallery URL: ${galleryUrl}`,
-                            "Do not say 'link above' because tool results may be collapsed or hidden.",
-                            "After you pick a template, reply with the template name or id.",
+                            generationId && catalogKey
+                                ? "The gallery shows the personalized v1/v2 renders. Confirming a style creates the variant and opens the editor directly."
+                                : "Static discovery mode copies the chosen template id.",
                         ].join("\n"),
                     },
                     {
@@ -183,6 +193,8 @@ export function registerTemplateTools(server, client) {
                         userFacingUrl: galleryUrl,
                         deviceType,
                         templateIds: filteredTemplateIds,
+                        browserOpened: opened,
+                        personalized: Boolean(generationId && catalogKey),
                     },
                     message: "Prepared template gallery",
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "applaunchflow",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Hosted OAuth MCP connector for AppLaunchFlow.",
   "license": "MIT",
   "repository": {