summer-engine 3.4.0 → 3.5.0

package/dist/core/capabilities/export-engine-version.js

@@ -7,6 +7,15 @@ import { BuildToolError } from "./summer-bundle.js";
  * summer_export_game writes and fails after a full engine start.
  */
 export const EXPORT_MIN_ENGINE_VERSION = "0.7.0";
+/** Bundle targets that need a newer engine than EXPORT_MIN_ENGINE_VERSION. */
+export const TARGET_MIN_ENGINE_VERSION = { android: "0.7.1" };
+/** The requested targets this engine version cannot export; an unreadable version skips none. */
+export function targetsNeedingNewerEngine(targets, version) {
+    return targets.flatMap((target) => {
+        const needs = TARGET_MIN_ENGINE_VERSION[target];
+        return needs && isVersionAtLeast(version, needs) === false ? [{ target, needs }] : [];
+    });
+}
 export const ENGINE_UPDATE_HOW = 'run "summer install --yes" (or download it from summerengine.com/download)';
 /** Installed Summer version of an engine binary, or null when this system cannot read it. */
 export function installedEngineVersion(binary) {

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

@@ -34,6 +34,8 @@ export interface ExportGameInput {
     out?: string;
     /** Export with debug enabled (--export-debug). */
     debug?: boolean;
+    /** Bundle with targets: set summer.build.json targetPlatforms to the targets first, so the store takes the declaration. */
+    alignDeclaration?: boolean;
     /** Export preset name; the engine's own is "summer.games". Bundle format without targets only. */
     preset?: string;
     /** Store platforms: macos, windows, ios, android, web. */
@@ -52,6 +54,8 @@ export interface ExportGameResult {
     preset: string;
     /** The targets asked for, when any were. */
     targets?: StoreTarget[];
+    /** Asked-for targets left out of the bundle (an engine too old for them); warnings say why. */
+    skippedTargets?: StoreTarget[];
     /** What happened to export_presets.cfg for the preset this export used. */
     presetChange?: EnsuredPreset["change"];
     debug: boolean;

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

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { platform } from "node:os";
 import { engineSelectionFromEnv } from "../engine.js";
@@ -7,10 +7,10 @@ import { findEngineBinary } from "../engine-install.js";
 import { readStoreJson, writeStoreJson } from "../store.js";
 import { writeZip } from "../util/zip-write.js";
 import { engineErrorLines, runEngine } from "./engine-run.js";
-import { assertExportEngine, installedEngineVersion } from "./export-engine-version.js";
+import { assertExportEngine, ENGINE_UPDATE_HOW, installedEngineVersion, targetsNeedingNewerEngine } 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";
+import { BuildToolError, declarationMismatch, hashFile, readSummerBundle, samePlatforms } from "./summer-bundle.js";
 export { runEngine, SUMMER_GAMES_PRESET };
 /**
  * summer_export_game: run the installed Summer Engine headless and return the
@@ -36,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 = {
@@ -272,10 +272,27 @@ async function runExport(deps, binary, project, preset, out, debug, timeoutMs, n
         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) });
     }
 }
+/** Set the project's summer.build.json targetPlatforms to the export targets (a hosted game's Build declaration). */
+async function alignBuildDeclaration(project, targets) {
+    const path = join(project, "summer.build.json");
+    if (!existsSync(path))
+        return;
+    let build;
+    try {
+        build = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        throw new BuildToolError("build_declaration_invalid", "summer.build.json is not valid JSON.", "Recovery: fix summer.build.json, then export again.");
+    }
+    if (Array.isArray(build.targetPlatforms) && samePlatforms(build.targetPlatforms.map(String), targets))
+        return;
+    build.targetPlatforms = [...targets];
+    await writeFile(path, `${JSON.stringify(build, null, 2)}\n`);
+}
 export async function exportGame(input, overrides = {}) {
     const deps = { ...defaultDependencies, ...overrides };
     const project = resolveExportProject(input.project);
-    const targets = input.targets?.length ? normalizeTargets(input.targets) : undefined;
+    let targets = input.targets?.length ? normalizeTargets(input.targets) : undefined;
     const format = resolveFormat(input, targets);
     const debug = input.debug === true;
     const started = deps.now();
@@ -293,13 +310,26 @@ export async function exportGame(input, overrides = {}) {
         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));
+    const engineVersion = deps.engineVersion(binary);
+    assertExportEngine(binary, engineVersion);
+    // A target this engine cannot build is left out, not the whole export.
+    const skipped = format === "bundle" && targets ? targetsNeedingNewerEngine(targets, engineVersion) : [];
+    const skippedWarnings = skipped.map(({ target, needs }) => `${target} was not exported: it needs Summer Engine ${needs} or newer, and ${engineVersion} is installed. Update (${ENGINE_UPDATE_HOW}) and export ${target} again.`);
+    if (skipped.length) {
+        const left = targets.filter((target) => !skipped.some((entry) => entry.target === target));
+        if (!left.length) {
+            throw new BuildToolError("export_target_unsupported", `Summer Engine ${engineVersion} cannot export ${skipped.map((entry) => entry.target).join(", ")}.`, `Recovery: ${skippedWarnings.join(" ")}`, undefined, { engineVersion, skippedTargets: skipped });
+        }
+        targets = left;
+    }
     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);
+    if (targets && input.alignDeclaration === true)
+        await alignBuildDeclaration(project, targets);
     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] ?? []);
@@ -310,10 +340,20 @@ export async function exportGame(input, overrides = {}) {
     }
     const bundle = await readSummerBundle(out);
     const missing = (targets ?? []).filter((target) => !bundle.targetPlatforms.includes(target));
-    if (missing.length) {
+    // Some targets made it: keep the bundle and say which did not.
+    const partial = missing.length > 0 && missing.length < (targets ?? []).length;
+    if (missing.length && !partial) {
         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 = projectChangeWarnings(projectChanges);
+    const warnings = [...skippedWarnings, ...projectChangeWarnings(projectChanges)];
+    const mismatch = declarationMismatch(bundle);
+    if (mismatch) {
+        warnings.unshift(`summer_publish_build will refuse this export (declaration_mismatch): ${mismatch}. Export again with alignDeclaration:true to set summer.build.json targetPlatforms to [${bundle.targetPlatforms.join(", ")}], or with targets equal to what it declares.`);
+    }
+    if (partial) {
+        warnings.push(`This Summer Engine exported the bundle without ${missing.join(", ")}: its summer.games preset has no such platform. ` +
+            ["Update Summer Engine and export them again.", ...missing.flatMap((target) => TARGET_ENGINE_NOTE[target] ?? [])].join(" "));
+    }
     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(", ")}. ` +
@@ -332,6 +372,9 @@ export async function exportGame(input, overrides = {}) {
         project,
         preset,
         ...(targets ? { targets, presetChange: ensured.change } : {}),
+        ...(skipped.length || partial
+            ? { skippedTargets: [...skipped.map((entry) => entry.target), ...(partial ? missing : [])] }
+            : {}),
         debug,
         engine: binary,
         durationMs: deps.now().getTime() - started.getTime(),

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

@@ -1,8 +1,10 @@
 import { z } from "zod";
+/** Image generation can take over a minute on the larger models; wait this long for the server. */
+export declare const IMAGE_GENERATION_TIMEOUT_MS = 180000;
 /** Shared MCP/CLI image request contract; optional flags preserve omission. */
 export declare const imageGenerationArgsSchema: z.ZodObject<{
     prompt: z.ZodString;
-    model: z.ZodDefault<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
     style: z.ZodDefault<z.ZodString>;
     referenceImageUrl: z.ZodOptional<z.ZodString>;
     removeBackground: z.ZodOptional<z.ZodBoolean>;
@@ -10,13 +12,15 @@ export declare const imageGenerationArgsSchema: z.ZodObject<{
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
     options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    out: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     prompt: string;
-    model: string;
     style: string;
     width?: number | undefined;
     height?: number | undefined;
     options?: Record<string, any> | undefined;
+    out?: string | undefined;
+    model?: 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;
@@ -25,9 +29,15 @@ export declare const imageGenerationArgsSchema: z.ZodObject<{
     width?: number | undefined;
     height?: number | undefined;
     options?: Record<string, any> | undefined;
+    out?: string | 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;
 }>;
+/**
+ * Save a generated image where the caller asked (a folder or a file path), or
+ * under TMPDIR/summer-gen. Returns the path, or null when the download failed.
+ */
+export declare function saveGeneratedImage(url: string, out?: string, prefix?: string): Promise<string | null>;

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

@@ -1,11 +1,17 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, extname, join, resolve } from "node:path";
 import { z } from "zod";
+/** Image generation can take over a minute on the larger models; wait this long for the server. */
+export const IMAGE_GENERATION_TIMEOUT_MS = 180_000;
+const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp"]);
 /** Shared MCP/CLI image request contract; optional flags preserve omission. */
 export const imageGenerationArgsSchema = z.object({
     prompt: z.string().describe("Description of the image to generate"),
     model: z
         .string()
-        .default("nano-banana-2")
-        .describe("Model name or full provider ID"),
+        .optional()
+        .describe("Model name or full provider ID. Omit it and the server picks one that reaches the requested size (nano-banana-2 when no size is asked)."),
     style: z
         .string()
         .default("realistic")
@@ -37,4 +43,27 @@ export const imageGenerationArgsSchema = z.object({
         .record(z.any())
         .optional()
         .describe("Extra model params (seed, negative_prompt, ...). The result lists any it did not use in ignoredOptions."),
+    out: z
+        .string()
+        .optional()
+        .describe("Where to save the image on this machine: a folder, or a file path ending in .png, .jpg or .webp. Default: <TMPDIR>/summer-gen/."),
 });
+/**
+ * Save a generated image where the caller asked (a folder or a file path), or
+ * under TMPDIR/summer-gen. Returns the path, or null when the download failed.
+ */
+export async function saveGeneratedImage(url, out, prefix = "img") {
+    try {
+        const target = out?.trim() ? resolve(out.trim()) : join(tmpdir(), "summer-gen");
+        const file = IMAGE_EXTENSIONS.has(extname(target).toLowerCase()) ? target : join(target, `${prefix}-${Date.now()}.png`);
+        await mkdir(dirname(file), { recursive: true });
+        const res = await fetch(url, { signal: AbortSignal.timeout(60_000) });
+        if (!res.ok)
+            return null;
+        await writeFile(file, Buffer.from(await res.arrayBuffer()));
+        return file;
+    }
+    catch {
+        return null;
+    }
+}

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;

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

@@ -8,12 +8,11 @@ import { appendStoreJsonLine } from "../store.js";
 import { readJsonResponse } from "../util/http.js";
 import { readLastExport } from "./export-game.js";
 import { publishDownload } from "./publish-download.js";
-import { BuildToolError, readSummerBundle } from "./summer-bundle.js";
+import { BuildToolError, declarationMismatch, readSummerBundle } from "./summer-bundle.js";
 /**
  * summer_publish_build: upload a summer.games export to the creator's game
  * through the same creator store routes Studio's export upload uses
- * (publicsummerengine /api/creator-store/* -> summer-platform
- * /v1/management/*, build-publications, ADR 0033):
+ * (/api/creator-store/*, build-publications):
  *
  *   POST games/{g}/build-publications            declare the export (idempotent)
  *   POST .../{p}:source-upload                    open the part plan (64 MiB parts)
@@ -24,8 +23,7 @@ import { BuildToolError, readSummerBundle } from "./summer-bundle.js";
  *   POST games/{g}/builds/{b}/client-packages     name the Build's client pack
  *   POST .../{p}:publish                          only with publish=true
  *
- * Mirrors publicsummerengine src/lib/creator-store/pack-upload.ts
- * (uploadExportedGame), including its idempotency keys, so a retry continues
+ * Mirrors Studio's export upload, including its idempotency keys, so a retry continues
  * the same publication instead of creating another one.
  *
  * Auth: the Summer store OAuth token from "summer login --store" (audience
@@ -38,18 +36,18 @@ const CONCURRENCY = 3;
 const PART_RETRIES = 3;
 const DEFAULT_WAIT_SECONDS = 600;
 const POLL_MS = 3_000;
-/** summer-platform client versions: vMAJOR.MINOR.PATCH[-rN]. */
+/** Store client versions: vMAJOR.MINOR.PATCH[-rN]. */
 export const CLIENT_VERSION = /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-r[1-9]\d*)?$/;
 const INTAKE_DONE = ["preview_ready", "published", "ready", "succeeded"];
 const NOT_ACTIONABLE = "deployment_not_actionable";
-/** Games without a server run on the Summer Games phone apps only (summer-platform gameplatforms.StandaloneTargets). */
+/** Games without a server run on the Summer Games phone apps only (the store's standalone targets). */
 const STANDALONE_TARGETS = ["ios", "android"];
 /** Why the Platform did not take the export, in plain words (same text Studio shows). */
 const INTAKE_FAILURES = {
     game_identity_mismatch: "This export belongs to another game. Upload it to its original game, or make a portable export for this game.",
     bundle_invalid: "Summer could not read this export. Export the game again and upload the new file.",
     declaration_mismatch: "The export's game or settings do not match this upload. Use the original game or export a new version with the intended settings.",
-    template_set_unavailable: "Summer Games cannot run this Summer version yet. Update Summer Engine, export again and upload the new file.",
+    template_set_unavailable: "Summer Games cannot run this Summer version yet. If you exported with the newest Summer Engine, Summer Games may still be turning that version on: retry the same upload later, there is nothing to update. With an older engine, update Summer Engine and export again.",
     client_version_conflict: "This version number already belongs to a different export. Use a new clientVersion.",
     artifact_exists: "This exact export is already uploaded for this game. Export a new version and upload that.",
     approval_denied: "Summer Games did not approve this game, so it cannot take new builds.",
@@ -254,6 +252,10 @@ export function normalizeClientVersion(value) {
     return version;
 }
 function targetPlatforms(bundle) {
+    const mismatch = declarationMismatch(bundle);
+    if (mismatch) {
+        throw new BuildToolError("declaration_mismatch", `The store would refuse this upload (declaration_mismatch): ${mismatch}. Nothing was uploaded and no version was used.`, "Recovery: export again with summer_export_game alignDeclaration:true (it sets summer.build.json targetPlatforms to the targets you export), or with targets equal to what summer.build.json declares; then upload the new export.");
+    }
     if (bundle.hosted)
         return bundle.targetPlatforms;
     const other = bundle.targetPlatforms.filter((platform) => !STANDALONE_TARGETS.includes(platform));
@@ -423,7 +425,17 @@ export async function publishBuild(input, overrides = {}) {
                 break;
             if (publication.state === "failed" || publication.state === "cancelled") {
                 const code = typeof publication.errorCode === "string" ? publication.errorCode : "publication_failed";
-                throw new BuildToolError(code, (code === "declaration_mismatch" && publication.errorMessage) || INTAKE_FAILURES[code] || publication.errorMessage || "Summer could not make a build from this upload.", "Recovery: export again, use a new clientVersion, and retry.", undefined, { publicationId });
+                throw new BuildToolError(code, ((code === "declaration_mismatch" || code === "template_set_unavailable") && publication.errorMessage) ||
+                    INTAKE_FAILURES[code] ||
+                    publication.errorMessage ||
+                    "Summer could not make a build from this upload.", 
+                // The store checks the declaration and the bundle before it records a
+                // client pack, so those refusals leave the version free.
+                code === "declaration_mismatch" || code === "bundle_invalid"
+                    ? "Recovery: fix what the message names, export again and retry; the same clientVersion still works, because a refused upload records no version."
+                    : code === "template_set_unavailable"
+                        ? `Recovery: ${INTAKE_FAILURES.template_set_unavailable.replace(/^Summer Games cannot run this Summer version yet\. /, "")} The same clientVersion works on the retry.`
+                        : "Recovery: export again, use a new clientVersion, and retry.", undefined, { publicationId });
             }
             if (deps.now() >= deadline) {
                 const result = {

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

@@ -1,7 +1,6 @@
 import { type PublishBuildDependencies } from "./publish-build.js";
 /**
- * The store's second build path (summer-platform store versions,
- * internal/creatorstore): a web build (an HTML5 .zip played on summer.games)
+ * The store's second build path (store versions): a web build (an HTML5 .zip played on summer.games)
  * or a native download (macOS universal, Windows x64, Linux x64) that players
  * download. summer_export_game format "download" makes these files;
  * summer_publish_build uploads them here, through the same creator store

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

@@ -7,8 +7,7 @@ import { readZipEntries } from "../util/zip.js";
 import { BuildToolError } from "./summer-bundle.js";
 import { createStore, readGrants, uploadParts } from "./publish-build.js";
 /**
- * The store's second build path (summer-platform store versions,
- * internal/creatorstore): a web build (an HTML5 .zip played on summer.games)
+ * The store's second build path (store versions): a web build (an HTML5 .zip played on summer.games)
  * or a native download (macOS universal, Windows x64, Linux x64) that players
  * download. summer_export_game format "download" makes these files;
  * summer_publish_build uploads them here, through the same creator store
@@ -25,7 +24,7 @@ import { createStore, readGrants, uploadParts } from "./publish-build.js";
  * already live the store refuses an agent's :complete (the owner finishes it).
  */
 export const DOWNLOAD_PLATFORMS = ["web", "macos-universal", "windows-x64", "linux-x64"];
-/** summer-platform creatorstore limits (versions.go, webzip.go). */
+/** The store's upload limits for store versions and web zips. */
 const WEB_MAX_BYTES = 500 * 1024 * 1024;
 const WEB_MAX_FILES = 2000;
 const WEB_MAX_FILE_BYTES = 200 * 1024 * 1024;

package/dist/core/capabilities/replace-node.d.ts

@@ -3,9 +3,7 @@
  * (src/mcp/tools/scene-tools.ts and tool-dispatch.ts), built from ops whose
  * results persist, and verified against the SAVED scene file.
  *
- * Why not the engine's ReplaceNode op for scenes: SceneOps::replace_node
- * (engine modules/1summer_engine/editor/ops/scene_ops.cpp, scene branch and
- * the async _finish_replace_node) instantiates the new PackedScene and hands
+ * Why not the engine's ReplaceNode op for scenes: for a scene it instantiates the new PackedScene and hands
  * it to SceneTreeDock::replace_node — the editor's "Change Type" path — which
  * ends in Node::replace_by (scene/main/node.cpp). replace_by finishes with
  * `p_node->set_scene_file_path(get_scene_file_path())`: the new instance is

package/dist/core/capabilities/replace-node.js

@@ -3,9 +3,7 @@
  * (src/mcp/tools/scene-tools.ts and tool-dispatch.ts), built from ops whose
  * results persist, and verified against the SAVED scene file.
  *
- * Why not the engine's ReplaceNode op for scenes: SceneOps::replace_node
- * (engine modules/1summer_engine/editor/ops/scene_ops.cpp, scene branch and
- * the async _finish_replace_node) instantiates the new PackedScene and hands
+ * Why not the engine's ReplaceNode op for scenes: for a scene it instantiates the new PackedScene and hands
  * it to SceneTreeDock::replace_node — the editor's "Change Type" path — which
  * ends in Node::replace_by (scene/main/node.cpp). replace_by finishes with
  * `p_node->set_scene_file_path(get_scene_file_path())`: the new instance is