summer-engine 3.3.0 → 3.4.1

package/dist/core/capabilities/export-game.d.ts

@@ -7,7 +7,7 @@ export { runEngine, SUMMER_GAMES_PRESET, type EngineRun };
  * 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
@@ -69,10 +69,16 @@ export interface ExportGameResult {
     icon?: string | null;
     /** Download format: what signing the file carries. */
     signing?: string;
+    /** Files in the project folder the export created, changed or removed (export_presets.cfg, project.godot, ...). */
+    projectChanges?: ProjectChange[];
     /** Things the store will still refuse or warn about, in plain words. */
     warnings?: string[];
     next: string;
 }
+export interface ProjectChange {
+    file: string;
+    change: "created" | "modified" | "deleted";
+}
 export interface LastExport {
     path: string;
     project: string;
@@ -84,6 +90,8 @@ export interface LastExport {
 }
 export interface ExportGameDependencies {
     findBinary: () => string | null;
+    /** Installed Summer version of the binary (Info.plist, sq.version), or null. */
+    engineVersion: (binary: string) => string | null;
     run: (binary: string, args: string[], timeoutMs: number) => Promise<EngineRun>;
     now: () => Date;
     /** Template lookup for download exports (overridable in tests). */

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
@@ -35,15 +36,15 @@ export { runEngine, SUMMER_GAMES_PRESET };
  */
 export const LAST_EXPORT_FILE = "last-export.json";
 const DEFAULT_TIMEOUT_MS = 15 * 60_000;
-/** Store platform ids of the versions intake (summer-platform creatorstore). */
+/** Store platform ids of the store's versions intake. */
 const STORE_VERSION_PLATFORM = {
     web: "web",
     macos: "macos-universal",
     windows: "windows-x64",
 };
-/** Web zip limits of the store (summer-platform internal/creatorstore/webzip.go). */
+/** Web zip limits of the store. */
 const WEB_LIMITS = { zipBytes: 500 * 1024 * 1024, fileBytes: 200 * 1024 * 1024, files: 2000 };
-/** Games without a server run on the phone apps only (summer-platform gameplatforms.StandaloneTargets). */
+/** Games without a server run on the phone apps only (the store's standalone targets). */
 const STANDALONE_TARGETS = ["ios", "android"];
 /** Engine support per bundle target, for the recovery text when a target is missing. */
 const TARGET_ENGINE_NOTE = {
@@ -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/export-presets.d.ts

@@ -1,7 +1,7 @@
 /**
  * Store targets for summer_export_game, and the export presets that make them.
  *
- * The Summer Games store has two intakes (summer-platform):
+ * The Summer Games store has two intakes:
  * - build-publications takes ONE summer.bundle.v1 .zip per Build. Summer runs
  *   its client.pck on its own client templates (the Summer Games iOS and
  *   Android apps, the Summer desktop app on macOS and Windows), so the creator

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

@@ -5,7 +5,7 @@ import { BuildToolError } from "./summer-bundle.js";
 /**
  * Store targets for summer_export_game, and the export presets that make them.
  *
- * The Summer Games store has two intakes (summer-platform):
+ * The Summer Games store has two intakes:
  * - build-publications takes ONE summer.bundle.v1 .zip per Build. Summer runs
  *   its client.pck on its own client templates (the Summer Games iOS and
  *   Android apps, the Summer desktop app on macOS and Windows), so the creator

package/dist/core/capabilities/fabricate-mesh.d.ts

@@ -4,7 +4,7 @@
  * (`summer tool fabricate-3d`) so both faces validate the same arguments, send
  * the same op with the same clamps, and wait the same client poll budget.
  *
- * What the op does on the engine side (fabricate_ops.cpp, mesh fabrication): run one
+ * What the op does on the engine side: run one
  * agent-authored bpy script in a supervised headless child of the USER'S OWN
  * Blender install, validate the .glb the child exported, move it under res://,
  * wait for the editor import to settle, and optionally instantiate it into the
@@ -28,8 +28,7 @@ export declare const FABRICATE_DEFAULT_OUT_DIR = "res://assets/fabricated/";
 /** What the tool tells the model to do when the engine lacks FabricateMesh. */
 export declare const FABRICATE_FALLBACK = "generate the asset with summer_generate_3d, import one from the free library with summer_search_assets / summer_import_asset, use summer_import_hdri for environment lighting, or build blockout geometry in-scene with summer_add_node / summer_set_prop or a summer_run_editor_script";
 /**
- * Mirror of the engine's out_path pre-validation (fabricate_ops.cpp
- * _resolve_out_path) so a bad destination is refused on this side with the
+ * Mirror of the engine's out_path pre-validation so a bad destination is refused on this side with the
  * same words, and nothing is sent. Returns null when the path is acceptable.
  */
 export declare function fabricateOutPathProblem(rawPath: string): string | null;

package/dist/core/capabilities/fabricate-mesh.js

@@ -4,7 +4,7 @@
  * (`summer tool fabricate-3d`) so both faces validate the same arguments, send
  * the same op with the same clamps, and wait the same client poll budget.
  *
- * What the op does on the engine side (fabricate_ops.cpp, mesh fabrication): run one
+ * What the op does on the engine side: run one
  * agent-authored bpy script in a supervised headless child of the USER'S OWN
  * Blender install, validate the .glb the child exported, move it under res://,
  * wait for the editor import to settle, and optionally instantiate it into the
@@ -30,8 +30,7 @@ export const FABRICATE_DEFAULT_OUT_DIR = "res://assets/fabricated/";
 export const FABRICATE_FALLBACK = "generate the asset with summer_generate_3d, import one from the free library with summer_search_assets / summer_import_asset, use summer_import_hdri for environment lighting, or build blockout geometry in-scene with summer_add_node / summer_set_prop or a summer_run_editor_script";
 const VECTOR3_VARIANT_RE = /^Vector3\(\s*[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?\s*,\s*[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?\s*,\s*[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?\s*\)$/;
 /**
- * Mirror of the engine's out_path pre-validation (fabricate_ops.cpp
- * _resolve_out_path) so a bad destination is refused on this side with the
+ * Mirror of the engine's out_path pre-validation so a bad destination is refused on this side with the
  * same words, and nothing is sent. Returns null when the path is acceptable.
  */
 export function fabricateOutPathProblem(rawPath) {

package/dist/core/capabilities/frame-quality.d.ts

@@ -1,17 +1,17 @@
 /**
  * Frame-quality probe for engine screenshots (tool/screenshot).
  *
- * WHY THIS EXISTS. In the 2026-09-03 end-to-end run (docs/design/archive/E2E-2026-09-03.md,
- * F-01) `summer_screenshot target:"viewport"` returned an entirely black
+ * WHY THIS EXISTS. In the 2026-09-03 end-to-end run,
+ * `summer_screenshot target:"viewport"` returned an entirely black
  * 1072x1280 JPEG (src/core/capabilities/__fixtures__/frames/01-mcp-viewport-black.jpg)
  * with a caption
  * telling the agent to describe what it saw. It was the first viewport capture
  * after scene mutations had flipped the editor from the 3D to the 2D tab; the
  * same call 67 s later returned real content. Engine side, the ViewportSnapshot
- * op (summerengine modules/1summer_engine/editor/ops/debug_ops.cpp) reads the
+ * op reads the
  * editor SubViewport's texture with get_texture()->get_image() AS-IS — no forced
  * RenderingServer draw and no blank-frame retry, both of which ScenePreview has
- * (preview_ops.cpp "render-readiness hardening") because a not-yet-drawn
+ * because a not-yet-drawn
  * texture reads back black. That is consistent with a 2D subviewport that had
  * not been redrawn since the tab switch, but it has NOT been proven by
  * instrumenting the engine, so this module detects the SYMPTOM (a flat frame)

package/dist/core/capabilities/frame-quality.js

@@ -1,17 +1,17 @@
 /**
  * Frame-quality probe for engine screenshots (tool/screenshot).
  *
- * WHY THIS EXISTS. In the 2026-09-03 end-to-end run (docs/design/archive/E2E-2026-09-03.md,
- * F-01) `summer_screenshot target:"viewport"` returned an entirely black
+ * WHY THIS EXISTS. In the 2026-09-03 end-to-end run,
+ * `summer_screenshot target:"viewport"` returned an entirely black
  * 1072x1280 JPEG (src/core/capabilities/__fixtures__/frames/01-mcp-viewport-black.jpg)
  * with a caption
  * telling the agent to describe what it saw. It was the first viewport capture
  * after scene mutations had flipped the editor from the 3D to the 2D tab; the
  * same call 67 s later returned real content. Engine side, the ViewportSnapshot
- * op (summerengine modules/1summer_engine/editor/ops/debug_ops.cpp) reads the
+ * op reads the
  * editor SubViewport's texture with get_texture()->get_image() AS-IS — no forced
  * RenderingServer draw and no blank-frame retry, both of which ScenePreview has
- * (preview_ops.cpp "render-readiness hardening") because a not-yet-drawn
+ * because a not-yet-drawn
  * texture reads back black. That is consistent with a 2D subviewport that had
  * not been redrawn since the tab switch, but it has NOT been proven by
  * instrumenting the engine, so this module detects the SYMPTOM (a flat frame)

package/dist/core/capabilities/grep.d.ts

@@ -1,7 +1,7 @@
 /**
  * grep — ONE implementation of `summer_grep` for both faces
  * (src/mcp/tools/file-tools.ts and tool-dispatch.ts), over the engine's
- * ripgrep-backed Grep op (modules/1summer_engine/editor/ops/search_ops.cpp).
+ * ripgrep-backed Grep op.
  *
  * The engine op returns {file, line, content} per match and parses only
  * ripgrep's "match" events, so its contextLines flag adds nothing to the

package/dist/core/capabilities/grep.js

@@ -1,7 +1,7 @@
 /**
  * grep — ONE implementation of `summer_grep` for both faces
  * (src/mcp/tools/file-tools.ts and tool-dispatch.ts), over the engine's
- * ripgrep-backed Grep op (modules/1summer_engine/editor/ops/search_ops.cpp).
+ * ripgrep-backed Grep op.
  *
  * The engine op returns {file, line, content} per match and parses only
  * ripgrep's "match" events, so its contextLines flag adds nothing to the

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/navigation/open.d.ts

@@ -12,7 +12,7 @@
  * advertises `capabilities.navigation` the tool sends the one-table op
  * `Navigate { target, ...args }`; on an engine that predates it the few ids the
  * original ops can serve (scene, node, script, file, the three docks) use those
- * ops and everything else answers `engine_lacks_op`. See NAVIGATION-PLAN.md.
+ * ops and everything else answers `engine_lacks_op`.
  *
  * Both faces call runOpen(); the CLI (tool-dispatch + `summer open`) and the
  * MCP tool (src/mcp/tools/navigation-tools.ts) only differ in how the engine

package/dist/core/capabilities/navigation/open.js

@@ -12,7 +12,7 @@
  * advertises `capabilities.navigation` the tool sends the one-table op
  * `Navigate { target, ...args }`; on an engine that predates it the few ids the
  * original ops can serve (scene, node, script, file, the three docks) use those
- * ops and everything else answers `engine_lacks_op`. See NAVIGATION-PLAN.md.
+ * ops and everything else answers `engine_lacks_op`.
  *
  * Both faces call runOpen(); the CLI (tool-dispatch + `summer open`) and the
  * MCP tool (src/mcp/tools/navigation-tools.ts) only differ in how the engine

package/dist/core/capabilities/navigation/render-product-map.js

@@ -49,7 +49,7 @@ export function renderProductMap() {
     lines.push("## Who owns what");
     lines.push("");
     lines.push("- **Web rows** come from summerengine.com's own route catalog (`/agent-routes.json`, published from the web repo's `src/lib/navigation/routes.ts`). The toolkit vendors a snapshot (`assets/navigation/web-routes.json`, refreshed with `npm run sync:web-routes`); it does not invent pages.");
-    lines.push("- **Editor rows** are ids of Summer Engine's one navigation table (`navigate_ops.cpp`, op `Navigate`). The running engine advertises which ids it can open in `/api/health` `capabilities.navigation`; `summer open --list` shows availability from the connected engine. Engines that predate the `Navigate` op can still serve the rows with a legacy op (last-but-one column); every other row answers `engine_lacks_op` with an update hint.");
+    lines.push("- **Editor rows** are ids of Summer Engine's one navigation table (the `Navigate` op). The running engine advertises which ids it can open in `/api/health` `capabilities.navigation`; `summer open --list` shows availability from the connected engine. Engines that predate the `Navigate` op can still serve the rows with a legacy op (last-but-one column); every other row answers `engine_lacks_op` with an update hint.");
     lines.push("");
     lines.push("## How to read a row");
     lines.push("");

package/dist/core/capabilities/navigation/targets.js

@@ -1,5 +1,5 @@
 /**
- * The product map as the toolkit sees it (docs/design/NAVIGATION-PLAN.md).
+ * The product map as the toolkit sees it (rendered for agents as library/references/product-map).
  *
  * The toolkit does NOT own where things are. Each product does:
  *
@@ -7,7 +7,7 @@
  *   src/lib/navigation/routes.ts). A vendored snapshot lives at
  *   assets/navigation/web-routes.json (refresh: `npm run sync:web-routes`) and
  *   every web row below is built from it — nothing hand-written.
- * - Summer Engine owns one table of editor destinations (navigate_ops.cpp) and
+ * - Summer Engine owns one table of editor destinations (the Navigate op) and
  *   advertises the ids it can open in /api/health capabilities.navigation.
  *   The rows below are METADATA for those ids (titles, intents, argument
  *   names) plus, for the few ids an older engine can serve through its

package/dist/core/capabilities/placement-batch.d.ts

@@ -8,7 +8,7 @@ export type PlacementField = (typeof PLACEMENT_FIELDS)[number];
 /** Model-visible budget for compact receipts (the 5 KB tool-result contract). */
 export declare const COMPACT_LIMIT_BYTES: number;
 /** Held-back transform SetProps sent per request; the engine refuses requests
- *  over 256 ops (local_api_server.cpp). */
+ *  over 256 ops. */
 export declare const TRANSFORM_OPS_PER_REQUEST = 200;
 export interface PlacementProp {
     key: PlacementField;

package/dist/core/capabilities/placement-batch.js

@@ -4,7 +4,7 @@
  * twins.
  *
  * The engine's InstantiateScene accepts only parent / scene / name /
- * target_size (scene_ops.cpp instantiate_scene) and must travel as its own
+ * target_size and must travel as its own
  * request (single-only). A placed piece is therefore an InstantiateScene plus
  * SetProps on the node path its receipt reports (meta.nodePath, which already
  * carries any collision rename). The caller writes ONE op; this module expands
@@ -35,7 +35,7 @@ export const PLACEMENT_FIELDS = ["position", "rotation_degrees", "scale", "trans
 /** Model-visible budget for compact receipts (the 5 KB tool-result contract). */
 export const COMPACT_LIMIT_BYTES = 5 * 1024;
 /** Held-back transform SetProps sent per request; the engine refuses requests
- *  over 256 ops (local_api_server.cpp). */
+ *  over 256 ops. */
 export const TRANSFORM_OPS_PER_REQUEST = 200;
 const SUMMARY_TARGET_BYTES = 4600;
 const ERROR_TEXT_LIMIT = 240;

package/dist/core/capabilities/play-determinism.d.ts

@@ -5,7 +5,7 @@
  * summer_play tool and the CLI dispatcher.
  *
  * Transport note: the engine's /api/play rung copies only `scene` into the
- * PlayGame op (local_api_server.cpp play branch), so a launch that carries a
+ * PlayGame op, so a launch that carries a
  * pin is sent as an explicit PlayGame op through /api/ops instead. A launch
  * without any pin stays on /api/play, byte-for-byte the v1 call.
  *

package/dist/core/capabilities/play-determinism.js

@@ -5,7 +5,7 @@
  * summer_play tool and the CLI dispatcher.
  *
  * Transport note: the engine's /api/play rung copies only `scene` into the
- * PlayGame op (local_api_server.cpp play branch), so a launch that carries a
+ * PlayGame op, so a launch that carries a
  * pin is sent as an explicit PlayGame op through /api/ops instead. A launch
  * without any pin stays on /api/play, byte-for-byte the v1 call.
  *

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

@@ -1,5 +1,5 @@
 import { BuildToolError } from "./summer-bundle.js";
-/** summer-platform client versions: vMAJOR.MINOR.PATCH[-rN]. */
+/** Store client versions: vMAJOR.MINOR.PATCH[-rN]. */
 export declare const CLIENT_VERSION: RegExp;
 export interface PublishBuildInput {
     gameId?: string;
@@ -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;