@appscreenshotstudio/mcp 0.4.2 → 0.4.4

package/README.md

@@ -148,6 +148,21 @@ Generate an AI background for a specific card. Uses project metadata (brand colo
 
 **Costs 6 credits.**
 
+### `generate-panoramic-background`
+
+Generate one wide image and slice it across multiple cards so they read as a continuous scene in the App Store gallery. Use after a panoramic chat edit ("pano the background across cards 1-3") to fulfill the pending panoramic, or pass an explicit `prompt` / `pexels_query`.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `project_id` | string | Yes | Project containing the cards |
+| `prompt` | string | No | AI scene description (Gemini). Costs 6 credits. |
+| `pexels_query` | string | No | Stock photo search query (Pexels). Free. |
+| `card_indices` | number[] | No | Cards sharing the panoramic (0-based, min 2). Default: first 3. |
+
+Omit both `prompt` and `pexels_query` to fulfill a panoramic already set up by `generate-screenshots` / `edit-screenshots`.
+
+**Costs 6 credits (AI prompt) or free (Pexels query).**
+
 ### `list-devices`
 
 Show all supported device specs. No API call needed.
@@ -169,6 +184,7 @@ Once installed, use `/appscreenshotstudio` in Claude Code or just ask "generate
 | ID | Name | Size | Required |
 |---|---|---|---|
 | `iphone-6.9` | iPhone 16 Pro Max | 1260x2736 | App Store |
+| `iphone-6.3` | iPhone 17 Pro | 1206x2622 | Optional |
 | `ipad-13` | iPad Pro 13" | 2064x2752 | App Store |
 | `android-phone` | Android Phone | 1080x2340 | Play Store |
 | `android-tablet-10` | Android Tablet 7" | 1200x1920 | Play Store |
@@ -178,12 +194,13 @@ Once installed, use `/appscreenshotstudio` in Claude Code or just ask "generate
 
 The AI generates professional screenshots using:
 
-- **78+ decorative shapes** across 13 categories: nature (leaf, flower, tree), weather (cloud, sun, snowflake), celebration (sparkle, trophy, crown, confetti), social (chat-bubble, music-note), tech (rocket, code-bracket), health (dumbbell, flame), food (coffee-cup, pizza), travel (airplane, compass), finance (dollar-sign, piggy-bank), education (graduation-cap, lightbulb), pets (paw-print, cat-face), emoji (smiley, fire-emoji), abstract (swirl, infinity, gem)
+- **94 shape types** (17 core + 77 decorative across 13 categories): nature (leaf, flower, tree), weather (cloud, sun, snowflake), celebration (sparkle, trophy, crown, confetti), social (chat-bubble, music-note), tech (rocket, code-bracket), health (dumbbell, flame), food (coffee-cup, pizza), travel (airplane, compass), finance (dollar-sign, piggy-bank), education (graduation-cap, lightbulb), pets (paw-print, cat-face), emoji (smiley, fire-emoji), abstract (swirl, infinity, gem)
 - **Rich text**: per-word color, bold, italic, underline, highlight pills (colored backgrounds behind words), gradient fills, text stroke outlines, emoji
-- **Laurel stats**: wing-left + wing-right shapes flanking stats like "4.9 Rating" or "1M+ Users"
-- **Floating UI snippets**: rounded-rect panels with text overlapping device edges
-- **11 device perspectives**: flat, left-15, left-30, right-15, right-30, isometric, top-down, flat-lay, side-profile, landscape-left, landscape-right
-- **7 layouts**: Text Top + Device Center (A), Text Top + Device Offset (B), Social Proof (C), Marketing Title (M1), Feature Callout (M2), CTA (M3), Testimonial (M4)
+- **Compound trust signals**: statRow, laurelStat, starRating, quote, pressBanner, featureGrid, beforeAfterSplit, stepList — auto-positioned per layout
+- **Frame color**: recolor the device frame — `natural` (default), `black`, `white`, `gold`. Requires Growth plan or higher.
+- **Panoramics**: slice one wide image across cards (chat tags the cards, then `generate-panoramic-background` creates and slices the image) or stretch a foreground element across adjacent cards (`apply_element_span`). Gallery gutters are accounted for.
+- **9 device perspectives**: flat, left-15, left-30, right-15, right-30, isometric, top-down, landscape-left, landscape-right
+- **14 layouts**: `text-top-device-bottom`, `text-top-device-tilted`, `device-hero`, `social-proof`, `review-clip`, `screen-hero`, `lifestyle-hero`, `photo-device-hero`, `feature-grid`, `before-after`, `stats-hero`, `metric-badge`, `annotated-feature`, `step-flow`. The AI varies `deviceScale`, `deviceSide`, `textPosition`, and `textAlign` per card so a set never looks like duplicates.
 
 ## Workflow
 

package/dist/index.js

@@ -31,6 +31,7 @@ const API_KEY = process.env.APPSCREENSHOTSTUDIO_API_KEY;
 // ⚠️ Keep in sync: lib/device-specs.ts, mcp-server/README.md, docs/api page, docs/mcp page
 const DEVICES = [
     { id: 'iphone-6.9', name: 'iPhone 16 Pro Max', width: 1260, height: 2736, category: 'iphone', required: true },
+    { id: 'iphone-6.3', name: 'iPhone 17 Pro', width: 1206, height: 2622, category: 'iphone', required: false },
     { id: 'ipad-13', name: 'iPad Pro 13"', width: 2064, height: 2752, category: 'ipad', required: true },
     { id: 'android-phone', name: 'Android Phone', width: 1080, height: 2340, category: 'android-phone', required: true },
     { id: 'android-tablet-10', name: 'Android Tablet 7"', width: 1200, height: 1920, category: 'android-tablet', required: true },
@@ -126,7 +127,7 @@ function buildDesignMessage(input) {
 // ─── MCP Server ─────────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'appscreenshotstudio',
-    version: '0.4.0',
+    version: '0.4.4',
 });
 // Tool 1: generate-screenshots
 server.registerTool('generate-screenshots', {
@@ -137,25 +138,30 @@ IMPORTANT: Before calling this tool, research the user's codebase to populate th
 
 The AI picks a narrative arc that fits the app's sell angle (trust-first for finance/health, visual-first for creative/lifestyle, problem-first for pain-relief apps, numbers-led for SaaS/analytics, community-first for social, feature-forward for multi-mode apps) and assigns a job to each card: HOOK → EDUCATE → PROVE → CONVERT.
 
-9 layout types available per card:
+14 layout types available per card:
 - text-top-device-bottom: headline top, flat device bottom (feature/educate)
 - text-top-device-tilted: headline left, tilted device right (or mirrored)
 - device-hero: headline + large centered device, product-forward
-- social-proof: stars + quote + laurel stat, device optional
-- feature-callout: headline + features list, no device
-- lifestyle-hero: full-bleed photo background + text overlay
+- social-proof: stars + quote + laurel stat, no device (testimonial-led)
+- review-clip: rating-statement headline + stars + quote + bottom-clipped device
+- screen-hero: top-clipped device + centered headline + optional trust stat
+- lifestyle-hero: full-bleed photo background + text overlay (no device)
+- photo-device-hero: full-bleed photo background + headline overlay + flat device
+- feature-grid: headline + 2×2 or 2×3 icon+label grid, no device
 - before-after: dark before-half + bright after-half (transformation apps)
-- text-bottom: headline anchored to lower third, cinematic
 - stats-hero: giant centered stat(s), no device, numbers-led
+- metric-badge: centered device + chunky "achievement card" floating over its screen
+- annotated-feature: tilted device + side callout chip linked by a connector line
+- step-flow: headline + 2-4 numbered step rows ("how it works"), no device
 
-Each card can carry auto-positioned compound fields: statRow, laurelStat, pressBanner, starRating, quote, featurePills, featureGrid, stepFlow, snippets, beforeAfterSplit.
+Each card can carry auto-positioned compound fields: statRow, laurelStat, pressBanner, starRating, quote, featureGrid, beforeAfterSplit, stepList.
 
-Panoramic backgrounds slice one wide AI-generated or Pexels image across multiple cards for cohesion. Panoramic element spans stretch a foreground image or device across adjacent cards.
+Panoramic backgrounds slice one wide AI-generated or Pexels image across multiple cards for cohesion. Panoramic element spans stretch a foreground image or device across adjacent cards. Note: if the design comes back with a panoramic background, the chat only tags the cards; call generate-panoramic-background afterwards to actually create and slice the wide image.
 
 Design features:
 - Rich text with per-word color, weight, italic, underline, highlight pills, gradient fills, stroke outlines, and emoji
-- Device perspective variants: flat, left-15/30, right-15/30, isometric, top-down, flat-lay, side-profile, landscape
-- 76+ decorative shapes across 13 categories (nature, weather, celebration, social, tech, health, food, travel, abstract, finance, education, pets, emoji)
+- Device perspective variants: flat, left-15/30, right-15/30, isometric, top-down, landscape
+- 77 decorative shapes across 13 categories (nature, weather, celebration, social, tech, health, food, travel, abstract, finance, education, pets, emoji), plus 17 core geometric shapes
 - Laurel stats: wing-left + wing-right shapes flanking a hero number
 
 App Store 60/40 rule enforced: minimum 60% of cards must show a device mockup, maximum 40% can be marketing-only.
@@ -268,23 +274,23 @@ What you can change:
 - Text: headlines, subtitles, badge text, font size, font family (Inter, Poppins, Montserrat, DM Sans, Space Grotesk, etc.)
 - Text styling: per-word color, bold, italic, underline, highlight pills (colored background behind words), gradient text, text stroke outlines
 - Colors: brand palette, gradient backgrounds, accent colors, text colors
-- Layouts (9 types): text-top-device-bottom, text-top-device-tilted, device-hero, social-proof, feature-callout, lifestyle-hero, before-after, text-bottom, stats-hero. The AI picks a narrative arc (HOOK → EDUCATE → PROVE → CONVERT) across the set.
-- Layout params: deviceScale (small/medium/large), deviceSide (left/right), textPosition (above/below), compoundPlacement (below-text/below-device)
-- Device mockups: perspective variants (flat, left-15, right-15, left-30, right-30, isometric, top-down, flat-lay, side-profile, landscape-left, landscape-right), 2D rotation, resize, reposition
+- Layouts (14 types): text-top-device-bottom, text-top-device-tilted, device-hero, social-proof, review-clip, screen-hero, lifestyle-hero, photo-device-hero, feature-grid, before-after, stats-hero, metric-badge, annotated-feature, step-flow. The AI picks a narrative arc (HOOK → EDUCATE → PROVE → CONVERT) across the set.
+- Layout params: deviceScale (small/medium/large), deviceSide (left/right), textPosition (above/below), textAlign (left/center)
+- Device mockups: perspective variants (flat, left-15, right-15, left-30, right-30, isometric, top-down, landscape-left, landscape-right), 2D rotation, resize, reposition
+- Frame color: recolor the device frame — "natural" (default), "black", "white", "gold". Examples: "make the iPhone gold", "black titanium finish", "white iPhone". Requires Growth plan or higher.
 - Switch devices: "make this for Apple Watch" / "duplicate for Android tablet" clones the project at the target device's canvas size
 - Add/remove cards: add a social proof card, remove card 3, add a marketing title card
-- Compound fields (auto-positioned): statRow, laurelStat, pressBanner, starRating, quote, featurePills, featureGrid, stepFlow, snippets, beforeAfterSplit
-- Panoramic backgrounds: one wide AI or Pexels image sliced across multiple cards ("pano the background across cards 1-3")
+- Compound fields (auto-positioned): statRow, laurelStat, pressBanner, starRating, quote, featureGrid, beforeAfterSplit
+- Panoramic backgrounds: one wide AI or Pexels image sliced across multiple cards ("pano the background across cards 1-3"). The edit only tags the cards; call generate-panoramic-background afterwards to create and slice the wide image.
 - Panoramic element spans: stretch a foreground image, device-mockup, or shape across adjacent cards ("pano the device across cards 1-2")
-- Floating elements: add/edit badges, star ratings, floating UI snippets
+- Floating elements: add/edit badges, star ratings
 - Shapes: glow orbs, waves, blobs, rounded rectangles, circles, custom SVG paths
-- Decorative shapes: 76+ library shapes — leaf, flower, cloud, sparkle, heart, rocket, trophy, crown, coffee-cup, airplane, dollar-sign, paw-print, wing-left/wing-right (for laurels), and many more
+- Decorative shapes: 77 library shapes — leaf, flower, cloud, sparkle, heart, rocket, trophy, crown, coffee-cup, airplane, dollar-sign, paw-print, wing-left/wing-right (for laurels), and many more
 - Backgrounds: solid, subtle-gradient, rich-gradient, photo (Pexels), or ai-generated; change gradient colors/angle; set a backgroundPrompt for AI-generated
 - Style: shadows, opacity, border radius, rotation, blur
 
 What isn't supported (the AI will flag these in unsupportedAsks):
 - Multiple devices side-by-side in a single card (e.g. iPhone + Watch in one scene) — each card renders one device. Use the duplicate-for-device workflow instead, or split across cards.
-- Frame color selection (white/silver/space-black) — pick a frame style in the canvas device panel.
 - Uploading a specific user-supplied screenshot into a mockup — use upload-screenshots tool first, then reference the uploaded project.
 
 Example edit messages:
@@ -295,6 +301,7 @@ Example edit messages:
 - "Pano the background photo across cards 1-3"
 - "Stretch the device on card 1 across into card 2"
 - "Make this project for Apple Watch"
+- "Recolor the iPhone frame to gold across all cards"
 - "Replace card 3 with a CTA card saying Download Free"
 - "Switch card 2 to device-hero layout with statRow showing our three key metrics"
 - "Add a before-after card showing the transformation"
@@ -303,8 +310,8 @@ Example edit messages:
     inputSchema: z.object({
         project_id: z.string().describe('Project ID from a previous generate-screenshots call'),
         message: z.string().describe('What to change — use natural language'),
-        card_indices: z.array(z.number()).optional()
-            .describe('Target specific cards by index (0-based). e.g. [0] for card 1, [2,3] for cards 3-4. Omit to apply changes to all cards.'),
+        card_indices: z.array(z.number().int().min(0)).max(10).optional()
+            .describe('Target specific cards by index (0-based). e.g. [0] for card 1, [2,3] for cards 3-4. Max 10 indices. Omit to apply changes to all cards.'),
         codebase_context: z.object({
             readme_summary: z.string().optional(),
             key_screens: z.array(z.string()).max(15).optional(),
@@ -423,8 +430,8 @@ Returns the canvas state with:
 - cards[]: each card has an id, elements array, and optional background settings
 - Each element has: type (text, device-mockup, shape, badge, image, star-rating), position (x, y), size (width, height), zIndex, and type-specific properties
 - Text elements: fontFamily, fontSize, fontWeight, color, segments (for multi-color text with per-word color, bold, italic, underline, highlightColor)
-- Device mockups: perspectiveVariant (flat, left-15, right-15, left-30, right-30, isometric, top-down, flat-lay, side-profile, landscape-left, landscape-right), screenshotImage (null if no upload)
-- Shapes: 78+ shape types across 13 categories — core shapes (circle, rectangle, rounded-rect, blob, wave, triangle, diamond, hexagon, ring, star, wing-left, wing-right, etc.) plus decorative library shapes (leaf, flower, cloud, sparkle, heart, rocket, trophy, crown, coffee-cup, airplane, dollar-sign, paw-print, and many more)
+- Device mockups: perspectiveVariant (flat, left-15, right-15, left-30, right-30, isometric, top-down, landscape-left, landscape-right), screenshotImage (null if no upload)
+- Shapes: 94 shape types (17 core + 77 decorative across 13 categories) — core shapes (circle, rectangle, rounded-rect, blob, wave, triangle, diamond, hexagon, ring, star, wing-left, wing-right, etc.) plus decorative library shapes (leaf, flower, cloud, sparkle, heart, rocket, trophy, crown, coffee-cup, airplane, dollar-sign, paw-print, and many more)
 - projectMeta: globalVisualTheme, brandColors, mood, appCategory`,
     inputSchema: z.object({
         project_id: z.string().describe('Project ID to inspect'),
@@ -505,7 +512,55 @@ The generated image is cropped to exact device dimensions and set as the card's
             }],
     };
 });
-// Tool 7: prepare-screenshot-brief
+// Tool 7: generate-panoramic-background
+server.registerTool('generate-panoramic-background', {
+    title: 'Generate Panoramic Background',
+    description: `Generate one wide background image and slice it across multiple cards so they read as a continuous scene when the App Store gallery scrolls. The store gallery gap is accounted for, so slices line up after Apple's gutter.
+
+Two image sources:
+- prompt: AI-generated via Gemini. Costs 6 credits.
+- pexels_query: stock landscape photo from Pexels. Free.
+
+If you omit both, the tool fulfills a panoramic the chat already set up: when generate-screenshots or edit-screenshots returns a design with a panoramic background (e.g. after "pano the background across cards 1-3"), the cards are tagged but the wide image isn't created yet. Calling this tool with just the project_id picks up that pending panoramic and generates it.
+
+Good prompts describe a continuous scene, not objects or text:
+- "Misty mountain range at dawn, soft pink-to-blue gradient sky"
+- "Calm ocean horizon at golden hour with gentle waves"
+- "Abstract flowing emerald and teal silk waves"`,
+    inputSchema: z.object({
+        project_id: z.string().describe('Project ID'),
+        prompt: z.string().optional()
+            .describe('AI scene description (Gemini, 6 credits). Describe one continuous landscape scene: no text, devices, or UI.'),
+        pexels_query: z.string().optional()
+            .describe('Stock photo search query (Pexels, free). e.g. "mountain sunrise", "ocean horizon". Provide either this or prompt, not both.'),
+        card_indices: z.array(z.number().int().min(0)).max(10).optional()
+            .describe('Which cards share the panoramic (0-based, min 2). Default: first 3 cards (the ones visible in the App Store gallery without scrolling).'),
+    }),
+}, async ({ project_id, prompt, pexels_query, card_indices }) => {
+    const res = await apiCall('POST', `/api/v1/projects/${project_id}/generate-panoramic-background`, {
+        ...(prompt ? { prompt } : {}),
+        ...(pexels_query ? { pexels_query } : {}),
+        ...(card_indices ? { card_indices } : {}),
+    });
+    if (!res.ok) {
+        return {
+            content: [{ type: 'text', text: `Panoramic background generation failed: ${JSON.stringify(res.data)}` }],
+        };
+    }
+    const data = res.data.data;
+    const creditsRemaining = res.data.credits_remaining;
+    return {
+        content: [{
+                type: 'text',
+                text: [
+                    `Panoramic background generated and sliced across cards ${data.card_indices.map(i => i + 1).join(', ')}.`,
+                    `Credits remaining: ${creditsRemaining}`,
+                    `Project URL: ${API_BASE}/builder/${project_id}`,
+                ].join('\n'),
+            }],
+    };
+});
+// Tool 8: prepare-screenshot-brief
 server.registerTool('prepare-screenshot-brief', {
     title: 'Prepare Screenshot Brief',
     description: `Get a research checklist and strategy guide to prepare for screenshot generation. Call this BEFORE generate-screenshots to know what to look for in the codebase. Free — no API call or credits needed.
@@ -745,7 +800,7 @@ This tool helps you gather the right information so generate-screenshots produce
             }],
     };
 });
-// Tool 8: upload-screenshots
+// Tool 9: upload-screenshots
 server.registerTool('upload-screenshots', {
     title: 'Upload App Screenshots',
     description: `Upload local app screenshots (from Simulator, emulator, or screen captures) into the device mockups of an existing project. This lets you add real app UI into the device frames without leaving the terminal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appscreenshotstudio/mcp",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "MCP server for generating App Store screenshots via AppScreenshotStudio",
   "type": "module",
   "license": "MIT",

package/skills/appscreenshotstudio/SKILL.md

@@ -64,7 +64,7 @@ Call the `generate-screenshots` MCP tool with:
 - `features`: top 3-5 features as array
 - `brand_colors`: `{ primary, secondary?, accent? }` from theme files
 - `mood`: user's chosen mood
-- `device_id`: `"iphone-6.9"` (default), `"ipad-13"`, `"android-phone"`, `"android-tablet-10"`
+- `device_id`: `"iphone-6.9"` (default), `"ipad-13"`, `"android-phone"`, `"android-tablet-10"`, `"apple-watch-ultra"`
 - `count`: number of cards (3-10)
 - `story_flow`: `"auto"` (default), `"hero-intro"`, `"problem-solution"`, `"benefit-first"`, etc.
 - `codebase_context`: the full context object from Step 1