summer-engine 3.3.0 → 3.4.0

package/dist/core/hosted-mcp.d.ts

@@ -0,0 +1,115 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+/** The part of an MCP client the mount and the CLI use (a fake in tests). */
+export interface HostedClient {
+    listTools(params?: {
+        cursor?: string;
+    }): Promise<{
+        tools: Tool[];
+        nextCursor?: string;
+    }>;
+    callTool(params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    listPrompts(params?: {
+        cursor?: string;
+    }): Promise<{
+        prompts: Array<{
+            name: string;
+            title?: string;
+            description?: string;
+            arguments?: Array<{
+                name: string;
+                description?: string;
+                required?: boolean;
+            }>;
+        }>;
+        nextCursor?: string;
+    }>;
+    getPrompt(params: {
+        name: string;
+        arguments?: Record<string, string>;
+    }): Promise<Record<string, unknown>>;
+    listResources(params?: {
+        cursor?: string;
+    }): Promise<{
+        resources: Array<{
+            uri: string;
+            name: string;
+            title?: string;
+            description?: string;
+            mimeType?: string;
+        }>;
+        nextCursor?: string;
+    }>;
+    readResource(params: {
+        uri: string;
+    }): Promise<Record<string, unknown>>;
+    close?(): Promise<void>;
+}
+export interface HostedConnectDependencies {
+    /** The hosted Summer Engine MCP URL (the store sign-in's resource). */
+    url: () => string;
+    token: () => Promise<string>;
+    connect: (url: string, token: () => Promise<string>) => Promise<HostedClient>;
+}
+export declare function connectHostedMcp(url: string, token: () => Promise<string>): Promise<HostedClient>;
+export declare const defaultHostedConnectDependencies: HostedConnectDependencies;
+/** True when this machine has a store sign-in on disk (no network). */
+export declare function hasStoreSignIn(): Promise<boolean>;
+export declare function listAllHostedTools(client: HostedClient): Promise<Tool[]>;
+/** Connect with the store sign-in, run fn, close. Throws OAuthError when not signed in. */
+export declare function withHostedMcp<T>(fn: (client: HostedClient) => Promise<T>, deps?: HostedConnectDependencies): Promise<T>;
+/** The text of a tool result, parsed as JSON when it is JSON. */
+export declare function hostedResultPayload(result: Record<string, unknown>): {
+    isError: boolean;
+    text: string;
+    json: Record<string, unknown> | null;
+};
+export type StoreAccessResult = {
+    status: "not_signed_in";
+    message: string;
+} | {
+    status: "ok";
+    games: number | null;
+} | {
+    status: "refused";
+    code: string | null;
+    message: string;
+    requestId?: string;
+} | {
+    status: "unreachable";
+    message: string;
+};
+/**
+ * Ask the store for the creator's games through the hosted MCP
+ * (summer_store_list_games): proves the store accepts this machine's sign-in.
+ */
+export declare function checkStoreAccess(timeoutMs?: number, deps?: HostedConnectDependencies): Promise<StoreAccessResult>;
+/** The hosted tool a CLI name means: the exact name, or a slug ("store-list-games" -> summer_store_list_games). */
+export declare function matchHostedTool(name: string, tools: readonly Tool[]): Tool | null;
+export type HostedToolsListing = {
+    status: "listed";
+    tools: Tool[];
+} | {
+    status: "not_signed_in";
+} | {
+    status: "unavailable";
+    message: string;
+};
+/** The hosted store and publishing tools, when this machine has a store sign-in. */
+export declare function listHostedToolsForCli(deps?: HostedConnectDependencies, signedIn?: () => Promise<boolean>): Promise<HostedToolsListing>;
+export type HostedCallOutcome = {
+    status: "called";
+    tool: string;
+    result: Record<string, unknown>;
+} | {
+    status: "not_found";
+} | {
+    status: "not_signed_in";
+} | {
+    status: "unavailable";
+    message: string;
+};
+/** Call a hosted tool by its name or slug with the store sign-in (one connection). */
+export declare function callHostedToolForCli(name: string, args: Record<string, unknown>, deps?: HostedConnectDependencies, signedIn?: () => Promise<boolean>): Promise<HostedCallOutcome>;

package/dist/core/hosted-mcp.js

@@ -0,0 +1,164 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { getStoreAccessToken, OAuthError, readStoredOAuthToken, resolveMcpResourceUrl } from "./oauth.js";
+import { TOOLKIT_VERSION } from "./version.js";
+/**
+ * A client for the hosted Summer Engine MCP (mcp.summerengine.com), signed in
+ * with the store sign-in ("summer login --store"). The local MCP mounts its
+ * tools (src/mcp/hosted-mount.ts); `summer tool` and `summer doctor` call it
+ * directly through the helpers below, so all three faces reach the same
+ * store and publishing tools.
+ */
+const CALL_TIMEOUT_MS = 120_000;
+export async function connectHostedMcp(url, token) {
+    const transport = new StreamableHTTPClientTransport(new URL(url), {
+        // A fresh (refreshed when near expiry) token on every request.
+        fetch: async (input, init) => {
+            const headers = new Headers(init?.headers);
+            headers.set("authorization", `Bearer ${await token()}`);
+            return fetch(input, { ...init, headers });
+        },
+    });
+    const client = new Client({ name: "summer-engine-local", version: TOOLKIT_VERSION });
+    await client.connect(transport);
+    const timeout = { timeout: CALL_TIMEOUT_MS };
+    return {
+        listTools: (params) => client.listTools(params),
+        callTool: (params) => client.callTool(params, undefined, timeout),
+        listPrompts: (params) => client.listPrompts(params),
+        getPrompt: (params) => client.getPrompt(params),
+        listResources: (params) => client.listResources(params),
+        readResource: (params) => client.readResource(params),
+        close: () => client.close(),
+    };
+}
+export const defaultHostedConnectDependencies = {
+    url: () => resolveMcpResourceUrl(),
+    token: () => getStoreAccessToken(),
+    connect: connectHostedMcp,
+};
+/** True when this machine has a store sign-in on disk (no network). */
+export async function hasStoreSignIn() {
+    return (await readStoredOAuthToken()) !== null;
+}
+export async function listAllHostedTools(client) {
+    const out = [];
+    let cursor;
+    for (let pages = 0; pages < 20; pages++) {
+        const result = await client.listTools(cursor ? { cursor } : undefined);
+        out.push(...(result.tools ?? []));
+        if (!result.nextCursor)
+            break;
+        cursor = result.nextCursor;
+    }
+    return out;
+}
+/** Connect with the store sign-in, run fn, close. Throws OAuthError when not signed in. */
+export async function withHostedMcp(fn, deps = defaultHostedConnectDependencies) {
+    const url = deps.url();
+    await deps.token();
+    const client = await deps.connect(url, deps.token);
+    try {
+        return await fn(client);
+    }
+    finally {
+        await client.close?.().catch(() => undefined);
+    }
+}
+/** The text of a tool result, parsed as JSON when it is JSON. */
+export function hostedResultPayload(result) {
+    const content = Array.isArray(result.content) ? result.content : [];
+    const text = content
+        .filter((part) => part.type === "text" && typeof part.text === "string")
+        .map((part) => part.text)
+        .join("\n");
+    let json = null;
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            json = parsed;
+    }
+    catch {
+        json = null;
+    }
+    if (!json && result.structuredContent && typeof result.structuredContent === "object") {
+        json = result.structuredContent;
+    }
+    return { isError: result.isError === true, text, json };
+}
+/**
+ * Ask the store for the creator's games through the hosted MCP
+ * (summer_store_list_games): proves the store accepts this machine's sign-in.
+ */
+export async function checkStoreAccess(timeoutMs = 8_000, deps = defaultHostedConnectDependencies) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ status: "unreachable", message: `no answer within ${Math.round(timeoutMs / 1000)} s` }), timeoutMs);
+        timer.unref?.();
+    });
+    const attempt = (async () => {
+        try {
+            const result = await withHostedMcp((client) => client.callTool({ name: "summer_store_list_games", arguments: {} }), deps);
+            const payload = hostedResultPayload(result);
+            if (payload.isError || payload.json?.ok === false) {
+                const code = typeof payload.json?.code === "string" ? payload.json.code : typeof payload.json?.error === "string" ? payload.json.error : null;
+                const message = typeof payload.json?.message === "string" ? payload.json.message : payload.text.slice(0, 300) || "the store refused the call";
+                const requestId = typeof payload.json?.requestId === "string" ? payload.json.requestId : undefined;
+                return { status: "refused", code, message, ...(requestId ? { requestId } : {}) };
+            }
+            const games = Array.isArray(payload.json?.games) ? payload.json.games.length : null;
+            return { status: "ok", games };
+        }
+        catch (error) {
+            if (error instanceof OAuthError && error.code === "store_login_required") {
+                return { status: "not_signed_in", message: error.message.replace(` ${error.recovery}`, "") };
+            }
+            if (error instanceof OAuthError)
+                return { status: "refused", code: error.code, message: error.message };
+            return { status: "unreachable", message: error instanceof Error ? error.message : String(error) };
+        }
+    })();
+    try {
+        return await Promise.race([attempt, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The hosted tool a CLI name means: the exact name, or a slug ("store-list-games" -> summer_store_list_games). */
+export function matchHostedTool(name, tools) {
+    const needle = name.trim();
+    const asAlias = needle.startsWith("summer_") ? needle : `summer_${needle.replace(/-/g, "_")}`;
+    return tools.find((tool) => tool.name === needle) ?? tools.find((tool) => tool.name === asAlias) ?? null;
+}
+/** The hosted store and publishing tools, when this machine has a store sign-in. */
+export async function listHostedToolsForCli(deps = defaultHostedConnectDependencies, signedIn = hasStoreSignIn) {
+    if (!(await signedIn()))
+        return { status: "not_signed_in" };
+    try {
+        return { status: "listed", tools: await withHostedMcp(listAllHostedTools, deps) };
+    }
+    catch (error) {
+        if (error instanceof OAuthError && error.code === "store_login_required")
+            return { status: "not_signed_in" };
+        return { status: "unavailable", message: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Call a hosted tool by its name or slug with the store sign-in (one connection). */
+export async function callHostedToolForCli(name, args, deps = defaultHostedConnectDependencies, signedIn = hasStoreSignIn) {
+    if (!(await signedIn()))
+        return { status: "not_signed_in" };
+    try {
+        return await withHostedMcp(async (client) => {
+            const tool = matchHostedTool(name, await listAllHostedTools(client));
+            if (!tool)
+                return { status: "not_found" };
+            return { status: "called", tool: tool.name, result: await client.callTool({ name: tool.name, arguments: args }) };
+        }, deps);
+    }
+    catch (error) {
+        if (error instanceof OAuthError && error.code === "store_login_required")
+            return { status: "not_signed_in" };
+        return { status: "unavailable", message: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/core/launch-posture.d.ts

@@ -96,6 +96,9 @@ export type BackgroundLaunchSupport = {
     reason: "version_unknown";
     version: null;
 };
+/** Whether `version` is `minimum` or newer; null when either is missing or
+ *  not x.y.z (an unknown version is never "too old" and never "new enough"). */
+export declare function isVersionAtLeast(version: string | null | undefined, minimum: string): boolean | null;
 /**
  * Whether the installed engine honours the background flag. The `--help`
  * probe answer (true/false) is definitive when it ran; a probe that could not

package/dist/core/launch-posture.js

@@ -61,7 +61,7 @@
  * --help probe below runs against THAT binary (cache key: path + mtime + size).
  */
 import { spawn } from "node:child_process";
-import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { platform } from "node:os";
 import { getSummerDir } from "./auth.js";
@@ -100,6 +100,15 @@ function compareVersions(a, b) {
         return a.minor - b.minor;
     return a.patch - b.patch;
 }
+/** Whether `version` is `minimum` or newer; null when either is missing or
+ *  not x.y.z (an unknown version is never "too old" and never "new enough"). */
+export function isVersionAtLeast(version, minimum) {
+    const parsed = version ? parseVersion(version) : null;
+    const min = parseVersion(minimum);
+    if (!parsed || !min)
+        return null;
+    return compareVersions(parsed, min) >= 0;
+}
 /**
  * Whether the installed engine honours the background flag. The `--help`
  * probe answer (true/false) is definitive when it ran; a probe that could not
@@ -282,12 +291,16 @@ export function parseVelopackVersion(sqVersionText) {
     const match = sqVersionText.match(/<version>\s*([^<\s]+)\s*<\/version>/i);
     return match ? match[1].trim() : null;
 }
-/** Walk up from `.../Summer.app/Contents/MacOS/Summer` to the bundle. */
+/** Walk up from `.../Summer.app/Contents/MacOS/Summer` to the bundle. A
+ *  bundle unpacked without its `.app` folder (`<dir>/Contents/MacOS/Summer`)
+ *  reads as `<dir>`. */
 function macBundlePathFor(binary) {
     let current = dirname(binary);
     for (let depth = 0; depth < 4; depth++) {
         if (basename(current).endsWith(".app"))
             return current;
+        if (basename(current) === "Contents" && existsSync(join(current, "Info.plist")))
+            return dirname(current);
         const parent = dirname(current);
         if (parent === current)
             break;

package/dist/mcp/hosted-mount.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { type Tool } from "@modelcontextprotocol/sdk/types.js";
+import { type HostedClient, type HostedConnectDependencies } from "../core/hosted-mcp.js";
+export type { HostedClient };
 /**
  * One Summer Engine MCP. The cloud tools a creator's agent needs to publish
  * (projects, store page, build upload, submit for the owner's approval, the
@@ -11,65 +12,16 @@ import { type Tool } from "@modelcontextprotocol/sdk/types.js";
  * that server). A name the local MCP already has stays local (the engine and
  * generation tools keep their CLI-token path).
  *
- * Mounting is lazy: the server answers with the engine tools at once, and the
- * hosted tools appear when the mount finishes (tools/list_changed). Without a
- * store sign-in one tool, summer_store_tools, says how to sign in and mounts
- * on the next call.
+ * Mounting runs after connect. The first tools/list waits for a mount in
+ * progress (up to FIRST_LIST_WAIT_MS), so a host that lists tools once still
+ * sees the store tools; a slower mount adds them later (tools/list_changed).
+ * Without a store sign-in the mount fails at once, and one tool,
+ * summer_store_tools, says how to sign in and mounts on the next call.
  */
 export declare const STORE_TOOLS_STATUS = "summer_store_tools";
-/** The part of an MCP client the mount uses (a fake in tests). */
-export interface HostedClient {
-    listTools(params?: {
-        cursor?: string;
-    }): Promise<{
-        tools: Tool[];
-        nextCursor?: string;
-    }>;
-    callTool(params: {
-        name: string;
-        arguments?: Record<string, unknown>;
-    }): Promise<Record<string, unknown>>;
-    listPrompts(params?: {
-        cursor?: string;
-    }): Promise<{
-        prompts: Array<{
-            name: string;
-            title?: string;
-            description?: string;
-            arguments?: Array<{
-                name: string;
-                description?: string;
-                required?: boolean;
-            }>;
-        }>;
-        nextCursor?: string;
-    }>;
-    getPrompt(params: {
-        name: string;
-        arguments?: Record<string, string>;
-    }): Promise<Record<string, unknown>>;
-    listResources(params?: {
-        cursor?: string;
-    }): Promise<{
-        resources: Array<{
-            uri: string;
-            name: string;
-            title?: string;
-            description?: string;
-            mimeType?: string;
-        }>;
-        nextCursor?: string;
-    }>;
-    readResource(params: {
-        uri: string;
-    }): Promise<Record<string, unknown>>;
-}
-export interface HostedMountDependencies {
-    /** The hosted Summer Engine MCP URL (the store sign-in's resource). */
-    url: () => string;
-    token: () => Promise<string>;
-    connect: (url: string, token: () => Promise<string>) => Promise<HostedClient>;
-}
+/** How long the first tools/list waits for a mount in progress, so hosts that list once see the store tools. */
+export declare const FIRST_LIST_WAIT_MS = 5000;
+export type HostedMountDependencies = HostedConnectDependencies;
 export declare const defaultHostedMountDependencies: HostedMountDependencies;
 export interface HostedMountState {
     status: "idle" | "mounting" | "mounted" | "unavailable";
@@ -90,7 +42,9 @@ export interface HostedMountState {
  * reports each mounted tool's own JSON Schema rather than the passthrough one.
  * Returns mount(), which callers run after connect without awaiting it.
  */
-export declare function prepareHostedMount(server: McpServer, deps?: HostedMountDependencies): {
+export declare function prepareHostedMount(server: McpServer, deps?: HostedMountDependencies, options?: {
+    firstListWaitMs?: number;
+}): {
     mount: () => Promise<HostedMountState>;
     state: HostedMountState;
 };

package/dist/mcp/hosted-mount.js

@@ -1,10 +1,8 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
+import { connectHostedMcp } from "../core/hosted-mcp.js";
 import { getStoreAccessToken, OAuthError, resolveMcpResourceUrl } from "../core/oauth.js";
 import { appendMcpLogEvent } from "../core/mcp-log.js";
-import { TOOLKIT_VERSION } from "../core/version.js";
 /**
  * One Summer Engine MCP. The cloud tools a creator's agent needs to publish
  * (projects, store page, build upload, submit for the owner's approval, the
@@ -16,38 +14,20 @@ import { TOOLKIT_VERSION } from "../core/version.js";
  * that server). A name the local MCP already has stays local (the engine and
  * generation tools keep their CLI-token path).
  *
- * Mounting is lazy: the server answers with the engine tools at once, and the
- * hosted tools appear when the mount finishes (tools/list_changed). Without a
- * store sign-in one tool, summer_store_tools, says how to sign in and mounts
- * on the next call.
+ * Mounting runs after connect. The first tools/list waits for a mount in
+ * progress (up to FIRST_LIST_WAIT_MS), so a host that lists tools once still
+ * sees the store tools; a slower mount adds them later (tools/list_changed).
+ * Without a store sign-in the mount fails at once, and one tool,
+ * summer_store_tools, says how to sign in and mounts on the next call.
  */
 export const STORE_TOOLS_STATUS = "summer_store_tools";
-const CALL_TIMEOUT_MS = 120_000;
+/** How long the first tools/list waits for a mount in progress, so hosts that list once see the store tools. */
+export const FIRST_LIST_WAIT_MS = 5_000;
 const passthroughArgs = z.object({}).passthrough();
 export const defaultHostedMountDependencies = {
     url: () => resolveMcpResourceUrl(),
     token: () => getStoreAccessToken(),
-    connect: async (url, token) => {
-        const transport = new StreamableHTTPClientTransport(new URL(url), {
-            // A fresh (refreshed when near expiry) token on every request.
-            fetch: async (input, init) => {
-                const headers = new Headers(init?.headers);
-                headers.set("authorization", `Bearer ${await token()}`);
-                return fetch(input, { ...init, headers });
-            },
-        });
-        const client = new Client({ name: "summer-engine-local", version: TOOLKIT_VERSION });
-        await client.connect(transport);
-        const timeout = { timeout: CALL_TIMEOUT_MS };
-        return {
-            listTools: (params) => client.listTools(params),
-            callTool: (params) => client.callTool(params, undefined, timeout),
-            listPrompts: (params) => client.listPrompts(params),
-            getPrompt: (params) => client.getPrompt(params),
-            listResources: (params) => client.listResources(params),
-            readResource: (params) => client.readResource(params),
-        };
-    },
+    connect: connectHostedMcp,
 };
 async function listAll(page, key) {
     const out = [];
@@ -70,7 +50,9 @@ function errorText(error) {
  * reports each mounted tool's own JSON Schema rather than the passthrough one.
  * Returns mount(), which callers run after connect without awaiting it.
  */
-export function prepareHostedMount(server, deps = defaultHostedMountDependencies) {
+export function prepareHostedMount(server, deps = defaultHostedMountDependencies, options = {}) {
+    const firstListWaitMs = options.firstListWaitMs ?? FIRST_LIST_WAIT_MS;
+    let listed = false;
     const state = { status: "idle", tools: [], prompts: [], resources: [], collisions: [] };
     const schemas = new Map();
     const registries = server;
@@ -82,6 +64,10 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
     const listTools = handlers.get("tools/list");
     if (listTools) {
         server.server.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+            if (!listed) {
+                listed = true;
+                await waitForMount(firstListWaitMs);
+            }
             const result = await listTools(request, extra);
             return {
                 ...result,
@@ -94,6 +80,14 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
     }
     let statusTool = null;
     let running = null;
+    /** Wait for a mount in progress, at most ms; returns at once when none runs. */
+    async function waitForMount(ms) {
+        if (!running || ms <= 0)
+            return;
+        let timer;
+        await Promise.race([running, new Promise((done) => (timer = setTimeout(done, ms)))]);
+        clearTimeout(timer);
+    }
     const showStatusTool = () => {
         if (statusTool || STORE_TOOLS_STATUS in registries._registeredTools)
             return;

package/dist/mcp/server.js

@@ -356,8 +356,9 @@ export async function startMcpServer(options = {}) {
         appendMcpLogEvent("mcp:boot_drift_probe_failed", errorDetails(error));
     });
     // Hosted Summer Engine MCP tools (store, publishing, board, Grow): ready
-    // before connect, mounted after it without blocking the engine tools.
-    const hosted = prepareHostedMount(server);
+    // before connect, mounted after it. The first tools/list waits a few
+    // seconds for the mount (not under summer doctor, which times the list).
+    const hosted = prepareHostedMount(server, undefined, process.env.SUMMER_MCP_DOCTOR === "1" ? { firstListWaitMs: 0 } : {});
     const transport = new StdioServerTransport();
     await server.connect(transport);
     void hosted.mount();

package/dist/mcp/tools/creator-tools.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { CreatorOperationError, listCreatorReleases, publishCreator, } from "../../core/capabilities/creator.js";
+import { captureGameplay } from "../../core/capabilities/capture-gameplay.js";
 import { exportGame } from "../../core/capabilities/export-game.js";
 import { STORE_TARGETS } from "../../core/capabilities/export-presets.js";
 import { exportTemplates, TEMPLATE_PLATFORMS } from "../../core/capabilities/export-templates.js";
@@ -39,7 +40,7 @@ async function creatorResult(operation) {
     }
 }
 export function registerCreatorTools(server) {
-    server.tool("summer_export_game", "Export the game in the exact file the Summer Games store takes, with the installed Summer Engine headless (no window). format \"bundle\" (default): the summer.games .zip the Summer apps run on iPhone, Android, macOS and Windows; targets picks the platforms (a game without a server: ios and android only); upload it with summer_publish_build. format \"download\" with one target: web (an HTML5 .zip on Summer's WebGPU Forward+ web template, played on summer.games), macos (.app zip, macos-universal) or windows (.exe zip, windows-x64); these need the export template from summer_export_templates and are uploaded as store versions. Works without the editor running. Returns path, sha256, size, the manifest or store platform, and warnings.", {
+    server.tool("summer_export_game", "Export the game in the exact file the Summer Games store takes, with the installed Summer Engine headless (no window). format \"bundle\" (default): the summer.games .zip the Summer apps run on iPhone, Android, macOS and Windows; targets picks the platforms (a game without a server: ios and android only); upload it with summer_publish_build. format \"download\" with one target: web (an HTML5 .zip on Summer's WebGPU Forward+ web template, played on summer.games), macos (.app zip, macos-universal) or windows (.exe zip, windows-x64); these need the export template from summer_export_templates and are uploaded as store versions. Needs Summer Engine 0.7.0 or newer: an older engine is refused before anything is written (code engine_too_old). Works without the editor running. Returns path, sha256, size, the manifest or store platform, and warnings.", {
         project: z.string().optional().describe("Project folder with project.godot. Defaults to the MCP's bound project, then the working directory."),
         out: z.string().optional().describe("Output .zip path. Defaults to <project>/.summer/exports/."),
         targets: z
@@ -65,8 +66,17 @@ export function registerCreatorTools(server) {
             .optional()
             .describe("The installed Summer Engine version (Help > About, e.g. 0.7.1). Read automatically on macOS; needed on Windows and Linux."),
     }, async ({ action, platforms, includeDebug, summerVersion }) => creatorResult(() => exportTemplates({ action, platforms, includeDebug, summerVersion })));
-    server.tool("summer_publish_build", "Upload an export from summer_export_game to the creator's game on summer.games, through the same store upload Studio uses, straight from disk. A store bundle (format bundle): declare, upload parts, seal, wait until Summer makes the Build, name its client pack, and with publish=true approve it. A web build or native download (format download): upload it as the game's store version for its platform (web, macos-universal, windows-x64, linux-x64; read from the last export) and wait until Summer has checked it. First call with confirm=false and show the user the returned target; set confirm only after they approve. Needs \"summer login --store\". A retry with the same file and clientVersion continues the same upload. Nothing here makes a game live: the owner approves publishing (summer_store_submit).", {
-        gameId: z.string().optional().describe("The store game id (Studio store page URL). Omit to get the list of your games."),
+    server.tool("summer_capture_gameplay", "Capture real gameplay frames without a running editor: starts the game in Summer Engine's offscreen verify instance (a real renderer, a window parked offscreen with no focus, never on screen), lets it run waitSeconds, and saves PNG frames of what the game draws, HUD included. Use for store screenshots (1920x1080 landscape or 1080x1920 portrait). With an editor open, summer_screenshot target game also works. Returns each frame's path, width and height; look at them before using them.", {
+        project: z.string().optional().describe("Project folder with project.godot. Defaults to the MCP's bound project, then the working directory."),
+        scene: z.string().optional().describe("Scene to start (res://... or uid://...). Default: the project's main scene, which is often a title menu; pass the gameplay scene for gameplay frames."),
+        resolution: z.string().optional().describe("Window size WIDTHxHEIGHT (default 1920x1080; 1080x1920 for portrait)."),
+        frames: z.number().int().min(1).max(10).optional().describe("Frames to save (default 1)."),
+        waitSeconds: z.number().min(0).max(120).optional().describe("Seconds the game runs before the first frame (default 3)."),
+        intervalSeconds: z.number().min(0.1).max(60).optional().describe("Seconds between frames (default 1)."),
+        out: z.string().optional().describe("Output folder. Defaults to <project>/.summer/captures/<time>/ (ignored by git)."),
+    }, async (args) => creatorResult(() => captureGameplay(args)));
+    server.tool("summer_publish_build", "Upload an export from summer_export_game to the creator's game on summer.games, through the same store upload Studio uses, straight from disk. A store bundle (format bundle): declare, upload parts, seal, wait until Summer makes the Build, name its client pack, and with publish=true approve it. A web build or native download (format download): upload it as the game's store version for its platform (web, macos-universal, windows-x64, linux-x64; read from the last export) and wait until Summer has checked it. First call with confirm=false: it checks that the game exists for this account and warns when its store page does not list the export's platforms, then returns the target (game name and id, file, digest, size, version) to show the user; set confirm only after they approve. Needs \"summer login --store\". A retry with the same file and clientVersion continues the same upload. Nothing here makes a game live: the owner approves publishing (summer_store_submit).", {
+        gameId: z.string().optional().describe("The store game id (from summer_store_list_games, or the Studio store page URL). Without it the call fails with game_required and lists your store games, or says why the store did not list them."),
         file: z.string().optional().describe("Exported .zip. Defaults to the last summer_export_game result."),
         clientVersion: z.string().describe("Build version, vMAJOR.MINOR.PATCH (e.g. v1.0.0); a new upload needs a new version."),
         publish: z.boolean().default(false).describe("Bundles only: also approve the Build for players. A game that has not passed review keeps it as a preview; an agent needs the owner's approval."),

package/dist/mcp/tools/generate-tools.js

@@ -297,19 +297,29 @@ Style presets: "realistic" (default), "cartoon", "anime", "none"
 For an alpha PNG, set removeBackground: true. Prompt wording alone does not
 guarantee transparency; background removal runs server-side after generation.
 
-The 'options' object is passed directly to the AI provider for full control.
+Size: aspectRatio (1:1, 16:9, 9:16, 4:3, 3:4, ...) or width + height (the
+smallest size you need). For store art ask width 1920 height 1080 (key art)
+or width 1080 height 1920 (tall cover): the server picks a model that reaches
+that size, or refuses a named model that cannot, before anything is spent.
+Each result reports the real width and height and the model that ran.
+
+'options' carries extra model params (seed, negative_prompt, ...); the result
+lists any the server did not use in ignoredOptions.
 
 Returns the asset with fileUrl (hosted) and localPath (temp file on disk).
 Use the Read tool on localPath to show the image to the user for approval.
 
 Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
-Requires authentication: run 'npx -y summer-engine@latest login' first.`, imageGenerationArgsSchema.shape, async ({ prompt, model, style, referenceImageUrl, removeBackground, options }) => {
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, imageGenerationArgsSchema.shape, async ({ prompt, model, style, referenceImageUrl, removeBackground, aspectRatio, width, height, options }) => {
         const result = await mcpGenerate("/api/mcp/generate/image", {
             prompt,
             model,
             style,
             referenceImageUrl,
             removeBackground,
+            aspectRatio,
+            width,
+            height,
             options,
         });
         if (result.error) {

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "_generated": "GENERATED from integrations/gemini — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Agent tooling for Summer Engine: MCP bridge, context primer, and game-dev skills. Use with the npm CLI for skill files on disk.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
@@ -35,6 +35,7 @@
     "./library/skills/asset-strategy/",
     "./library/skills/audio-direction/",
     "./library/skills/auto-fire-targeting/",
+    "./library/skills/bounded-engine-runs/",
     "./library/skills/brainstorm-game/",
     "./library/skills/brainstorming/",
     "./library/skills/browse-templates/",
@@ -46,6 +47,7 @@
     "./library/skills/character-portrait/",
     "./library/skills/cinematic-cutscene/",
     "./library/skills/combat-basics/",
+    "./library/skills/compatibility-renderer-traps/",
     "./library/skills/concept-art/",
     "./library/skills/create-asset-sheet/",
     "./library/skills/debug/",