applaunchflow 0.3.3 → 0.3.4

package/build/index.js

@@ -59,7 +59,7 @@ Screenshot workflows:
 
 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.

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/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/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)
@@ -179,6 +200,9 @@ export function registerGraphicsTools(server, client) {
         },
     }, 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,8 +228,11 @@ export function registerGraphicsTools(server, client) {
                 title,
                 generationId,
                 catalogKey,
+                applySelection: Boolean(generationId && catalogKey),
             });
-            const opened = await openUrl(server, galleryUrl, "Browse personalized social-graphics styles in AppLaunchFlow.", { signal: extra.signal });
+            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: [
                     {
@@ -215,7 +242,9 @@ export function registerGraphicsTools(server, client) {
                                 ? "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"),
                     },
                     {
@@ -234,6 +263,7 @@ export function registerGraphicsTools(server, client) {
                         format,
                         templateIds: filteredTemplateIds,
                         browserOpened: opened,
+                        personalized: Boolean(generationId && catalogKey),
                     },
                     message: "Prepared social template gallery",
                 },

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/package.json

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