summer-engine 3.4.0 → 3.4.1

package/dist/cli/commands/skills.js

@@ -340,7 +340,7 @@ skillsCommand
         console.log(previewIncludedLine(previewIncluded));
     if (previewSkipped > 0)
         console.log(previewSkippedLine(previewSkipped));
-    // Claude Code: also install slash commands (`tools/summer-cli/commands/*.md`)
+    // Claude Code: also install slash commands (`commands/*.md`)
     // into `~/.claude/commands/`. Other agents don't have an equivalent today.
     if (agent === "claude-code") {
         const commandResults = installClaudeCommands(scope, Boolean(opts.force));
@@ -352,7 +352,7 @@ skillsCommand
     printInstallSummary(skills.length, agent, scope, location);
 });
 /**
- * Copy every `.md` file in `tools/summer-cli/commands/` to the user's
+ * Copy every `.md` file in the package's `commands/` to the user's
  * `~/.claude/commands/` directory so the slash commands (e.g. `/gameskill`)
  * are available on every machine that runs `summer skills install`.
  *

package/dist/core/api-client.d.ts

@@ -22,7 +22,7 @@ export type EngineSnapshot = {
     /** Structured failure classifier the engine returns on a game snapshot over
      *  local HTTP (409 `bridge_required`) — surfaced verbatim so the tool can give
      *  an honest, actionable message instead of a truncated generic 409 string.
-     *  When P4.4 lands (game snapshots answer 200/202 over HTTP) this simply
+     *  Once game snapshots answer 200/202 over HTTP this simply
      *  never fires and the tool works. */
     failureReason?: string;
     /** Scene-preview confession fields (P4.3). Populated only for target:"scene".
@@ -194,8 +194,8 @@ export declare class EngineApiClient {
     private _parseSnapshotResponse;
     /**
      * Turn a 409 from /api/snapshot/game into a structured failure. The engine's
-     * structural refusal carries `bridge_required` / `unsupported_transport`
-     * (tool_net_thread.cpp:495-503); a 409 without that shape is surfaced as a
+     * structural refusal carries `bridge_required` / `unsupported_transport`;
+     * a 409 without that shape is surfaced as a
      * plain error rather than silently claiming "bridge required".
      */
     private _bridgeRequiredFromResponse;
@@ -246,9 +246,8 @@ export declare class EngineApiClient {
     getPort(): number;
     /**
      * Cheap drift probe for the MCP client cache. The engine mints a fresh
-     * api-token on every launch (local_api_server.cpp::_generate_api_token) and can
-     * bind a different port (tool_net_thread.cpp::start increments 6550..6565 when
-     * the old socket lingers), so a client built before an engine restart holds
+     * api-token on every launch and can bind a different port (it increments
+     * 6550..6565 when the old socket lingers), so a client built before an engine restart holds
      * dead credentials. Re-read the on-disk creds and report whether they no longer
      * match this client's snapshot.
      *

package/dist/core/api-client.js

@@ -492,8 +492,7 @@ export class EngineApiClient {
     async getSceneState(scenePath, options) {
         // depth/limit/root only take effect on targeted (scene=) reads: the engine
         // routes those through the live command queue and forwards every query
-        // param into StateProvider::scene_state (tool_net_thread.cpp
-        // _parse_state_args). An UNtargeted read is answered from a pre-published
+        // param into the engine's scene-state reader. An UNtargeted read is answered from a pre-published
         // snapshot built with the defaults (depth 2, limit 200) and its query
         // params are ignored — callers who need depth/limit must pass scenePath
         // (summer_get_scene_tree resolves the current scene path for this).
@@ -515,9 +514,8 @@ export class EngineApiClient {
     async getProjectState(prefix) {
         // ?prefix= is sent for forward-compatibility, but current engine builds
         // IGNORE it: /api/state/project is always served from the snapshot, which
-        // is published with empty args (local_api_server.cpp
-        // _maybe_publish_snapshot), so StateProvider::project_state never sees the
-        // query. Callers that need a prefix subset must also filter client-side
+        // is published with empty args, so the engine's project-state reader never
+        // sees the query. Callers that need a prefix subset must also filter client-side
         // (summer_get_project_context does).
         const query = prefix ? `?prefix=${encodeURIComponent(prefix)}` : "";
         return this.request("GET", `/api/state/project${query}`);
@@ -542,13 +540,13 @@ export class EngineApiClient {
         if (pins) {
             // Determinism params (seed / fixed_fps / time_scale) — the /api/play rung
             // copies ONLY `scene` from options into the PlayGame op
-            // (local_api_server.cpp play branch), so a pinned launch travels as an
+            // (the engine's /api/play handler), so a pinned launch travels as an
             // explicit PlayGame op through /api/ops. executeOps stamps the bound
             // identity like every other op. An engine that predates the params
             // ignores the extra keys and answers the v1 result (no `determinism`).
             return this.executeOps([{ op: "PlayGame", ...(scene ? { scene } : {}), ...pins }], undefined, 60_000);
         }
-        // The engine reads play params from body.options (tool_net_thread.cpp:503),
+        // The engine reads play params from body.options,
         // and the play handler reads options["scene"] — a top-level { scene } is
         // dropped, so the scene MUST be nested inside options. The bound identity
         // rides in the same options dict so play is refused on a mismatched project.
@@ -593,10 +591,10 @@ export class EngineApiClient {
         // with the same payload shape — _requestQueued resolves both.
         //
         // Game capture over local HTTP structurally 409s today with a STRUCTURED
-        // reason (`failure_reason:"unsupported_transport"`, `bridge_required:true`,
-        // tool_net_thread.cpp:495-503). Detect that specific shape and return it
+        // reason (`failure_reason:"unsupported_transport"`, `bridge_required:true`).
+        // Detect that specific shape and return it
         // verbatim so the tool can give an honest message — do NOT hardcode "game
-        // always fails": once the engine answers 200/202 (P4.4), the same response
+        // always fails": once the engine answers 200/202, the same response
         // flows into the normal queued path. ONE request either way: a probe that
         // discarded a 200 (or orphaned an accepted 202 requestId) and then asked
         // again would capture the game twice.
@@ -681,8 +679,8 @@ export class EngineApiClient {
     }
     /**
      * Turn a 409 from /api/snapshot/game into a structured failure. The engine's
-     * structural refusal carries `bridge_required` / `unsupported_transport`
-     * (tool_net_thread.cpp:495-503); a 409 without that shape is surfaced as a
+     * structural refusal carries `bridge_required` / `unsupported_transport`;
+     * a 409 without that shape is surfaced as a
      * plain error rather than silently claiming "bridge required".
      */
     async _bridgeRequiredFromResponse(res) {
@@ -777,9 +775,8 @@ export class EngineApiClient {
     }
     /**
      * Cheap drift probe for the MCP client cache. The engine mints a fresh
-     * api-token on every launch (local_api_server.cpp::_generate_api_token) and can
-     * bind a different port (tool_net_thread.cpp::start increments 6550..6565 when
-     * the old socket lingers), so a client built before an engine restart holds
+     * api-token on every launch and can bind a different port (it increments
+     * 6550..6565 when the old socket lingers), so a client built before an engine restart holds
      * dead credentials. Re-read the on-disk creds and report whether they no longer
      * match this client's snapshot.
      *

package/dist/core/auth.js

@@ -161,8 +161,8 @@ export async function saveLoginSession(session) {
     // those exact files. credential-metadata.json adds audience/scope information
     // without changing or duplicating the secret.
     // Write order: user.json, then auth-token, then the advisory metadata. The
-    // desktop engine cross-checks token.sub against user.json's id
-    // (summerengine auth_manager.cpp, inspect_cli_bootstrap_credential), so a
+    // desktop engine cross-checks token.sub against user.json's id when it
+    // adopts the CLI credential, so a
     // write interrupted between the first two files fails closed instead of
     // adopting a mismatched identity. The metadata write is last and is NOT a
     // gate: the token is already live by then, and its contents are re-derived

package/dist/core/capabilities/asset-import.d.ts

@@ -2,7 +2,6 @@
  * Asset import into the engine-bound project (Kenney texture pairing + path
  * inference + optional scene placement). ONE copy shared by the MCP asset tools
  * and the CLI dispatch table.
- * See: publicsummerengine/Docs/ASSET_IMPORT_END_TO_END.md
  */
 import type { EngineApiClient } from "../api-client.js";
 /** An asset record as returned by the Summer gateway asset APIs. */

package/dist/core/capabilities/camera-view.d.ts

@@ -4,7 +4,7 @@ export type CameraBookmarkAction = (typeof CAMERA_BOOKMARK_ACTIONS)[number];
 export declare const CAMERA_BOOKMARK_OPS: Record<CameraBookmarkAction, string>;
 /** What the engine_lacks_op result tells the model to do instead. */
 export declare const CAMERA_BOOKMARK_FALLBACK = "pass the pose explicitly on every capture with summer_screenshot framing:\"free\" (camera_position + camera_look_at), or render through a Camera3D placed in the scene with framing:\"camera\"";
-/** Bookmark name grammar (preview_ops.cpp): 1-64 of [A-Za-z0-9_-]. */
+/** Bookmark name grammar (same as the engine's): 1-64 of [A-Za-z0-9_-]. */
 export declare const BOOKMARK_NAME_PATTERN: RegExp;
 export interface CameraBookmarkArgs {
     action: CameraBookmarkAction;

package/dist/core/capabilities/camera-view.js

@@ -4,7 +4,7 @@
  * and the CLI dispatcher so both faces validate the same way and send the same
  * op.
  *
- * Engine contract (doc/SUMMER/SCENE_SCRIPTING_CONTRACTS.md, "Wave I"):
+ * Engine contract:
  *   SaveCameraBookmark { name, position?, look_at?, fov? }  -> pose_source
  *   ListCameraBookmarks {}                                   -> names, bookmarks
  *   DeleteCameraBookmark { name }                            -> remaining
@@ -25,7 +25,7 @@ export const CAMERA_BOOKMARK_OPS = {
 };
 /** What the engine_lacks_op result tells the model to do instead. */
 export const CAMERA_BOOKMARK_FALLBACK = "pass the pose explicitly on every capture with summer_screenshot framing:\"free\" (camera_position + camera_look_at), or render through a Camera3D placed in the scene with framing:\"camera\"";
-/** Bookmark name grammar (preview_ops.cpp): 1-64 of [A-Za-z0-9_-]. */
+/** Bookmark name grammar (same as the engine's): 1-64 of [A-Za-z0-9_-]. */
 export const BOOKMARK_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
 function requireBookmarkName(name, action) {
     const trimmed = name?.trim() ?? "";

package/dist/core/capabilities/connect-signal.d.ts

@@ -3,8 +3,7 @@
  * (src/mcp/tools/scene-tools.ts and tool-dispatch.ts) that leaves the
  * connection in the saved scene, verified from the file.
  *
- * Why not the engine's ConnectSignal op: SceneOps::connect_signal (engine
- * modules/1summer_engine/editor/ops/scene_ops.cpp) builds
+ * Why not the engine's ConnectSignal op: it builds
  * `Callable(receiver, method)` and registers
  * `add_do_method(emitter, "connect", signal, cb)` — no CONNECT_PERSIST, and the
  * op reads no flags argument. PackedScene::pack writes only persistent

package/dist/core/capabilities/connect-signal.js

@@ -3,8 +3,7 @@
  * (src/mcp/tools/scene-tools.ts and tool-dispatch.ts) that leaves the
  * connection in the saved scene, verified from the file.
  *
- * Why not the engine's ConnectSignal op: SceneOps::connect_signal (engine
- * modules/1summer_engine/editor/ops/scene_ops.cpp) builds
+ * Why not the engine's ConnectSignal op: it builds
  * `Callable(receiver, method)` and registers
  * `add_do_method(emitter, "connect", signal, cb)` — no CONNECT_PERSIST, and the
  * op reads no flags argument. PackedScene::pack writes only persistent

package/dist/core/capabilities/console-read.d.ts

@@ -6,8 +6,8 @@
  * Output panel (EditorLog) never received them: a running game's errors are
  * collected by the debugger (summer_get_debugger_errors / the `debugger`
  * section of summer_get_diagnostics). The engine types console lines straight
- * from EditorLog::MSG_TYPE (error / warning / std / editor — debug_ops.cpp
- * GetConsoleOutput), so dropping `std` lines by default hides nothing that
+ * from EditorLog::MSG_TYPE (error / warning / std / editor) in
+ * GetConsoleOutput, so dropping `std` lines by default hides nothing that
  * was an error; the trap is treating this tool's count as the post-play
  * verdict at all. The note travels with the result because tool descriptions
  * are read once and results are read every time.

package/dist/core/capabilities/console-read.js

@@ -6,8 +6,8 @@
  * Output panel (EditorLog) never received them: a running game's errors are
  * collected by the debugger (summer_get_debugger_errors / the `debugger`
  * section of summer_get_diagnostics). The engine types console lines straight
- * from EditorLog::MSG_TYPE (error / warning / std / editor — debug_ops.cpp
- * GetConsoleOutput), so dropping `std` lines by default hides nothing that
+ * from EditorLog::MSG_TYPE (error / warning / std / editor) in
+ * GetConsoleOutput, so dropping `std` lines by default hides nothing that
  * was an error; the trap is treating this tool's count as the post-play
  * verdict at all. The note travels with the result because tool descriptions
  * are read once and results are read every time.

package/dist/core/capabilities/engine-receipt.d.ts

@@ -26,10 +26,9 @@ export declare function getFailureReason(value: {
  * Decide whether an engine result envelope represents a FAILURE, and if so
  * return a model-visible message. Returns null only for genuine success.
  *
- * Guards the two web bug classes (publicsummerengine cf17134f + contract.ts
- * `isFailureSignal`):
+ * Guards the two bug classes the web platform's tool layer once had:
  *   - a failure `terminalState` (anything other than applied/no_op) is a failure
- *     even when results[] is absent — the cf17134f "no-results envelope looked
+ *     even when results[] is absent — the "no-results envelope looked
  *     applied" masking. The poll loop surfaces timed_out/etc. here.
  *   - an explicit ok:false / status:"error" / failed op inside results[].
  *
@@ -37,9 +36,8 @@ export declare function getFailureReason(value: {
  */
 export declare function extractOpError(result: unknown): string | null;
 /**
- * The engine stamps `scenePersistence.persisted` on every scene-targeted batch
- * (ops_executor.cpp: scene_persistence["persisted"] =
- * explicit_scene_save_succeeded). It only means SaveScene returned OK, not
+ * The engine stamps `scenePersistence.persisted` on every scene-targeted batch.
+ * It only means SaveScene returned OK, not
  * that the file holds the change: a ReparentNode subtree whose owners the
  * engine cleared, or a ConnectSignal made without CONNECT_PERSIST, is missing
  * from a file whose save "persisted". Rename it to
@@ -50,7 +48,7 @@ export declare function extractOpError(result: unknown): string | null;
 export declare function honestSceneReceipt<T>(result: T): T;
 /**
  * An older engine answers an unknown op with a per-op "unknown op: <Kind>"
- * (ops_executor.cpp fallthrough). Amend the envelope's error so the model gets
+ * Amend the envelope's error so the model gets
  * the upgrade path instead of retrying, and stamp `failure_reason:
  * "engine_lacks_op"` (+ `op`) so the result is detectable the same way as the
  * capability pre-flight's MissingOpResult: programmatic callers read the

package/dist/core/capabilities/engine-receipt.js

@@ -9,7 +9,7 @@ export function getFailureReason(value) {
             ? value.failure_reason
             : undefined;
 }
-// 0.5.34 Block E contract (publicsummerengine src/lib/tools/contract.ts §0.1).
+// Engine 0.5.34 receipt contract, shared with the web platform's tool layer.
 // The async lifecycle (async-op-lifecycle.ts pollOpToTerminal) merges
 // terminalState/errorClass onto the apply dict it returns. ONLY these two are
 // "applied something / applied nothing-on-purpose" — every other terminal state
@@ -33,10 +33,9 @@ const TERMINAL_STATE_MESSAGES = {
  * Decide whether an engine result envelope represents a FAILURE, and if so
  * return a model-visible message. Returns null only for genuine success.
  *
- * Guards the two web bug classes (publicsummerengine cf17134f + contract.ts
- * `isFailureSignal`):
+ * Guards the two bug classes the web platform's tool layer once had:
  *   - a failure `terminalState` (anything other than applied/no_op) is a failure
- *     even when results[] is absent — the cf17134f "no-results envelope looked
+ *     even when results[] is absent — the "no-results envelope looked
  *     applied" masking. The poll loop surfaces timed_out/etc. here.
  *   - an explicit ok:false / status:"error" / failed op inside results[].
  *
@@ -97,9 +96,8 @@ export function extractOpError(result) {
     return null;
 }
 /**
- * The engine stamps `scenePersistence.persisted` on every scene-targeted batch
- * (ops_executor.cpp: scene_persistence["persisted"] =
- * explicit_scene_save_succeeded). It only means SaveScene returned OK, not
+ * The engine stamps `scenePersistence.persisted` on every scene-targeted batch.
+ * It only means SaveScene returned OK, not
  * that the file holds the change: a ReparentNode subtree whose owners the
  * engine cleared, or a ConnectSignal made without CONNECT_PERSIST, is missing
  * from a file whose save "persisted". Rename it to
@@ -123,11 +121,11 @@ export function honestSceneReceipt(result) {
     return (out ?? result);
 }
 /** The per-op text an older engine answers for a Kind its dispatch ladder does
- *  not know (ops_executor.cpp fallthrough: `unknown op: <Kind>`). */
+ *  not know (`unknown op: <Kind>`). */
 const UNKNOWN_OP_PATTERN = /unknown op/i;
 /**
  * An older engine answers an unknown op with a per-op "unknown op: <Kind>"
- * (ops_executor.cpp fallthrough). Amend the envelope's error so the model gets
+ * Amend the envelope's error so the model gets
  * the upgrade path instead of retrying, and stamp `failure_reason:
  * "engine_lacks_op"` (+ `op`) so the result is detectable the same way as the
  * capability pre-flight's MissingOpResult: programmatic callers read the

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

@@ -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 = {

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/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

@@ -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 = {

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