summer-engine 3.3.0 → 3.4.1

package/dist/core/capabilities/capture-gameplay.js

@@ -0,0 +1,283 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { platform } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { findEngineBinary } from "../engine-install.js";
+import { runEngine } from "./engine-run.js";
+import { resolveExportProject } from "./export-game.js";
+import { BuildToolError } from "./summer-bundle.js";
+const defaultDependencies = {
+    findBinary: () => findEngineBinary(platform()),
+    run: runEngine,
+    now: () => new Date(),
+};
+const DEFAULT_RESOLUTION = "1920x1080";
+const MAX_FRAMES = 10;
+/** The engine clamps --summer-verify-max to 240 (main.cpp SUMMER_VERIFY_MAX_SECONDS). */
+const ENGINE_MAX_SECONDS = 240;
+const IMPORT_TIMEOUT_MS = 5 * 60_000;
+const PROBE_FILE = "capture_probe.gd";
+function invalid(message, recovery) {
+    return new BuildToolError("capture_args_invalid", message, recovery);
+}
+function parseResolution(value) {
+    const text = value?.trim() || DEFAULT_RESOLUTION;
+    const match = /^(\d{2,5})x(\d{2,5})$/i.exec(text);
+    if (!match)
+        throw invalid(`resolution "${text}" is not WIDTHxHEIGHT.`, 'Recovery: pass e.g. "1920x1080" (landscape) or "1080x1920" (portrait).');
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    if (width < 64 || height < 64 || width > 7680 || height > 7680) {
+        throw invalid(`resolution ${text} is out of range.`, "Recovery: use 64 to 7680 pixels per side.");
+    }
+    return { width, height, text: `${width}x${height}` };
+}
+function boundedNumber(value, fallback, min, max, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < min || value > max) {
+        throw invalid(`${name} must be between ${min} and ${max}.`, `Recovery: pass ${name} in that range, or omit it.`);
+    }
+    return value;
+}
+function checkScene(project, scene) {
+    const value = scene?.trim();
+    if (!value)
+        return undefined;
+    if (value.startsWith("uid://"))
+        return value;
+    if (!value.startsWith("res://") || !/\.(tscn|scn)$/i.test(value)) {
+        throw invalid(`scene "${value}" is not a res:// scene path.`, 'Recovery: pass a scene like "res://main.tscn", or omit scene to start the main scene.');
+    }
+    if (!existsSync(join(project, value.slice("res://".length)))) {
+        throw invalid(`${value} does not exist in ${project}.`, "Recovery: pass a scene file that exists, or omit scene to start the main scene.");
+    }
+    return value;
+}
+function stamp(date) {
+    return date.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z").replace("T", "-");
+}
+/** <project>/.summer/captures/, ignored by the editor and by git (like .summer/exports). */
+async function capturesDir(project) {
+    const dir = join(project, ".summer", "captures");
+    await mkdir(dir, { recursive: true });
+    for (const [name, body] of [
+        [".gdignore", ""],
+        [".gitignore", "*\n"],
+    ]) {
+        const file = join(dir, name);
+        if (!existsSync(file))
+            await writeFile(file, body);
+    }
+    return dir;
+}
+/** Width and height from a PNG's IHDR chunk, or null when the file is not a PNG. */
+export function pngSize(bytes) {
+    if (bytes.length < 24 || bytes.readUInt32BE(0) !== 0x89504e47 || bytes.toString("ascii", 12, 16) !== "IHDR")
+        return null;
+    return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+/**
+ * The stock probe. Self-contained (extends Node, no base class to copy into the
+ * project); follows the verify-instance contract of assets/autopilot/probe_base.gd:
+ * the engine sets summer_out_dir and summer_max_seconds before _ready(), the
+ * first frames are empty until the scene has drawn twice, results.json is
+ * always written.
+ */
+export function captureProbeSource(frames, waitSeconds, intervalSeconds) {
+    return `# Written by summer_capture_gameplay. Safe to delete.
+# Fully typed: projects that treat GDScript warnings as errors must still load it.
+extends Node
+
+var summer_out_dir: String = ""
+var summer_max_seconds: int = 20
+
+const FRAMES: int = ${frames}
+const WAIT_SECONDS: float = ${waitSeconds.toFixed(3)}
+const INTERVAL_SECONDS: float = ${intervalSeconds.toFixed(3)}
+
+var _shots: Array = []
+var _warnings: Array = []
+var _start_ms: int = 0
+var _done: bool = false
+
+func _ready() -> void:
+\tprocess_mode = Node.PROCESS_MODE_ALWAYS
+\t_start_ms = Time.get_ticks_msec()
+\tget_tree().create_timer(float(summer_max_seconds), true).timeout.connect(_on_deadline)
+\t_run.call_deferred()
+
+func _on_deadline() -> void:
+\t_finish(false)
+
+func _run() -> void:
+\t# The viewport holds no scene until two frames have been drawn.
+\tvar guard: int = 0
+\twhile Engine.get_frames_drawn() < 2 and guard < 600:
+\t\tguard += 1
+\t\tawait get_tree().process_frame
+\tif DisplayServer.get_name() == "headless":
+\t\t_warnings.append("No renderer (headless): no frame can be captured.")
+\t\t_finish(true)
+\t\treturn
+\tawait get_tree().create_timer(WAIT_SECONDS, true).timeout
+\tfor i: int in range(FRAMES):
+\t\tif i > 0:
+\t\t\tawait get_tree().create_timer(INTERVAL_SECONDS, true).timeout
+\t\tawait RenderingServer.frame_post_draw
+\t\tvar img: Image = get_viewport().get_texture().get_image()
+\t\tvar file_name: String = "shot-%02d.png" % (i + 1)
+\t\tif img == null:
+\t\t\t_warnings.append("%s: the viewport returned no image." % file_name)
+\t\t\tcontinue
+\t\tif img.save_png(summer_out_dir.path_join(file_name)) == OK:
+\t\t\t_shots.append({"file": file_name, "width": img.get_width(), "height": img.get_height()})
+\t\telse:
+\t\t\t_warnings.append("%s: could not write the PNG." % file_name)
+\t_finish(true)
+
+func _errors() -> Array:
+\tvar errors: Array = []
+\tvar path: String = summer_out_dir.path_join("errors.log")
+\tif FileAccess.file_exists(path):
+\t\tvar f: FileAccess = FileAccess.open(path, FileAccess.READ)
+\t\tif f != null:
+\t\t\twhile not f.eof_reached():
+\t\t\t\tvar line: String = f.get_line()
+\t\t\t\tif line.strip_edges() != "":
+\t\t\t\t\terrors.append(line)
+\treturn errors
+
+func _finish(finished: bool) -> void:
+\tif _done:
+\t\treturn
+\t_done = true
+\tvar out: Dictionary = {"shots": _shots, "frame_warnings": _warnings, "errors_seen": _errors(), "duration_ms": Time.get_ticks_msec() - _start_ms, "finished": finished}
+\tvar f: FileAccess = FileAccess.open(summer_out_dir.path_join("results.json"), FileAccess.WRITE)
+\tif f != null:
+\t\tf.store_string(JSON.stringify(out, "  "))
+\t\tf.close()
+\tget_tree().quit()
+`;
+}
+function outputTail(output) {
+    return output.trim().split("\n").slice(-30).join("\n");
+}
+export async function captureGameplay(input, overrides = {}) {
+    const deps = { ...defaultDependencies, ...overrides };
+    const project = resolveExportProject(input.project);
+    const resolution = parseResolution(input.resolution);
+    const frames = Math.round(boundedNumber(input.frames, 1, 1, MAX_FRAMES, "frames"));
+    const waitSeconds = boundedNumber(input.waitSeconds, 3, 0, 120, "waitSeconds");
+    const intervalSeconds = boundedNumber(input.intervalSeconds, 1, 0.1, 60, "intervalSeconds");
+    const scene = checkScene(project, input.scene);
+    const started = deps.now();
+    const binary = deps.findBinary();
+    if (!binary) {
+        throw new BuildToolError("engine_not_installed", "Summer Engine is not installed on this machine.", 'Recovery: run "summer install", or set SUMMER_BIN to the engine executable, then capture again.');
+    }
+    let out;
+    if (input.out?.trim()) {
+        out = isAbsolute(input.out) ? input.out : resolve(project, input.out);
+    }
+    else {
+        out = join(await capturesDir(project), stamp(started));
+    }
+    await mkdir(out, { recursive: true });
+    await rm(join(out, "results.json"), { force: true });
+    // A never-opened checkout has no .godot/ caches; the game would boot into
+    // missing-import errors. Build them once, headless (same as tests/autopilot).
+    let imported = false;
+    if (!existsSync(join(project, ".godot"))) {
+        const run = await deps.run(binary, ["--headless", "--import", "--disable-crash-handler", "--path", project], IMPORT_TIMEOUT_MS);
+        if (run.timedOut || !existsSync(join(project, ".godot"))) {
+            throw new BuildToolError("import_failed", "Summer Engine could not import the project's assets before the capture.", "Recovery: open the project once in Summer Engine (or run the engine with --headless --import), then capture again.", undefined, { output: outputTail(run.output) });
+        }
+        imported = true;
+    }
+    const probe = join(out, PROBE_FILE);
+    await writeFile(probe, captureProbeSource(frames, waitSeconds, intervalSeconds));
+    const maxSeconds = Math.min(ENGINE_MAX_SECONDS, Math.ceil(waitSeconds + (frames - 1) * intervalSeconds + 30));
+    const args = [
+        "--disable-crash-handler",
+        // No local HTTP API or ~/.summer discovery files for this throwaway run.
+        "--summer-no-api",
+        "--path",
+        project,
+        "--resolution",
+        resolution.text,
+        ...(scene ? ["--scene", scene] : []),
+        "--summer-verify",
+        probe,
+        "--summer-verify-out",
+        out,
+        "--summer-verify-max",
+        String(maxSeconds),
+    ];
+    let run;
+    try {
+        run = await deps.run(binary, args, (maxSeconds + 60) * 1000);
+    }
+    catch (error) {
+        throw new BuildToolError("engine_launch_failed", `Summer Engine could not start: ${error instanceof Error ? error.message : String(error)}.`, 'Recovery: run "summer doctor" and check the engine install.');
+    }
+    finally {
+        await rm(probe, { force: true });
+    }
+    const resultsPath = join(out, "results.json");
+    const results = existsSync(resultsPath)
+        ? (() => {
+            try {
+                return JSON.parse(readFileSync(resultsPath, "utf8"));
+            }
+            catch {
+                return null;
+            }
+        })()
+        : null;
+    const engineErrors = (results?.errors_seen ?? []).filter((line) => !line.startsWith("WARNING|"));
+    if (!results || results.failure_reason || !results.shots?.length) {
+        const reason = results?.failure_reason
+            ? `${results.failure_reason}: ${results.error ?? ""}`.trim()
+            : results
+                ? "the game ran but no frame was saved"
+                : "the verify instance wrote no results";
+        throw new BuildToolError("capture_failed", `No gameplay frame was captured (${reason}).`, results?.failure_reason === "no_main_scene"
+            ? "Recovery: set a main scene in Project Settings, or pass scene."
+            : "Recovery: read the engine errors below, fix what they name, and capture again. An engine older than the verify instance (before 0.5.55) cannot capture: update Summer Engine.", undefined, {
+            ...(engineErrors.length ? { engineErrors: engineErrors.slice(0, 10) } : {}),
+            ...(results?.frame_warnings?.length ? { frameWarnings: results.frame_warnings } : {}),
+            output: outputTail(run.output),
+        });
+    }
+    const captured = [];
+    for (const shot of results.shots) {
+        const path = join(out, shot.file);
+        if (!existsSync(path))
+            continue;
+        const size = pngSize(await readFile(path)) ?? { width: shot.width, height: shot.height };
+        captured.push({ path, ...size });
+    }
+    const warnings = [...(results.frame_warnings ?? [])];
+    if (results.finished === false)
+        warnings.push("The game hit its time limit before every frame was saved.");
+    const off = captured.filter((frame) => frame.width !== resolution.width || frame.height !== resolution.height);
+    if (off.length) {
+        warnings.push(`Frames are ${off[0].width}x${off[0].height}, not ${resolution.text}: the project's stretch settings (Project Settings > Display > Window) set the render size. Store screenshots need 1920x1080 or 1080x1920; crop or change the stretch mode.`);
+    }
+    if (engineErrors.length)
+        warnings.push(`The engine logged ${engineErrors.length} error(s) during the run; check the frames show the game as expected: ${engineErrors.slice(0, 3).join(" / ")}`);
+    return {
+        ok: true,
+        project,
+        scene: scene ?? "main scene",
+        resolution: resolution.text,
+        frames: captured,
+        out,
+        engine: binary,
+        imported,
+        durationMs: deps.now().getTime() - started.getTime(),
+        ...(warnings.length ? { warnings } : {}),
+        next: "Look at each frame before using it. For the store: upload with summer_upload_image_begin/complete and set them as desktop.screenshots or mobile.screenshots (summer_store_set_art). The game's own HUD may show; add no captions, logos or overlays.",
+    };
+}

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/creator.js

@@ -148,7 +148,7 @@ function assertUploadUrl(value) {
     }
     const local = url.hostname === "localhost" ||
         url.hostname === "127.0.0.1" ||
-        url.hostname === "::1";
+        url.hostname === "[::1]";
     if (url.username ||
         url.password ||
         (url.protocol !== "https:" && !(local && url.protocol === "http:"))) {

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

@@ -1,3 +1,4 @@
+import { type StoreAccessResult } from "../hosted-mcp.js";
 import { type ProjectMemorySummary } from "../../project-memory/project-memory.js";
 export type DoctorStatus = "ok" | "warning" | "fail";
 export interface DoctorCheck {
@@ -22,7 +23,14 @@ interface DoctorOptions {
 }
 export declare function runDoctor(options?: DoctorOptions): Promise<DoctorResult>;
 export declare function checkLogin(): Promise<DoctorCheck>;
-export declare function checkEngineInstall(): DoctorCheck;
+/**
+ * Store access: with a store sign-in ("summer login --store"), ask the store
+ * for the creator's games through the hosted Summer Engine MCP, so a refusal
+ * shows here with its reason instead of on the first publishing call.
+ * A warning at worst: only publishing needs the store.
+ */
+export declare function checkStoreSignIn(probe?: () => Promise<StoreAccessResult>, signedIn?: () => Promise<boolean>): Promise<DoctorCheck>;
+export declare function checkEngineInstall(readVersion?: (binary: string) => string | null): DoctorCheck;
 /** The one-line Project Memory verdict: Markdown counts plus the template pin
  *  (`.summer/project.json` is memory too — the first fact a fresh agent
  *  needs). Exported for tests. */

package/dist/core/capabilities/doctor.js

@@ -4,8 +4,11 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import { getAuthToken, getUserInfo } from "../auth.js";
 import { ENGINE_BIN_ENV, ENGINE_BINARY_ENV, findEngineBinary } from "../engine-install.js";
 import { checkEngineHealth, getApiPort, getApiToken } from "../engine.js";
+import { isVersionAtLeast } from "../launch-posture.js";
+import { EXPORT_MIN_ENGINE_VERSION, installedEngineVersion } from "./export-engine-version.js";
 import { c, pad, sym, tildeify } from "../format.js";
 import { getMcpLogPath } from "../mcp-log.js";
+import { checkStoreAccess, hasStoreSignIn } from "../hosted-mcp.js";
 import { formatProjectPin, getProjectMemorySummary, } from "../../project-memory/project-memory.js";
 import { buildCliVersionCheck, buildSkillsVersionCheck, defaultSkillMarkerCandidates, detectRecordedInstall, fetchLatestRegistryVersion, } from "../../installer/version-check.js";
 import { TOOLKIT_VERSION as version } from "../version.js";
@@ -27,6 +30,7 @@ export async function runDoctor(options = {}) {
     checks.push(await checkCliVersionCurrent());
     checks.push(await checkSkillsVersion());
     checks.push(await checkLogin());
+    checks.push(await checkStoreSignIn());
     checks.push(checkEngineInstall());
     checks.push(await checkLocalApi());
     checks.push(await checkProjectMemory());
@@ -120,17 +124,56 @@ export async function checkLogin() {
         message: user ? user.email : "signed in",
     };
 }
-export function checkEngineInstall() {
+/**
+ * Store access: with a store sign-in ("summer login --store"), ask the store
+ * for the creator's games through the hosted Summer Engine MCP, so a refusal
+ * shows here with its reason instead of on the first publishing call.
+ * A warning at worst: only publishing needs the store.
+ */
+export async function checkStoreSignIn(probe = () => checkStoreAccess(), signedIn = hasStoreSignIn) {
+    const base = { id: "store-access", label: "Store" };
+    if (!(await signedIn())) {
+        return { ...base, status: "ok", message: "no store sign-in (only publishing needs it: summer login --store)" };
+    }
+    const result = await probe();
+    if (result.status === "ok") {
+        return { ...base, status: "ok", message: `the store accepts this sign-in${result.games === null ? "" : ` (${result.games} ${result.games === 1 ? "game" : "games"})`}` };
+    }
+    if (result.status === "not_signed_in") {
+        return { ...base, status: "warning", message: `${result.message} (run: summer login --store)` };
+    }
+    if (result.status === "unreachable") {
+        return { ...base, status: "warning", message: `could not reach the store: ${result.message}`, details: { ...result } };
+    }
+    return {
+        ...base,
+        status: "warning",
+        message: `the store refused this sign-in${result.code ? ` (${result.code})` : ""}: ${result.message}${result.requestId ? ` [requestId ${result.requestId}]` : ""}`,
+        details: { ...result },
+    };
+}
+export function checkEngineInstall(readVersion = installedEngineVersion) {
     const binary = findEngineBinary();
     if (binary) {
         // Shorten /Applications/Summer.app/Contents/MacOS/Summer -> /Applications/Summer.app
-        const display = binary.replace(/\/Contents\/MacOS\/Summer$/, "");
+        const display = tildeify(binary.replace(/\/Contents\/MacOS\/Summer$/, ""));
+        const version = readVersion(binary);
+        const details = { path: binary, version, minimumExportVersion: EXPORT_MIN_ENGINE_VERSION };
+        if (isVersionAtLeast(version, EXPORT_MIN_ENGINE_VERSION) === false) {
+            return {
+                id: "engine-install",
+                label: "Engine",
+                status: "warning",
+                message: `${display} is ${version}; summer.games exports need ${EXPORT_MIN_ENGINE_VERSION}+ (update: summer install --yes)`,
+                details,
+            };
+        }
         return {
             id: "engine-install",
             label: "Engine",
             status: "ok",
-            message: tildeify(display),
-            details: { path: binary },
+            message: version ? `${display} (${version})` : display,
+            details,
         };
     }
     return {

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/engine-run.d.ts

@@ -3,6 +3,10 @@ export interface EngineRun {
     signal: NodeJS.Signals | null;
     timedOut: boolean;
     output: string;
+    /** The engine's "ERROR:" / "SCRIPT ERROR:" lines from the whole run (the first 20), even when the tail lost them. */
+    errors?: string[];
 }
+/** "ERROR: ..." and "SCRIPT ERROR: ..." lines of engine output, without colour codes or the "at:" lines. */
+export declare function engineErrorLines(output: string, limit?: number): string[];
 /** Spawn the engine (argv only, no shell), keep the last output, kill on timeout. */
 export declare function runEngine(binary: string, args: string[], timeoutMs: number): Promise<EngineRun>;

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

@@ -2,17 +2,44 @@ import { spawn as nodeSpawn } from "node:child_process";
 /** One headless engine process: argv only (no shell), the last output kept, killed on timeout. */
 const OUTPUT_TAIL_BYTES = 8 * 1024;
 const KILL_GRACE_MS = 5_000;
+const MAX_ERROR_LINES = 20;
+const MAX_ERROR_LINE_CHARS = 600;
+const ANSI = /\u001b\[[0-9;]*m/g;
+/** "ERROR: ..." and "SCRIPT ERROR: ..." lines of engine output, without colour codes or the "at:" lines. */
+export function engineErrorLines(output, limit = MAX_ERROR_LINES) {
+    const lines = [];
+    for (const raw of output.split(/\r?\n/)) {
+        const line = raw.replace(ANSI, "").trim();
+        if (!/^(SCRIPT )?ERROR:/.test(line))
+            continue;
+        if (lines.length >= limit)
+            break;
+        lines.push(line.slice(0, MAX_ERROR_LINE_CHARS));
+    }
+    return lines;
+}
 /** Spawn the engine (argv only, no shell), keep the last output, kill on timeout. */
 export function runEngine(binary, args, timeoutMs) {
     return new Promise((resolvePromise, reject) => {
         const child = nodeSpawn(binary, args, { stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
         let output = "";
         let timedOut = false;
-        const keep = (chunk) => {
-            output = (output + chunk.toString("utf8")).slice(-OUTPUT_TAIL_BYTES);
+        // Error lines are collected per stream as they arrive, so a long run cannot push them out of the tail.
+        const errors = [];
+        const partial = { stdout: "", stderr: "" };
+        const collect = (text) => {
+            if (errors.length < MAX_ERROR_LINES)
+                errors.push(...engineErrorLines(text, MAX_ERROR_LINES - errors.length));
+        };
+        const keep = (stream) => (chunk) => {
+            const text = chunk.toString("utf8");
+            output = (output + text).slice(-OUTPUT_TAIL_BYTES);
+            const lines = (partial[stream] + text).split("\n");
+            partial[stream] = (lines.pop() ?? "").slice(-OUTPUT_TAIL_BYTES);
+            collect(lines.join("\n"));
         };
-        child.stdout?.on("data", keep);
-        child.stderr?.on("data", keep);
+        child.stdout?.on("data", keep("stdout"));
+        child.stderr?.on("data", keep("stderr"));
         let killTimer;
         const timer = setTimeout(() => {
             timedOut = true;
@@ -27,7 +54,8 @@ export function runEngine(binary, args, timeoutMs) {
         child.on("close", (code, signal) => {
             clearTimeout(timer);
             clearTimeout(killTimer);
-            resolvePromise({ code, signal, timedOut, output });
+            collect(`${partial.stdout}\n${partial.stderr}`);
+            resolvePromise({ code, signal, timedOut, output, errors });
         });
     });
 }

package/dist/core/capabilities/export-engine-version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The oldest Summer Engine that exports what the Summer Games store takes.
+ * 0.6.0 has no "summer.games" export platform: it cannot read the presets
+ * summer_export_game writes and fails after a full engine start.
+ */
+export declare const EXPORT_MIN_ENGINE_VERSION = "0.7.0";
+export declare 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 declare function installedEngineVersion(binary: string): string | null;
+/**
+ * Refuse an engine older than EXPORT_MIN_ENGINE_VERSION, before anything is
+ * written to the project. An unreadable version passes: the engine's own
+ * export output then names what is wrong.
+ */
+export declare function assertExportEngine(binary: string, version: string | null): void;

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

@@ -0,0 +1,24 @@
+import { platform } from "node:os";
+import { isVersionAtLeast, readInstalledEngineVersion } from "../launch-posture.js";
+import { BuildToolError } from "./summer-bundle.js";
+/**
+ * The oldest Summer Engine that exports what the Summer Games store takes.
+ * 0.6.0 has no "summer.games" export platform: it cannot read the presets
+ * summer_export_game writes and fails after a full engine start.
+ */
+export const EXPORT_MIN_ENGINE_VERSION = "0.7.0";
+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) {
+    return readInstalledEngineVersion(binary, platform());
+}
+/**
+ * Refuse an engine older than EXPORT_MIN_ENGINE_VERSION, before anything is
+ * written to the project. An unreadable version passes: the engine's own
+ * export output then names what is wrong.
+ */
+export function assertExportEngine(binary, version) {
+    if (isVersionAtLeast(version, EXPORT_MIN_ENGINE_VERSION) !== false)
+        return;
+    throw new BuildToolError("engine_too_old", `Summer Engine ${version} is installed; summer.games exports need Summer Engine ${EXPORT_MIN_ENGINE_VERSION} or newer.`, `Recovery: update Summer Engine to ${EXPORT_MIN_ENGINE_VERSION}+: ${ENGINE_UPDATE_HOW}, then export again. Nothing was written to the project.`, undefined, { engine: binary, engineVersion: version, minimumEngineVersion: EXPORT_MIN_ENGINE_VERSION });
+}