applaunchflow 0.3.2 → 0.3.3

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,7 +53,7 @@ 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.
 
@@ -97,7 +97,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 +105,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/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/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

@@ -177,7 +177,7 @@ 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 {
             const payload = decorateSocialTemplatePayload(await client.listSocialTemplates(), client.credentials.baseUrl);
             const availableIds = new Set(payload.templates.map((t) => t.id));
@@ -205,12 +205,15 @@ export function registerGraphicsTools(server, client) {
                 generationId,
                 catalogKey,
             });
+            const opened = await openUrl(server, galleryUrl, "Browse personalized 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.",
                         ].join("\n"),
@@ -230,6 +233,7 @@ export function registerGraphicsTools(server, client) {
                         userFacingUrl: galleryUrl,
                         format,
                         templateIds: filteredTemplateIds,
+                        browserOpened: opened,
                     },
                     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/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.3",
   "description": "Hosted OAuth MCP connector for AppLaunchFlow.",
   "license": "MIT",
   "repository": {