summer-engine 3.3.0 → 3.4.0

package/dist/core/capabilities/export-game.js

@@ -6,7 +6,8 @@ import { engineSelectionFromEnv } from "../engine.js";
 import { findEngineBinary } from "../engine-install.js";
 import { readStoreJson, writeStoreJson } from "../store.js";
 import { writeZip } from "../util/zip-write.js";
-import { runEngine } from "./engine-run.js";
+import { engineErrorLines, runEngine } from "./engine-run.js";
+import { assertExportEngine, installedEngineVersion } from "./export-engine-version.js";
 import { BUNDLE_TARGETS, DOWNLOAD_TARGETS, SUMMER_GAMES_PRESET, bundlePresetSpec, ensurePreset, normalizeTargets, variantString, } from "./export-presets.js";
 import { engineTemplateInfo, findInstalledTemplate, templateFileFor } from "./export-templates.js";
 import { BuildToolError, hashFile, readSummerBundle } from "./summer-bundle.js";
@@ -15,7 +16,7 @@ export { runEngine, SUMMER_GAMES_PRESET };
  * summer_export_game: run the installed Summer Engine headless and return the
  * file the Summer Games store takes for the chosen targets.
  *
- *   <engine> --headless --path <project> --export-release "<preset>" <out>
+ *   <engine> --headless --summer-no-api --path <project> --export-release "<preset>" <out>
  *
  * format "bundle" (default): the summer.bundle.v1 .zip for build-publications
  * (summer_publish_build). Summer runs its client.pck on its own templates in
@@ -51,6 +52,7 @@ const TARGET_ENGINE_NOTE = {
 };
 const defaultDependencies = {
     findBinary: () => findEngineBinary(platform()),
+    engineVersion: installedEngineVersion,
     run: runEngine,
     now: () => new Date(),
 };
@@ -81,6 +83,69 @@ async function defaultExportDir(project) {
 function outputTail(output) {
     return output.trim().split("\n").slice(-40).join("\n");
 }
+/** size and mtime of every file at the top of the project folder (project.godot, export_presets.cfg, ...). */
+async function snapshotProjectFiles(project) {
+    const files = new Map();
+    for (const entry of await readdir(project, { withFileTypes: true })) {
+        if (!entry.isFile())
+            continue;
+        const info = await stat(join(project, entry.name)).catch(() => null);
+        if (info)
+            files.set(entry.name, `${info.size}:${info.mtimeMs}`);
+    }
+    return files;
+}
+async function projectChangesSince(project, before, output) {
+    const after = await snapshotProjectFiles(project);
+    const changes = [];
+    for (const [file, value] of after) {
+        if (output && resolve(project, file) === resolve(output))
+            continue;
+        if (!before.has(file))
+            changes.push({ file, change: "created" });
+        else if (before.get(file) !== value)
+            changes.push({ file, change: "modified" });
+    }
+    for (const file of before.keys())
+        if (!after.has(file))
+            changes.push({ file, change: "deleted" });
+    return changes.sort((a, b) => a.file.localeCompare(b.file));
+}
+function projectChangeWarnings(changes) {
+    return changes.some((entry) => entry.file === "project.godot" && entry.change === "modified")
+        ? ["Summer Engine rewrote project.godot while it exported (an engine update cleans up old settings; the previous file is project.godot.bak). Review the change and commit or revert it."]
+        : [];
+}
+/** Re-throw an export failure with the project files it already changed. */
+async function withProjectChanges(project, before, work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (!(error instanceof BuildToolError))
+            throw error;
+        const changes = await projectChangesSince(project, before).catch(() => []);
+        if (!changes.length)
+            throw error;
+        throw new BuildToolError(error.code, error.message.replace(` ${error.recovery}`, ""), error.recovery, error.status, { ...error.detail, projectChanges: changes });
+    }
+}
+/** Plain recovery for what the engine printed; the generic preset hint only when a preset is what it names. */
+function exportFailureRecovery(errors, preset) {
+    const text = errors.join("\n");
+    if (/export preset/i.test(text) && /(invalid|not found|no such|unknown)/i.test(text)) {
+        return `Recovery: this engine has no "${preset}" export preset, which means it predates summer.games exports: update Summer Engine to 0.7.0+ (run "summer install --yes"), then export again.`;
+    }
+    if (/source graph|client pack|authority|domain/i.test(text)) {
+        return ("Recovery: this is a hosted game whose source graph puts a resource the client loads in a server-only (authority) domain. " +
+            "Open the source graph summer.build.json names (source_graph, usually source-domains.json) and narrow the authority root to the server-only files " +
+            "(for example the authority scene and its script), so the scenes and resources the client starts (such as the network composition .tres) sit under a shared or client root. " +
+            "The multiplayer-project skill explains the domains. Then export again.");
+    }
+    return errors.length
+        ? "Recovery: fix what the engine names above and export again."
+        : "Recovery: the engine printed no ERROR line; read output, fix what it names, and export again.";
+}
 /** One value from project.godot ([section] key=value), unquoted. */
 export function projectSetting(project, section, key) {
     let current = "";
@@ -189,7 +254,8 @@ async function listFiles(root) {
     return files.sort();
 }
 async function runExport(deps, binary, project, preset, out, debug, timeoutMs, notes) {
-    const args = ["--headless", "--path", project, debug ? "--export-debug" : "--export-release", preset, out];
+    // --summer-no-api: an export needs no local HTTP API; nothing binds 127.0.0.1:6550 or writes discovery files.
+    const args = ["--headless", "--summer-no-api", "--path", project, debug ? "--export-debug" : "--export-release", preset, out];
     let run;
     try {
         run = await deps.run(binary, args, timeoutMs);
@@ -201,10 +267,9 @@ async function runExport(deps, binary, project, preset, out, debug, timeoutMs, n
         throw new BuildToolError("export_timeout", `The export did not finish within ${Math.round(timeoutMs / 1000)} seconds and was stopped.`, "Recovery: a first export imports every asset; retry with a larger timeoutSeconds.", undefined, { output: outputTail(run.output) });
     }
     if (run.code !== 0 || !existsSync(out)) {
-        throw new BuildToolError("export_failed", `Summer Engine did not export the game (exit ${run.code ?? run.signal}).`, [
-            `Recovery: read the engine output, fix what it names, and export again. A missing "${preset}" preset means this engine predates summer.games exports: update Summer Engine.`,
-            ...notes,
-        ].join(" "), undefined, { output: outputTail(run.output) });
+        const errors = run.errors?.length ? run.errors : engineErrorLines(run.output);
+        const named = errors.slice(0, 3).map((line) => line.replace(/^(SCRIPT )?ERROR:\s*/, ""));
+        throw new BuildToolError("export_failed", `Summer Engine did not export the game (exit ${run.code ?? run.signal})${named.length ? `: ${named.join(" | ")}` : "."}`, [exportFailureRecovery(errors, preset), ...notes].join(" "), undefined, { errors, output: outputTail(run.output) });
     }
 }
 export async function exportGame(input, overrides = {}) {
@@ -227,15 +292,19 @@ export async function exportGame(input, overrides = {}) {
     if (!binary) {
         throw new BuildToolError("engine_not_installed", "Summer Engine is not installed on this machine.", 'Recovery: run "summer install", or set SUMMER_BIN to the engine executable, then export again.');
     }
+    // Before any preset is written: an old engine cannot read them.
+    assertExportEngine(binary, deps.engineVersion(binary));
     if (format === "download") {
         return exportDownload(deps, binary, project, targets[0], out, debug, timeoutMs, started);
     }
     out ??= join(await defaultExportDir(project), `${basename(project)}-${stamp(started)}.zip`);
     const before = existsSync(out) ? statSync(out).mtimeMs : null;
+    const projectBefore = await snapshotProjectFiles(project);
     const ensured = targets ? await ensurePreset(project, bundlePresetSpec(targets)) : undefined;
     const preset = ensured?.name ?? (input.preset?.trim() || SUMMER_GAMES_PRESET);
     const notes = (targets ?? []).flatMap((target) => TARGET_ENGINE_NOTE[target] ?? []);
-    await runExport(deps, binary, project, preset, out, debug, timeoutMs, notes);
+    await withProjectChanges(project, projectBefore, () => runExport(deps, binary, project, preset, out, debug, timeoutMs, notes));
+    const projectChanges = await projectChangesSince(project, projectBefore, out);
     if (before !== null && statSync(out).mtimeMs === before) {
         throw new BuildToolError("export_failed", "Summer Engine exited without writing a new bundle.", "Recovery: read the engine output and export again.");
     }
@@ -244,7 +313,7 @@ export async function exportGame(input, overrides = {}) {
     if (missing.length) {
         throw new BuildToolError("export_target_unsupported", `This Summer Engine exported the bundle without ${missing.join(", ")}: its summer.games preset has no such platform.`, ["Recovery: update Summer Engine and export again, or export without those targets.", ...missing.flatMap((target) => TARGET_ENGINE_NOTE[target] ?? [])].join(" "), undefined, { exportedPlatforms: bundle.targetPlatforms, path: out });
     }
-    const warnings = [];
+    const warnings = projectChangeWarnings(projectChanges);
     const desktopOnly = bundle.hosted ? [] : bundle.targetPlatforms.filter((target) => !STANDALONE_TARGETS.includes(target));
     if (desktopOnly.length) {
         warnings.push(`This game has no server, and the store runs games without a server on iPhone and Android only: summer_publish_build will refuse ${desktopOnly.join(", ")}. ` +
@@ -267,6 +336,7 @@ export async function exportGame(input, overrides = {}) {
         engine: binary,
         durationMs: deps.now().getTime() - started.getTime(),
         bundle: { ...summary, fileCount: files.length },
+        ...(projectChanges.length ? { projectChanges } : {}),
         ...(warnings.length ? { warnings } : {}),
         next: "Upload it to the game's store listing with summer_publish_build (gameId, clientVersion).",
     };
@@ -296,6 +366,7 @@ async function exportDownload(deps, binary, project, target, requestedOut, debug
             throw error;
     }
     const spec = downloadPresetSpec(target, slug);
+    const projectBefore = await snapshotProjectFiles(project);
     const ensured = await ensurePreset(project, spec);
     const exportsDir = await defaultExportDir(project);
     const work = join(exportsDir, `${slug}-${target}-${stamp(started)}`);
@@ -304,37 +375,41 @@ async function exportDownload(deps, binary, project, target, requestedOut, debug
     const out = requestedOut ?? join(exportsDir, `${slug}-${storePlatform}-${stamp(started)}.zip`);
     const warnings = [];
     let fileCount = 1;
-    try {
-        if (target === "macos") {
-            // The macOS exporter writes the .app inside a .zip itself.
-            const engineOut = join(work, `${slug}.zip`);
-            await runExport(deps, binary, project, spec.name, engineOut, debug, timeoutMs, []);
-            await rename(engineOut, out);
-            warnings.push("macOS shows players an unidentified-developer prompt for an ad hoc signed app; the store accepts it as is.");
-        }
-        else {
-            const engineOut = join(work, target === "web" ? "index.html" : `${slug}.exe`);
-            await runExport(deps, binary, project, spec.name, engineOut, debug, timeoutMs, []);
-            const files = await listFiles(work);
-            const entries = files.map((file) => ({ name: relative(work, file).split(sep).join("/"), source: file }));
-            if (target === "web") {
-                const sizes = await Promise.all(files.map(async (file) => (await stat(file)).size));
-                const total = sizes.reduce((sum, size) => sum + size, 0);
-                const tooBig = entries.find((_entry, index) => sizes[index] > WEB_LIMITS.fileBytes);
-                if (entries.length > WEB_LIMITS.files || total > WEB_LIMITS.zipBytes || tooBig) {
-                    throw new BuildToolError("web_build_too_large", `The web build has ${entries.length} files and ${Math.round(total / 1048576)} MiB${tooBig ? `; ${tooBig.name} is over 200 MiB` : ""}. The store takes at most ${WEB_LIMITS.files} files, 500 MiB, 200 MiB per file.`, "Recovery: exclude unused assets from the export (Project > Export > Resources) or compress textures, then export again.");
-                }
+    await withProjectChanges(project, projectBefore, async () => {
+        try {
+            if (target === "macos") {
+                // The macOS exporter writes the .app inside a .zip itself.
+                const engineOut = join(work, `${slug}.zip`);
+                await runExport(deps, binary, project, spec.name, engineOut, debug, timeoutMs, []);
+                await rename(engineOut, out);
+                warnings.push("macOS shows players an unidentified-developer prompt for an ad hoc signed app; the store accepts it as is.");
             }
             else {
-                warnings.push("The .exe is not code signed; Windows SmartScreen may warn players. The store accepts it as is.");
+                const engineOut = join(work, target === "web" ? "index.html" : `${slug}.exe`);
+                await runExport(deps, binary, project, spec.name, engineOut, debug, timeoutMs, []);
+                const files = await listFiles(work);
+                const entries = files.map((file) => ({ name: relative(work, file).split(sep).join("/"), source: file }));
+                if (target === "web") {
+                    const sizes = await Promise.all(files.map(async (file) => (await stat(file)).size));
+                    const total = sizes.reduce((sum, size) => sum + size, 0);
+                    const tooBig = entries.find((_entry, index) => sizes[index] > WEB_LIMITS.fileBytes);
+                    if (entries.length > WEB_LIMITS.files || total > WEB_LIMITS.zipBytes || tooBig) {
+                        throw new BuildToolError("web_build_too_large", `The web build has ${entries.length} files and ${Math.round(total / 1048576)} MiB${tooBig ? `; ${tooBig.name} is over 200 MiB` : ""}. The store takes at most ${WEB_LIMITS.files} files, 500 MiB, 200 MiB per file.`, "Recovery: exclude unused assets from the export (Project > Export > Resources) or compress textures, then export again.");
+                    }
+                }
+                else {
+                    warnings.push("The .exe is not code signed; Windows SmartScreen may warn players. The store accepts it as is.");
+                }
+                await writeZip(out, entries);
+                fileCount = entries.length;
             }
-            await writeZip(out, entries);
-            fileCount = entries.length;
         }
-    }
-    finally {
-        await rm(work, { recursive: true, force: true });
-    }
+        finally {
+            await rm(work, { recursive: true, force: true });
+        }
+    });
+    const projectChanges = await projectChangesSince(project, projectBefore, out);
+    warnings.unshift(...projectChangeWarnings(projectChanges));
     const icon = projectSetting(project, "application", "config/icon");
     if (!icon)
         warnings.push("The project has no icon (Project Settings > Application > Config > Icon); the export uses the Summer default.");
@@ -358,6 +433,7 @@ async function exportDownload(deps, binary, project, target, requestedOut, debug
         fileCount,
         icon,
         signing: target === "macos" ? "ad hoc (built-in), not notarized" : "none",
+        ...(projectChanges.length ? { projectChanges } : {}),
         ...(warnings.length ? { warnings } : {}),
         next: `Upload it as the game's ${storePlatform} store version with summer_publish_build (gameId, clientVersion); it reads the platform from this export.`,
     };

package/dist/core/capabilities/image-generation.d.ts

@@ -6,19 +6,28 @@ export declare const imageGenerationArgsSchema: z.ZodObject<{
     style: z.ZodDefault<z.ZodString>;
     referenceImageUrl: z.ZodOptional<z.ZodString>;
     removeBackground: z.ZodOptional<z.ZodBoolean>;
+    aspectRatio: z.ZodOptional<z.ZodEnum<["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "5:4", "4:5", "21:9"]>>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
     options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, "strip", z.ZodTypeAny, {
     prompt: string;
     model: string;
     style: string;
+    width?: number | undefined;
+    height?: number | undefined;
     options?: Record<string, any> | undefined;
     referenceImageUrl?: string | undefined;
     removeBackground?: boolean | undefined;
+    aspectRatio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | "5:4" | "4:5" | "21:9" | undefined;
 }, {
     prompt: string;
+    width?: number | undefined;
+    height?: number | undefined;
     options?: Record<string, any> | undefined;
     model?: string | undefined;
     style?: string | undefined;
     referenceImageUrl?: string | undefined;
     removeBackground?: boolean | undefined;
+    aspectRatio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | "5:4" | "4:5" | "21:9" | undefined;
 }>;

package/dist/core/capabilities/image-generation.js

@@ -15,8 +15,26 @@ export const imageGenerationArgsSchema = z.object({
         .optional()
         .describe("Source image URL for img2img / edit mode. The prompt describes how to transform this image."),
     removeBackground: z.boolean().optional().describe("Remove the background server-side and return an alpha PNG for sprites, icons, or isolated objects."),
+    aspectRatio: z
+        .enum(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "5:4", "4:5", "21:9"])
+        .optional()
+        .describe("Aspect ratio of the output (default 1:1). The result reports the real width and height."),
+    width: z
+        .number()
+        .int()
+        .min(64)
+        .max(4096)
+        .optional()
+        .describe("Smallest output width in pixels; pass with height. 1920 with height 1080 for store key art, 1080 with 1920 for a tall cover."),
+    height: z
+        .number()
+        .int()
+        .min(64)
+        .max(4096)
+        .optional()
+        .describe("Smallest output height in pixels; pass with width."),
     options: z
         .record(z.any())
         .optional()
-        .describe("Provider-specific params (guidance_scale, seed, image_size, negative_prompt, etc.)"),
+        .describe("Extra model params (seed, negative_prompt, ...). The result lists any it did not use in ignoredOptions."),
 });

package/dist/core/capabilities/publish-build.d.ts

@@ -32,7 +32,7 @@ export interface Store {
         key?: string;
     }): Promise<T>;
 }
-export declare function storeError(status: number, code: string, message: string | undefined): BuildToolError;
+export declare function storeError(status: number, code: string, message: string | undefined, requestId?: string): BuildToolError;
 export declare function createStore(baseUrl: string, token: string, deps: PublishBuildDependencies): Store;
 /** Whole-file and per-part SHA-256 ("sha256:<hex>") in one pass. */
 export declare function hashParts(path: string, partSize: number): Promise<{
@@ -57,6 +57,19 @@ export declare function uploadParts(sign: (partNumbers: number[]) => Promise<Gra
     partCount: number;
 }, deps: PublishBuildDependencies, parts?: number[]): Promise<void>;
 export declare function normalizeClientVersion(value?: string): string;
+/**
+ * Before the person confirms, prove the target is real: the game exists for
+ * this account, and its store page lists the platforms the export targets.
+ */
+export declare function checkStoreGame(gameId: string, exportTargets: string[], deps: PublishBuildDependencies): Promise<{
+    game: {
+        gameId: string;
+        name: string | null;
+        status: string | null;
+        targets: string[];
+    };
+    warnings: string[];
+}>;
 export type PublishBuildResult = Record<string, unknown> & {
     ok: true;
     status: string;

package/dist/core/capabilities/publish-build.js

@@ -61,9 +61,11 @@ export const defaultDependencies = {
     now: Date.now,
     token: () => getStoreAccessToken(),
 };
-export function storeError(status, code, message) {
+export function storeError(status, code, message, requestId) {
     if (status === 401) {
-        return new BuildToolError("store_auth_refused", "The Summer store refused this sign-in.", 'Recovery: run "summer login --store --force" and retry. If it is refused again, the store does not accept agent sign-ins yet: upload the .zip in Studio (Store > your game > Exports) until it does.', status);
+        // The token was sent and refused: signing in again gives the same token
+        // shape and the same answer, so it is not the first thing to try.
+        return new BuildToolError("store_auth_refused", `The Summer store did not accept this sign-in${message ? `: ${message.replace(/\.$/, "")}` : ""}.`, 'Recovery: run "summer doctor" (Store line) to see the store\'s answer. Signing in again does not change a refusal of a valid sign-in. Until the store accepts agent sign-in for this account, upload the .zip in Studio (Store > your game > Exports).', status, requestId ? { requestId } : undefined);
     }
     if (status === 403 && code === "owner_approval_required") {
         return new BuildToolError("owner_approval_required", message || "Only the game's owner can do this.", "Recovery: nothing went live. Submit with summer_store_submit and give the owner the approval link it returns; a live game's new download is finished by the owner in Studio.", status);
@@ -104,7 +106,8 @@ export function createStore(baseUrl, token, deps) {
             const body = (json && typeof json === "object" ? json : {});
             if (!response.ok) {
                 const error = body.error && typeof body.error === "object" ? body.error : {};
-                throw storeError(response.status, typeof error.code === "string" ? error.code : `http_${response.status}`, typeof error.message === "string" ? error.message : undefined);
+                const requestId = [error.requestId, body.requestId, response.headers.get("x-request-id")].find((value) => typeof value === "string" && value);
+                throw storeError(response.status, typeof error.code === "string" ? error.code : `http_${response.status}`, typeof error.message === "string" ? error.message : undefined, requestId);
             }
             return body;
         },
@@ -260,18 +263,68 @@ function targetPlatforms(bundle) {
     // The Build declares exactly what the bundle declares (declaration_mismatch otherwise).
     return bundle.targetPlatforms;
 }
-/** gameId is required: the error carries the person's games when the store answers. */
-async function listGamesOrThrow(deps) {
-    let games;
+/** The signed-in person's store games, or why the store did not list them. */
+async function listGames(deps) {
     try {
-        const store = createStore(await resolveGatewayUrl(), await deps.token(), deps);
+        const store = createStore(await resolveGatewayUrl(), await storeToken(deps), deps);
         const page = await store.call("GET", "games");
-        games = (page.items ?? []).map((game) => ({ id: game.id, name: game.name, slug: game.slug, status: game.status }));
+        return { games: (page.items ?? []).map((game) => ({ id: game.id, name: game.name, slug: game.slug, status: game.status, targets: game.supportedPlatforms ?? [] })) };
     }
-    catch {
-        games = undefined;
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** gameId is required: the error carries the person's games, or why the store did not list them. */
+async function listGamesOrThrow(deps) {
+    const listed = await listGames(deps);
+    if ("games" in listed) {
+        throw new BuildToolError("game_required", listed.games.length
+            ? "gameId is required: pick one of your store games below (the export is uploaded to one existing game)."
+            : "gameId is required, and this account has no store game yet.", listed.games.length
+            ? "Recovery: call again with gameId from the list."
+            : "Recovery: create the store game first (summer_store_create_game), then call again with its gameId.", undefined, { games: listed.games });
+    }
+    throw new BuildToolError("game_required", `gameId is required, and the store did not list your games: ${listed.error}`, "Recovery: copy the game id from Studio (the store page URL) and retry.", undefined, { listError: listed.error });
+}
+async function storeToken(deps) {
+    try {
+        return await deps.token();
+    }
+    catch (error) {
+        if (error instanceof OAuthError)
+            throw new BuildToolError(error.code, error.message.replace(` ${error.recovery}`, ""), error.recovery);
+        throw error;
+    }
+}
+/**
+ * Before the person confirms, prove the target is real: the game exists for
+ * this account, and its store page lists the platforms the export targets.
+ */
+export async function checkStoreGame(gameId, exportTargets, deps) {
+    const store = createStore(await resolveGatewayUrl(), await storeToken(deps), deps);
+    let game;
+    try {
+        game = await store.call("GET", `games/${seg(gameId)}`);
+    }
+    catch (error) {
+        if (error instanceof BuildToolError && error.status === 404) {
+            const listed = await listGames(deps);
+            throw new BuildToolError("game_not_found", "games" in listed
+                ? `There is no store game "${gameId}" for this account, so nothing can be uploaded to it.`
+                : `The store did not find game "${gameId}", and did not list your games either: ${listed.error}`, "games" in listed && listed.games.length
+                ? "Recovery: call again with gameId from the list."
+                : "Recovery: create the store game first (summer_store_create_game), or copy its id from Studio (the store page URL).", 404, "games" in listed ? { games: listed.games } : undefined);
+        }
+        throw error;
     }
-    throw new BuildToolError("game_required", "gameId is required: the export is uploaded to one existing game.", games ? "Recovery: pick the game's id from the list and retry." : "Recovery: copy the game id from Studio (the store page URL) and retry.", undefined, games ? { games } : undefined);
+    const targets = Array.isArray(game.supportedPlatforms) ? game.supportedPlatforms.filter((value) => typeof value === "string") : [];
+    // The store page speaks catalog names (ios, android, macos, windows, linux, web) or store ids (macos-universal, ...).
+    const catalog = new Set(targets.map((target) => target.replace(/-(universal|x64)$/, "")));
+    const unlisted = exportTargets.filter((target) => !catalog.has(target));
+    const warnings = unlisted.length
+        ? [`The store page of "${game.name ?? gameId}" does not list ${unlisted.join(", ")} (it lists ${targets.join(", ") || "no platforms"}). Players on ${unlisted.join(", ")} will not see this build until the store page lists them: add them with summer_store_update_listing.`]
+        : [];
+    return { game: { gameId, name: typeof game.name === "string" ? game.name : null, status: typeof game.status === "string" ? game.status : null, targets }, warnings };
 }
 export async function publishBuild(input, overrides = {}) {
     const deps = { ...defaultDependencies, ...overrides };
@@ -288,7 +341,11 @@ export async function publishBuild(input, overrides = {}) {
         const clientVersion = normalizeClientVersion(input.clientVersion);
         if (!gameId)
             return listGamesOrThrow(deps);
-        return publishDownload({ gameId, file, platform, clientVersion, confirm: input.confirm, waitSeconds: input.waitSeconds, face: input.face }, deps);
+        const download = { gameId, file, platform, clientVersion, confirm: input.confirm, waitSeconds: input.waitSeconds, face: input.face };
+        if (input.confirm === true)
+            return publishDownload(download, deps);
+        const preview = await publishDownload(download, deps);
+        return { ...preview, game: (await checkStoreGame(gameId, [], deps)).game };
     }
     if (extname(file).toLowerCase() !== ".zip") {
         throw new BuildToolError("export_format_unsupported", `${file} is not a summer.games .zip export.`, "Recovery: export with summer_export_game and upload that .zip.");
@@ -313,23 +370,18 @@ export async function publishBuild(input, overrides = {}) {
     if (!gameId)
         return listGamesOrThrow(deps);
     if (input.confirm !== true) {
+        const checked = await checkStoreGame(gameId, platforms, deps);
         return {
             ok: true,
             status: "confirmation_required",
             target,
-            next: `Show the user this exact game, file, digest, size, version and publish choice. Only after they approve, call again with confirm=true. Nothing was uploaded.`,
+            game: checked.game,
+            ...(checked.warnings.length ? { warnings: checked.warnings } : {}),
+            next: `Show the user this exact game (name and id), file, digest, size, version and publish choice. Only after they approve, call again with confirm=true. Nothing was uploaded.`,
         };
     }
     const audit = { at: new Date(deps.now()).toISOString(), operation: "publish_build", face: input.face, ...target };
-    let token;
-    try {
-        token = await deps.token();
-    }
-    catch (error) {
-        if (error instanceof OAuthError)
-            throw new BuildToolError(error.code, error.message.replace(` ${error.recovery}`, ""), error.recovery);
-        throw error;
-    }
+    const token = await storeToken(deps);
     const store = createStore(await resolveGatewayUrl(), token, deps);
     await appendStoreJsonLine("creator-audit.jsonl", { ...audit, outcome: "started" });
     // Same keys Studio derives: the same bytes, version and scene are one declaration.

package/dist/core/capabilities/tool-dispatch.js

@@ -49,6 +49,7 @@ import { shapeEngineLogResponse } from "../log-filters.js";
 import { listCreatorReleases, publishCreator, } from "./creator.js";
 import { exportGame } from "./export-game.js";
 import { exportTemplates } from "./export-templates.js";
+import { captureGameplay } from "./capture-gameplay.js";
 import { publishBuild } from "./publish-build.js";
 import { CONFIG_KEYS, getConfigValue, isConfigKey, readSummerConfig, resolveGatewayUrl, setConfigValue, unsetConfigValue, } from "../config.js";
 import { createDebugReportArtifact } from "./debug-report.js";
@@ -630,6 +631,15 @@ export const TOOL_DISPATCH = [
             summerVersion: optStr(args, "summerVersion"),
         });
     }),
+    entry("summer_capture_gameplay", "Capture real gameplay frames offscreen, without a running editor", false, (args) => captureGameplay({
+        project: optStr(args, "project"),
+        scene: optStr(args, "scene"),
+        resolution: optStr(args, "resolution"),
+        frames: optNumberOrUndefined(args, "frames"),
+        waitSeconds: optNumberOrUndefined(args, "waitSeconds"),
+        intervalSeconds: optNumberOrUndefined(args, "intervalSeconds"),
+        out: optStr(args, "out"),
+    })),
     entry("summer_publish_build", "Upload a summer.games export to your store game (confirm-gated)", false, (args) => publishBuild({
         gameId: optStr(args, "gameId"),
         file: optStr(args, "file"),

package/dist/core/config.js

@@ -30,7 +30,7 @@ function validateGatewayUrl(value) {
     }
     const local = parsed.hostname === "localhost" ||
         parsed.hostname === "127.0.0.1" ||
-        parsed.hostname === "::1";
+        parsed.hostname === "[::1]";
     if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) {
         throw new Error("gateway.url must use HTTPS (HTTP is allowed only for localhost). Recovery: set an HTTPS URL and retry.");
     }
@@ -49,7 +49,7 @@ function validateCreatorApiUrl(value) {
     }
     const local = parsed.hostname === "localhost" ||
         parsed.hostname === "127.0.0.1" ||
-        parsed.hostname === "::1";
+        parsed.hostname === "[::1]";
     if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) {
         throw new Error("creator.apiUrl must use HTTPS (HTTP is allowed only for localhost). Recovery: set an HTTPS URL and retry.");
     }

package/dist/core/engine-install.d.ts

@@ -58,6 +58,22 @@ export declare function linuxEngineInstallDir(): string;
 export declare function macEnginePaths(env?: NodeJS.ProcessEnv): string[];
 export declare function windowsEnginePaths(env?: NodeJS.ProcessEnv): string[];
 export declare function linuxEnginePaths(): string[];
+/** Where `summer install` records the engine it installed last
+ *  (~/.summer/engine-install.json), so an install with --path is found later
+ *  without SUMMER_BIN. */
+export declare const ENGINE_INSTALL_FILE = "engine-install.json";
+export interface RecordedEngineInstall {
+    schemaVersion: 1;
+    /** The engine executable (on macOS the one inside Summer.app). */
+    binary: string;
+    version: string | null;
+    installedAt: string;
+}
+export declare function recordEngineInstall(binary: string, version: string | null): Promise<void>;
+/** The engine `summer install` installed last, or null (sync: findEngineBinary is). */
+export declare function recordedEngineBinary(): string | null;
+/** The bundle summer install writes on macOS: <path>/Summer.app, or the path itself when it names a .app. */
+export declare function macInstallDestination(customPath?: string): string;
 export declare function engineBinaryCandidates(os?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string[];
 /** First existing engine binary for this machine, or null. SUMMER_BIN /
  *  SUMMER_ENGINE_BINARY wins when set and present; a set-but-missing override

package/dist/core/engine-install.js

@@ -1,6 +1,7 @@
-import { existsSync, statSync } from "fs";
+import { existsSync, readFileSync, statSync } from "fs";
 import { homedir, platform } from "os";
 import { basename, join } from "path";
+import { getSummerDir, writeStoreJson } from "./store.js";
 /**
  * Where each platform's engine binary lives, shared by `summer install`,
  * `summer run`, and `summer doctor` so they can never disagree about what
@@ -95,6 +96,31 @@ export function windowsEnginePaths(env = process.env) {
 export function linuxEnginePaths() {
     return [join(linuxEngineInstallDir(), LINUX_ENGINE_BINARY_NAME)];
 }
+/** Where `summer install` records the engine it installed last
+ *  (~/.summer/engine-install.json), so an install with --path is found later
+ *  without SUMMER_BIN. */
+export const ENGINE_INSTALL_FILE = "engine-install.json";
+export async function recordEngineInstall(binary, version) {
+    const record = { schemaVersion: 1, binary, version, installedAt: new Date().toISOString() };
+    await writeStoreJson(ENGINE_INSTALL_FILE, record);
+}
+/** The engine `summer install` installed last, or null (sync: findEngineBinary is). */
+export function recordedEngineBinary() {
+    try {
+        const record = JSON.parse(readFileSync(join(getSummerDir(), ENGINE_INSTALL_FILE), "utf8"));
+        return record.schemaVersion === 1 && typeof record.binary === "string" && record.binary ? record.binary : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The bundle summer install writes on macOS: <path>/Summer.app, or the path itself when it names a .app. */
+export function macInstallDestination(customPath) {
+    if (!customPath?.trim())
+        return "/Applications/Summer.app";
+    const trimmed = customPath.trim().replace(/\/+$/, "");
+    return /\.app$/i.test(trimmed) ? trimmed : join(trimmed, "Summer.app");
+}
 export function engineBinaryCandidates(os = platform(), env = process.env) {
     const override = engineBinaryOverride(env)?.path;
     const platformPaths = os === "darwin"
@@ -102,7 +128,11 @@ export function engineBinaryCandidates(os = platform(), env = process.env) {
         : os === "linux"
             ? linuxEnginePaths()
             : windowsEnginePaths(env);
-    return override ? [override, ...platformPaths] : platformPaths;
+    // The engine summer install put in place last wins over the default
+    // locations (an install with --path next to an older /Applications copy).
+    const recorded = recordedEngineBinary();
+    const paths = recorded ? [recorded, ...platformPaths.filter((path) => path !== recorded)] : platformPaths;
+    return override ? [override, ...paths] : paths;
 }
 /** First existing engine binary for this machine, or null. SUMMER_BIN /
  *  SUMMER_ENGINE_BINARY wins when set and present; a set-but-missing override