summer-engine 3.3.0 → 3.4.1

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

@@ -12,8 +12,7 @@ import { BuildToolError, 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,11 +36,11 @@ 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 = {
@@ -61,9 +59,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 +104,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 +261,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 +339,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 +368,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/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

package/dist/core/capabilities/runtime-control.d.ts

@@ -6,8 +6,7 @@
  * both faces validate the same inputs, send the same op and wait the same
  * budget.
  *
- * Engine contract (frozen): doc/SUMMER/SCENE_SCRIPTING_CONTRACTS.md "Wave I —
- * Runtime control & playtest ops" + editor/ops/runtime_ops.h. Every op except
+ * Engine contract (frozen): the runtime control and playtest ops. Every op except
  * ListGameInstances is SINGLE-ONLY and ASYNC (a debugger round-trip needs the
  * reply channel), requires a RUNNING game, accepts `instance?` (default
  * "main"), stamps the game frame it describes, rounds floats to 3dp and
@@ -499,9 +498,8 @@ export declare function playRequestsLocalPlay(args: PlayGameArgs): boolean;
 /**
  * Quiet is the default whenever an agent drives play — both faces of this tool
  * (MCP and `summer tool`) ARE agent faces, so the only way to a focus-stealing
- * launch is an explicit focus:true. Quiet travels as PlayGame `agent:true`
- * (debug_ops.cpp play_game -> GameView::set_agent_quiet_play), which the engine
- * has honoured since 0.5.45 (c7c490d84f3, 2026-07-02).
+ * launch is an explicit focus:true. Quiet travels as PlayGame `agent:true`,
+ * which the engine has honoured since 0.5.45.
  */
 export declare function playIsQuiet(args: PlayGameArgs): boolean;
 /** True when the call needs the PlayGame OP (instance-aware / determinism
@@ -529,8 +527,8 @@ export declare function withLocalPlayEcho(result: unknown, args: PlayGameArgs):
 export declare const PLAY_QUIET_NOT_SUPPORTED = "This Summer Engine build did not echo `agent_quiet` in its PlayGame result \u2014 it predates quiet play and has most likely switched the editor to the Game tab and taken focus. Update Summer Engine (restart it after updating) for launches that leave the user's screen alone.";
 /**
  * Quiet was requested: the engine echoes `agent_quiet` when it understood the
- * flag (debug_ops.cpp play_game — in the launch branch AND the already-running
- * branch on current engines). No echo at all means an engine that predates
+ * flag (in the launch branch AND the already-running branch on current
+ * engines). No echo at all means an engine that predates
  * the flag ignored it — say so instead of letting the model believe the user
  * was left alone. The field is the contract; the `note` text is never matched.
  */

package/dist/core/capabilities/runtime-control.js

@@ -6,8 +6,7 @@
  * both faces validate the same inputs, send the same op and wait the same
  * budget.
  *
- * Engine contract (frozen): doc/SUMMER/SCENE_SCRIPTING_CONTRACTS.md "Wave I —
- * Runtime control & playtest ops" + editor/ops/runtime_ops.h. Every op except
+ * Engine contract (frozen): the runtime control and playtest ops. Every op except
  * ListGameInstances is SINGLE-ONLY and ASYNC (a debugger round-trip needs the
  * reply channel), requires a RUNNING game, accepts `instance?` (default
  * "main"), stamps the game frame it describes, rounds floats to 3dp and
@@ -59,7 +58,7 @@ export const RUNTIME_CONTROL_OP_KINDS = [
     "ListGameInstances",
 ];
 // ---------------------------------------------------------------------------
-// Budgets — mirror the engine's watchdogs (runtime_ops.cpp) plus relay headroom.
+// Budgets — mirror the engine's runtime-op watchdogs plus relay headroom.
 // ---------------------------------------------------------------------------
 /** Default editor-side watchdog for a runtime op (_RT_DEFAULT_TIMEOUT_SEC). */
 export const RUNTIME_WATCHDOG_DEFAULT_SEC = 10;
@@ -882,9 +881,8 @@ export function playRequestsLocalPlay(args) {
 /**
  * Quiet is the default whenever an agent drives play — both faces of this tool
  * (MCP and `summer tool`) ARE agent faces, so the only way to a focus-stealing
- * launch is an explicit focus:true. Quiet travels as PlayGame `agent:true`
- * (debug_ops.cpp play_game -> GameView::set_agent_quiet_play), which the engine
- * has honoured since 0.5.45 (c7c490d84f3, 2026-07-02).
+ * launch is an explicit focus:true. Quiet travels as PlayGame `agent:true`,
+ * which the engine has honoured since 0.5.45.
  */
 export function playIsQuiet(args) {
     return args.focus !== true;
@@ -894,7 +892,7 @@ export function playIsQuiet(args) {
 export function playNeedsOp(args) {
     return (
     // The /api/play rung builds a PlayGame op with ONLY `scene`
-    // (local_api_server.cpp play branch), so `agent:true` has to ride the op.
+    // (the engine's /api/play handler), so `agent:true` has to ride the op.
     playIsQuiet(args) ||
         (typeof args.instance === "string" && args.instance.trim().length > 0) ||
         args.mode !== undefined ||
@@ -1031,8 +1029,8 @@ export function withLocalPlayEcho(result, args) {
 export const PLAY_QUIET_NOT_SUPPORTED = "This Summer Engine build did not echo `agent_quiet` in its PlayGame result — it predates quiet play and has most likely switched the editor to the Game tab and taken focus. Update Summer Engine (restart it after updating) for launches that leave the user's screen alone.";
 /**
  * Quiet was requested: the engine echoes `agent_quiet` when it understood the
- * flag (debug_ops.cpp play_game — in the launch branch AND the already-running
- * branch on current engines). No echo at all means an engine that predates
+ * flag (in the launch branch AND the already-running branch on current
+ * engines). No echo at all means an engine that predates
  * the flag ignored it — say so instead of letting the model believe the user
  * was left alone. The field is the contract; the `note` text is never matched.
  */

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

@@ -4,7 +4,7 @@
  * re-owning step every MCP path that sends ReparentNode shares.
  *
  * Two engine ops answer ok for changes SaveScene then leaves out of the file
- * (engine modules/1summer_engine/editor/ops/scene_ops.cpp, engine 0.6.0):
+ * (engine 0.6.0):
  *
  *  - ReparentNode (SceneOps::reparent_node) re-owns only the node it moves
  *    (`add_do_method(node, "set_owner", root)`). The remove_child before it

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

@@ -4,7 +4,7 @@
  * re-owning step every MCP path that sends ReparentNode shares.
  *
  * Two engine ops answer ok for changes SaveScene then leaves out of the file
- * (engine modules/1summer_engine/editor/ops/scene_ops.cpp, engine 0.6.0):
+ * (engine 0.6.0):
  *
  *  - ReparentNode (SceneOps::reparent_node) re-owns only the node it moves
  *    (`add_do_method(node, "set_owner", root)`). The remove_child before it

package/dist/core/capabilities/scene-kind.js

@@ -1,6 +1,6 @@
 /**
  * Is a scene 2D or 3D? Decided from a scene-tree read, the way the engine's
- * ScenePreview decides it (preview_ops.cpp `_scene_has_3d` / `_scene_has_2d`):
+ * ScenePreview decides it:
  * any Node3D anywhere in the tree makes the scene 3D; otherwise any CanvasItem
  * makes it 2D; a tree of plain Nodes is neither.
  *

package/dist/core/capabilities/scene-readback.d.ts

@@ -4,10 +4,9 @@
  * trusting the engine receipt (summer_replace_node, summer_batch with
  * ReparentNode, summer_connect_signal).
  *
- * The engine's `scenePersistence.persisted` only says SaveScene returned OK
- * (ops_executor.cpp: scene_persistence["persisted"] =
- * explicit_scene_save_succeeded); what the file holds is only known by reading
- * it. The client renames that flag to `saved` (engine-receipt.ts
+ * The engine's `scenePersistence.persisted` only says SaveScene returned OK;
+ * what the file holds is only known by reading it. The client renames that
+ * flag to `saved` (engine-receipt.ts
  * honestSceneReceipt); `verified` is set only by tools that read back here.
  */
 import { type JsonRecord } from "../util/json.js";

package/dist/core/capabilities/scene-readback.js

@@ -4,10 +4,9 @@
  * trusting the engine receipt (summer_replace_node, summer_batch with
  * ReparentNode, summer_connect_signal).
  *
- * The engine's `scenePersistence.persisted` only says SaveScene returned OK
- * (ops_executor.cpp: scene_persistence["persisted"] =
- * explicit_scene_save_succeeded); what the file holds is only known by reading
- * it. The client renames that flag to `saved` (engine-receipt.ts
+ * The engine's `scenePersistence.persisted` only says SaveScene returned OK;
+ * what the file holds is only known by reading it. The client renames that
+ * flag to `saved` (engine-receipt.ts
  * honestSceneReceipt); `verified` is set only by tools that read back here.
  */
 import { asRecord } from "../util/json.js";

package/dist/core/capabilities/scene-script.d.ts

@@ -5,8 +5,8 @@
  *
  * Server-side clamps: RunSceneScript blocks between frames of the LIVE editor,
  * so its ceiling is deliberately low; RunEditorScript boots a whole headless
- * child editor, so its floor covers the boot cost (editor_script_ops.cpp:
- * 15..600 default 120).
+ * child editor, so its floor covers the boot cost (engine clamp: 15..600,
+ * default 120).
  */
 export declare const SCENE_SCRIPT_MIN_SECONDS = 5;
 export declare const SCENE_SCRIPT_MAX_SECONDS = 120;

package/dist/core/capabilities/scene-script.js

@@ -5,8 +5,8 @@
  *
  * Server-side clamps: RunSceneScript blocks between frames of the LIVE editor,
  * so its ceiling is deliberately low; RunEditorScript boots a whole headless
- * child editor, so its floor covers the boot cost (editor_script_ops.cpp:
- * 15..600 default 120).
+ * child editor, so its floor covers the boot cost (engine clamp: 15..600,
+ * default 120).
  */
 export const SCENE_SCRIPT_MIN_SECONDS = 5;
 export const SCENE_SCRIPT_MAX_SECONDS = 120;

package/dist/core/capabilities/seeing/shot-store.d.ts

@@ -2,7 +2,7 @@ export declare const SHOTS_DIR: string;
 export declare const SAVED_SUBDIR = "saved";
 export declare const SHOT_MAX_EDGE = 1024;
 export declare const SHOTS_MAX_TOTAL_BYTES: number;
-/** Same grammar as camera bookmark names (preview_ops.cpp). */
+/** Same grammar as camera bookmark names. */
 export declare const SHOT_NAME_PATTERN: RegExp;
 export declare class ShotStoreError extends Error {
     readonly reason: "bad_name" | "not_jpeg" | "too_large" | "over_cap" | "unsafe_path" | "no_project";

package/dist/core/capabilities/seeing/shot-store.js

@@ -22,7 +22,7 @@ export const SHOTS_DIR = join(".summer", "shots");
 export const SAVED_SUBDIR = "saved";
 export const SHOT_MAX_EDGE = 1024;
 export const SHOTS_MAX_TOTAL_BYTES = 20 * 1024 * 1024;
-/** Same grammar as camera bookmark names (preview_ops.cpp). */
+/** Same grammar as camera bookmark names. */
 export const SHOT_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
 export class ShotStoreError extends Error {
     reason;

package/dist/core/capabilities/summer-bundle.d.ts

@@ -1,9 +1,8 @@
 /**
- * The summer.games export (summer-platform ADR 0033): one .zip with
+ * The summer.games export: one .zip with
  * summer-bundle.json, client.pck, and for a game with a host server.pck plus
  * config/. This reads what the build upload declares; the Platform verifies
- * the uploaded bytes again. Same rules as Studio's browser check
- * (publicsummerengine src/lib/creator-store/pck-check.ts, checkBundle).
+ * the uploaded bytes again. Same rules as Studio's browser check.
  */
 export declare const BUNDLE_SCHEMA = "summer.bundle.v1";
 export declare const BUNDLE_MANIFEST = "summer-bundle.json";

package/dist/core/capabilities/summer-bundle.js

@@ -2,11 +2,10 @@ import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { readZipEntries, readZipEntry, ZipReadError } from "../util/zip.js";
 /**
- * The summer.games export (summer-platform ADR 0033): one .zip with
+ * The summer.games export: one .zip with
  * summer-bundle.json, client.pck, and for a game with a host server.pck plus
  * config/. This reads what the build upload declares; the Platform verifies
- * the uploaded bytes again. Same rules as Studio's browser check
- * (publicsummerengine src/lib/creator-store/pck-check.ts, checkBundle).
+ * the uploaded bytes again. Same rules as Studio's browser check.
  */
 export const BUNDLE_SCHEMA = "summer.bundle.v1";
 export const BUNDLE_MANIFEST = "summer-bundle.json";

package/dist/core/capabilities/surface-snap.d.ts

@@ -1,7 +1,7 @@
 /**
  * surface-snap — ONE implementation of `summer_snap_to_surface` for both faces
  * (src/mcp/tools/spatial-tools.ts and tool-dispatch.ts), around the engine's
- * SnapToSurface op (modules/1summer_engine/editor/ops/surface_snap_ops.cpp).
+ * SnapToSurface op.
  *
  * Two gaps in the engine op, closed here with ops main already ships:
  *

package/dist/core/capabilities/surface-snap.js

@@ -1,7 +1,7 @@
 /**
  * surface-snap — ONE implementation of `summer_snap_to_surface` for both faces
  * (src/mcp/tools/spatial-tools.ts and tool-dispatch.ts), around the engine's
- * SnapToSurface op (modules/1summer_engine/editor/ops/surface_snap_ops.cpp).
+ * SnapToSurface op.
  *
  * Two gaps in the engine op, closed here with ops main already ships:
  *

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"),
@@ -651,7 +661,7 @@ export const TOOL_DISPATCH = [
         confirm: args.confirm === true,
         face: "cli",
     })),
-    entry("summer_creator_releases", "List creator-owned releases", false, (args) => listCreatorReleases({
+    entry("summer_creator_releases", "Deprecated: list releases on the legacy creator API; use summer_store_releases", false, (args) => listCreatorReleases({
         projectId: optStr(args, "projectId"),
         limit: typeof args.limit === "number" ? args.limit : 20,
         cursor: optStr(args, "cursor"),

package/dist/core/capabilities/ui-control.d.ts

@@ -4,8 +4,7 @@
  * both faces validate the same arguments, send the same op, and render the
  * engine's failure taxonomy the same way.
  *
- * Seven engine ops (modules/1summer_engine/editor/ops/ui_ops.cpp, frozen in
- * doc/SUMMER/SCENE_SCRIPTING_CONTRACTS.md "Wave L") behind four tools:
+ * Seven engine ops (a frozen engine contract) behind four tools:
  *
  *   summer_ui_actions     mode:"list"   -> UiListActions   (read)
  *                         mode:"invoke" -> UiInvoke        (mutates)

package/dist/core/capabilities/ui-control.js

@@ -4,8 +4,7 @@
  * both faces validate the same arguments, send the same op, and render the
  * engine's failure taxonomy the same way.
  *
- * Seven engine ops (modules/1summer_engine/editor/ops/ui_ops.cpp, frozen in
- * doc/SUMMER/SCENE_SCRIPTING_CONTRACTS.md "Wave L") behind four tools:
+ * Seven engine ops (a frozen engine contract) behind four tools:
  *
  *   summer_ui_actions     mode:"list"   -> UiListActions   (read)
  *                         mode:"invoke" -> UiInvoke        (mutates)

package/dist/core/capabilities/world-snapshot.d.ts

@@ -3,7 +3,7 @@
  * `summer_world_snapshot` (src/mcp/tools/perception-tools.ts and
  * tool-dispatch.ts).
  *
- * The engine's GetWorldSnapshot (world_snapshot_ops.cpp) takes only
+ * The engine's GetWorldSnapshot op takes only
  * scene_path / max_nodes / max_lights / include_2d and returns every node it
  * walked, about 250 bytes each: a scene of a few thousand nodes is far too
  * big to read.

package/dist/core/capabilities/world-snapshot.js

@@ -3,7 +3,7 @@
  * `summer_world_snapshot` (src/mcp/tools/perception-tools.ts and
  * tool-dispatch.ts).
  *
- * The engine's GetWorldSnapshot (world_snapshot_ops.cpp) takes only
+ * The engine's GetWorldSnapshot op takes only
  * scene_path / max_nodes / max_lights / include_2d and returns every node it
  * walked, about 250 bytes each: a scene of a few thousand nodes is far too
  * big to read.

package/dist/core/capability-skew.d.ts

@@ -77,7 +77,7 @@ export interface EngineCapabilities {
      *  `summer` capture ships, and the offscreen instance cap. Absent = engine
      *  predates runtime control (or advertises the kinds only in opKinds). */
     runtimeControl?: EngineRuntimeControlCapabilities;
-    /** Editor navigation advert (engine `Navigate` op, navigate_ops.cpp): the
+    /** Editor navigation advert (engine `Navigate` op): the
      *  destination ids this build can open. Absent = engine predates the op;
      *  summer_open then falls back to the legacy per-surface ops it can map. */
     navigation?: EngineNavigationCapabilities;
@@ -174,8 +174,7 @@ export declare function missingEngineEventsResult(client: CapabilityAdvertisingC
 export declare function buildCapabilitySkewWarning(health: unknown): string | null;
 /**
  * Engine ops that MUST be dispatched as their own single-op request. Mirrors
- * _summer_requires_single_async_dispatch (local_api_server.cpp, engine
- * 0.5.60+): the engine rejects any multi-op batch containing one of these
+ * the engine's single-async-op list (engine 0.5.60+): the engine rejects any multi-op batch containing one of these
  * WHOLESALE — nothing in the batch executes, and the batch fails with per-op
  * failure_reason "unsupported_transport"/"skipped". Git ops are covered by a
  * prefix check in the dispatchers.

package/dist/core/capability-skew.js

@@ -46,7 +46,7 @@ export const CLI_KNOWN_OP_NEEDS = [
     // summer_grep (core/capabilities/grep.ts)
     "Grep",
     // Navigation (summer_open: core/capabilities/navigation/) — Navigate is the
-    // one-table op (engine navigate_ops.cpp); the other three are the legacy
+    // engine's one-table op; the other three are the legacy
     // fallbacks on engines that predate it.
     "Navigate", "OpenResource", "FocusDock", "RevealInFileSystem",
     // Project + input
@@ -334,8 +334,7 @@ export function buildCapabilitySkewWarning(health) {
 // ---------------------------------------------------------------------------
 /**
  * Engine ops that MUST be dispatched as their own single-op request. Mirrors
- * _summer_requires_single_async_dispatch (local_api_server.cpp, engine
- * 0.5.60+): the engine rejects any multi-op batch containing one of these
+ * the engine's single-async-op list (engine 0.5.60+): the engine rejects any multi-op batch containing one of these
  * WHOLESALE — nothing in the batch executes, and the batch fails with per-op
  * failure_reason "unsupported_transport"/"skipped". Git ops are covered by a
  * prefix check in the dispatchers.
@@ -353,12 +352,12 @@ export const FALLBACK_SINGLE_ONLY_OPS = new Set([
     "RunCommand", "RunVerification", "RunEditorScript", "RunSceneScript",
     "ImportFromUrl", "ImportFromUrlBatch", "ExtractZipFromUrl",
     // Mesh fabrication: a headless Blender child on the same async single-op lane as
-    // RunEditorScript (local_api_server.cpp SUMMER_SINGLE_ASYNC_OPS).
+    // RunEditorScript.
     "FabricateMesh",
     // runtime control (RuntimeOps::async_op_kinds): every op below rides
     // the `summer` debugger capture, so like GameSnapshot each needs the async
     // single-op reply channel. ListGameInstances is deliberately NOT here — it
-    // is a cheap synchronous editor read that batches fine (runtime_ops.h).
+    // is a cheap synchronous editor read that batches fine.
     "SetRuntimeProp", "CallRuntimeMethod", "SpawnRuntimeScene", "FreeRuntimeNode",
     "RuntimeAnimation", "RuntimeAnimationTree", "GetRuntimeBones",
     "GamePause", "GameSpeed", "GameStep",

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.");
     }