summer-engine 3.4.0 → 3.5.0

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

@@ -1,4 +1,5 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, openSync, readdirSync, readFileSync, readSync, closeSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { platform } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
@@ -15,8 +16,22 @@ 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;
+/** Offscreen runs draw uncapped (~130 fps) while the verify backstop counts 60 frames a second; cap the frame rate so seconds stay seconds. */
+const CAPTURE_MAX_FPS = 60;
+/** Files the engine imports; a new or changed one means the .godot/ caches are stale. */
+const IMPORTED_EXTENSIONS = new Set([
+    ".png", ".jpg", ".jpeg", ".webp", ".svg", ".tga", ".bmp", ".exr", ".hdr", ".ktx", ".dds",
+    ".glb", ".gltf", ".fbx", ".obj", ".blend", ".dae",
+    ".wav", ".ogg", ".mp3",
+    ".ttf", ".otf", ".woff", ".woff2", ".fnt", ".csv",
+]);
+const SKIPPED_DIRS = new Set([".godot", ".git", ".summer", ".import", "node_modules", "build", "exports"]);
+const MAX_SCANNED_FILES = 50_000;
 const IMPORT_TIMEOUT_MS = 5 * 60_000;
 const PROBE_FILE = "capture_probe.gd";
+const MAX_STEPS = 50;
+const MAX_ARGS = 32;
+const STEP_KINDS = ["press", "key", "action", "click", "drag", "wait", "shot"];
 function invalid(message, recovery) {
     return new BuildToolError("capture_args_invalid", message, recovery);
 }
@@ -54,6 +69,169 @@ function checkScene(project, scene) {
     }
     return value;
 }
+function checkArgs(args) {
+    if (args === undefined)
+        return [];
+    if (!Array.isArray(args) || args.length > MAX_ARGS || args.some((arg) => typeof arg !== "string" || arg.length > 200 || /[\u0000\n\r]/.test(arg))) {
+        throw invalid(`args must be at most ${MAX_ARGS} single-line strings.`, 'Recovery: pass the game\'s own flags, e.g. ["--autostart", "--solo"].');
+    }
+    return args;
+}
+function point(value, where) {
+    if (!Array.isArray(value) || value.length !== 2 || !value.every((n) => typeof n === "number" && Number.isFinite(n) && n >= 0 && n <= 7680)) {
+        throw invalid(`${where} must be [x, y] in frame pixels.`, "Recovery: pass two numbers from 0 to 7680, e.g. [960, 540] for the middle of a 1920x1080 frame.");
+    }
+    return [value[0], value[1]];
+}
+/** Validate the steps and turn them into the probe's one shape. */
+export function probeSteps(steps) {
+    if (steps === undefined)
+        return [];
+    if (!Array.isArray(steps) || steps.length > MAX_STEPS) {
+        throw invalid(`steps must be a list of at most ${MAX_STEPS} steps.`, 'Recovery: pass e.g. [{"press":"Play"},{"wait":2000},{"shot":true}].');
+    }
+    const out = steps.map((raw, index) => {
+        const where = `steps[${index}]`;
+        const step = (raw && typeof raw === "object" ? raw : {});
+        const kinds = STEP_KINDS.filter((kind) => kind in step);
+        if (kinds.length !== 1) {
+            throw invalid(`${where} must have exactly one of ${STEP_KINDS.join(", ")}.`, 'Recovery: one step per object, e.g. {"press":"Play"} or {"key":"Space"}.');
+        }
+        const hold = boundedNumber(step.holdMs, 100, 0, 10_000, `${where}.holdMs`);
+        const name = (key) => {
+            const value = step[key];
+            if (typeof value !== "string" || !value.trim() || value.length > 100) {
+                throw invalid(`${where}.${key} must be a non-empty name.`, 'Recovery: e.g. {"press":"Play"}, {"key":"Space"}, {"action":"jump"}.');
+            }
+            return value.trim();
+        };
+        switch (kinds[0]) {
+            case "press":
+                return { type: "press", text: name("press"), timeout: boundedNumber(step.timeoutSeconds, 10, 0, 60, `${where}.timeoutSeconds`) };
+            case "key":
+                return { type: "key", text: name("key"), hold_ms: hold };
+            case "action":
+                return { type: "action", text: name("action"), hold_ms: hold };
+            case "click":
+                return { type: "click", at: point(step.click, `${where}.click`) };
+            case "drag": {
+                const drag = (step.drag && typeof step.drag === "object" ? step.drag : {});
+                return {
+                    type: "drag",
+                    at: point(drag.from, `${where}.drag.from`),
+                    to: point(drag.to, `${where}.drag.to`),
+                    ms: boundedNumber(drag.ms, 300, 0, 10_000, `${where}.drag.ms`),
+                };
+            }
+            case "wait":
+                return { type: "wait", ms: boundedNumber(step.wait, 0, 0, 60_000, `${where}.wait`) };
+            default:
+                if (step.shot !== true)
+                    throw invalid(`${where}.shot must be true.`, 'Recovery: {"shot":true} saves a frame at that point.');
+                return { type: "shot" };
+        }
+    });
+    if (out.filter((step) => step.type === "shot").length > MAX_FRAMES) {
+        throw invalid(`at most ${MAX_FRAMES} shot steps.`, "Recovery: capture again for more frames.");
+    }
+    return out;
+}
+/** Seconds the steps can take at most (press waits for its button). */
+function stepSeconds(steps) {
+    return steps.reduce((sum, step) => sum + (step.timeout ?? 0) + ((step.hold_ms ?? 0) + (step.ms ?? 0)) / 1000 + 0.5, 0);
+}
+/**
+ * Why one imported file needs importing again, or null when its import is
+ * current. Like the editor: the .import sidecar names the cached result, whose
+ * .md5 records the source's hash; the hash is only computed when the source is
+ * newer than that record.
+ */
+function staleImport(project, path) {
+    const relative = path.slice(project.length + 1);
+    let sidecar;
+    try {
+        sidecar = readFileSync(`${path}.import`, "utf8");
+    }
+    catch {
+        return `${relative} has not been imported`;
+    }
+    const dest = /^path(?:\.[a-z0-9_]+)?="res:\/\/\.godot\/imported\/([^"]+)"/m.exec(sidecar)?.[1];
+    // importer "keep" or "skip": nothing is cached.
+    if (!dest)
+        return null;
+    const record = join(project, ".godot", "imported", dest.replace(/\.[^.]+$/, ".md5"));
+    let recorded;
+    try {
+        recorded = { text: readFileSync(record, "utf8"), mtimeMs: statSync(record).mtimeMs };
+    }
+    catch {
+        return `${relative} has no import cache`;
+    }
+    if (statSync(path).mtimeMs <= recorded.mtimeMs)
+        return null;
+    const sourceMd5 = /source_md5="([0-9a-f]+)"/.exec(recorded.text)?.[1];
+    return sourceMd5 === createHash("md5").update(readFileSync(path)).digest("hex") ? null : `${relative} changed after the last import`;
+}
+function isLfsPointer(path) {
+    try {
+        if (statSync(path).size > 1024)
+            return false;
+        const fd = openSync(path, "r");
+        const buffer = Buffer.alloc(64);
+        readSync(fd, buffer, 0, 64, 0);
+        closeSync(fd);
+        return buffer.toString("utf8").startsWith("version https://git-lfs");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether the project's import caches are stale: an imported file (texture,
+ * model, sound, font) that has no .import sidecar or cache yet, or whose
+ * content changed since it was imported (a pull, or LFS files fetched after
+ * the first import). Also names files that are still Git LFS pointers, which no
+ * import can fix.
+ */
+export function importState(project) {
+    if (!existsSync(join(project, ".godot")))
+        return { needed: true, reason: "the project was never imported", lfsPointers: [] };
+    const lfsPointers = [];
+    let reason;
+    let scanned = 0;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (scanned >= MAX_SCANNED_FILES)
+                return;
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIPPED_DIRS.has(entry.name) && !existsSync(join(path, ".gdignore")))
+                    walk(path);
+                continue;
+            }
+            const dot = entry.name.lastIndexOf(".");
+            if (!entry.isFile() || dot < 0 || !IMPORTED_EXTENSIONS.has(entry.name.slice(dot).toLowerCase()))
+                continue;
+            scanned++;
+            if (isLfsPointer(path)) {
+                if (lfsPointers.length < 10)
+                    lfsPointers.push(path.slice(project.length + 1));
+                continue;
+            }
+            if (!reason)
+                reason = staleImport(project, path) ?? undefined;
+        }
+    };
+    walk(project);
+    return { needed: reason !== undefined, ...(reason ? { reason } : {}), lfsPointers };
+}
 function stamp(date) {
     return date.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z").replace("T", "-");
 }
@@ -77,14 +255,42 @@ export function pngSize(bytes) {
         return null;
     return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
 }
+/** A GDScript string literal (JSON escapes are valid GDScript escapes). */
+const gdString = (text) => JSON.stringify(text);
+const gdFloat = (value) => (Number.isInteger(value) ? `${value}.0` : String(value));
+const gdVector = (point) => `Vector2(${gdFloat(point[0])}, ${gdFloat(point[1])})`;
+/** One step as a typed GDScript call: no Variant reads, so strict projects load it. */
+function stepLine(step, index) {
+    switch (step.type) {
+        case "press":
+            return `await _press(${index}, ${gdString(step.text)}, ${gdFloat(step.timeout)})`;
+        case "key":
+            return `await _key_named(${index}, ${gdString(step.text)}, ${step.hold_ms})`;
+        case "action":
+            return `await _action_named(${index}, ${gdString(step.text)}, ${step.hold_ms})`;
+        case "click":
+            return `await _click(${gdVector(step.at)})`;
+        case "drag":
+            return `await _drag(${gdVector(step.at)}, ${gdVector(step.to)}, ${step.ms})`;
+        case "wait":
+            return `await get_tree().create_timer(${gdFloat(step.ms / 1000)}, true).timeout`;
+        default:
+            return "await _shot()";
+    }
+}
 /**
  * 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.
+ * always written. The steps are generated as typed calls, and nothing reads a
+ * Variant, so projects that treat every GDScript warning as an error
+ * (untyped_declaration, unsafe_call_argument, unsafe_cast, integer_division)
+ * still load it.
  */
-export function captureProbeSource(frames, waitSeconds, intervalSeconds) {
+export function captureProbeSource(frames, waitSeconds, intervalSeconds, steps = []) {
+    const shotSteps = steps.some((step) => step.type === "shot");
+    const body = steps.length ? steps.map((step, index) => `\t${stepLine(step, index)}`).join("\n") : "\tpass";
     return `# Written by summer_capture_gameplay. Safe to delete.
 # Fully typed: projects that treat GDScript warnings as errors must still load it.
 extends Node
@@ -95,11 +301,13 @@ var summer_max_seconds: int = 20
 const FRAMES: int = ${frames}
 const WAIT_SECONDS: float = ${waitSeconds.toFixed(3)}
 const INTERVAL_SECONDS: float = ${intervalSeconds.toFixed(3)}
+const SHOT_STEPS: bool = ${shotSteps}
 
-var _shots: Array = []
-var _warnings: Array = []
+var _shots: Array[Dictionary] = []
+var _warnings: Array[String] = []
 var _start_ms: int = 0
 var _done: bool = false
+var _pressed_seen: bool = false
 
 func _ready() -> void:
 \tprocess_mode = Node.PROCESS_MODE_ALWAYS
@@ -121,23 +329,159 @@ func _run() -> void:
 \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)
+\tawait _steps()
+\tif not SHOT_STEPS:
+\t\tfor i: int in range(FRAMES):
+\t\t\tif i > 0:
+\t\t\t\tawait get_tree().create_timer(INTERVAL_SECONDS, true).timeout
+\t\t\tawait _shot()
 \t_finish(true)
 
-func _errors() -> Array:
-\tvar errors: Array = []
+func _steps() -> void:
+${body}
+
+func _shot() -> void:
+\tawait RenderingServer.frame_post_draw
+\tvar img: Image = get_viewport().get_texture().get_image()
+\tvar file_name: String = "shot-%02d.png" % (_shots.size() + 1)
+\tif img == null:
+\t\t_warnings.append("%s: the viewport returned no image." % file_name)
+\t\treturn
+\tif img.save_png(summer_out_dir.path_join(file_name)) == OK:
+\t\t_shots.append({"file": file_name, "width": img.get_width(), "height": img.get_height()})
+\telse:
+\t\t_warnings.append("%s: could not write the PNG." % file_name)
+
+# Clicks and drags take frame pixels: the saved PNG's own coordinates. The frame
+# is the root viewport; the final transform maps it to the window, where input
+# events land, so a stretched canvas still gets the click where the frame shows it.
+func _to_window(frame_pos: Vector2) -> Vector2:
+\treturn get_viewport().get_final_transform() * frame_pos
+
+func _mouse_button(frame_pos: Vector2, pressed: bool) -> void:
+\tvar ev: InputEventMouseButton = InputEventMouseButton.new()
+\tev.button_index = MOUSE_BUTTON_LEFT
+\tev.pressed = pressed
+\tev.button_mask = MOUSE_BUTTON_MASK_LEFT if pressed else 0
+\tev.position = _to_window(frame_pos)
+\tev.global_position = ev.position
+\tInput.parse_input_event(ev)
+
+func _mouse_move(frame_pos: Vector2, relative: Vector2, held: bool) -> void:
+\tvar ev: InputEventMouseMotion = InputEventMouseMotion.new()
+\tev.position = _to_window(frame_pos)
+\tev.global_position = ev.position
+\tev.relative = relative
+\tev.button_mask = MOUSE_BUTTON_MASK_LEFT if held else 0
+\tInput.parse_input_event(ev)
+
+func _click(frame_pos: Vector2) -> void:
+\t_mouse_move(frame_pos, Vector2.ZERO, false)
+\tawait get_tree().process_frame
+\t_mouse_button(frame_pos, true)
+\tawait get_tree().create_timer(0.05, true).timeout
+\t_mouse_button(frame_pos, false)
+\tawait get_tree().process_frame
+
+func _drag(from: Vector2, to: Vector2, ms: int) -> void:
+\t_mouse_move(from, Vector2.ZERO, false)
+\t_mouse_button(from, true)
+\tvar moves: int = maxi(2, roundi(ms / 16.0))
+\tvar last: Vector2 = from
+\tfor j: int in range(1, moves + 1):
+\t\tawait get_tree().create_timer(ms / 1000.0 / moves, true).timeout
+\t\tvar here: Vector2 = from.lerp(to, float(j) / moves)
+\t\t_mouse_move(here, here - last, true)
+\t\tlast = here
+\t_mouse_button(to, false)
+\tawait get_tree().process_frame
+
+func _key_named(index: int, key_name: String, hold_ms: int) -> void:
+\tvar keycode: Key = OS.find_keycode_from_string(key_name)
+\tif keycode == KEY_NONE:
+\t\t_warnings.append('steps[%d]: no key is named "%s" (use names like Space, Enter, Escape, A, Up).' % [index, key_name])
+\t\treturn
+\tvar ev: InputEventKey = InputEventKey.new()
+\tev.keycode = keycode
+\tev.physical_keycode = keycode
+\tev.pressed = true
+\tInput.parse_input_event(ev)
+\tawait get_tree().create_timer(hold_ms / 1000.0, true).timeout
+\tvar up: InputEventKey = InputEventKey.new()
+\tup.keycode = keycode
+\tup.physical_keycode = keycode
+\tup.pressed = false
+\tInput.parse_input_event(up)
+\tawait get_tree().process_frame
+
+func _action_named(index: int, action: String, hold_ms: int) -> void:
+\tif not InputMap.has_action(StringName(action)):
+\t\t_warnings.append('steps[%d]: the project has no input action "%s".' % [index, action])
+\t\treturn
+\tvar ev: InputEventAction = InputEventAction.new()
+\tev.action = StringName(action)
+\tev.pressed = true
+\tInput.parse_input_event(ev)
+\tawait get_tree().create_timer(hold_ms / 1000.0, true).timeout
+\tvar up: InputEventAction = InputEventAction.new()
+\tup.action = StringName(action)
+\tup.pressed = false
+\tInput.parse_input_event(up)
+\tawait get_tree().process_frame
+
+# A visible, enabled button: exact text, then node name, then partial text, then partial name.
+func _find_button(label: String) -> BaseButton:
+\tvar want: String = label.strip_edges().to_lower()
+\tvar best: BaseButton = null
+\tvar best_rank: int = 99
+\tfor node: Node in get_tree().root.find_children("*", "BaseButton", true, false):
+\t\tvar button: BaseButton = node as BaseButton
+\t\tif button == null or button.disabled or not button.is_visible_in_tree():
+\t\t\tcontinue
+\t\tvar text: String = ""
+\t\tvar as_button: Button = button as Button
+\t\tif as_button != null:
+\t\t\ttext = tr(as_button.text).strip_edges().to_lower()
+\t\tvar node_name: String = String(button.name).to_lower()
+\t\tvar rank: int = 99
+\t\tif text == want:
+\t\t\trank = 0
+\t\telif node_name == want:
+\t\t\trank = 1
+\t\telif text.contains(want):
+\t\t\trank = 2
+\t\telif node_name.contains(want):
+\t\t\trank = 3
+\t\tif rank < best_rank:
+\t\t\tbest = button
+\t\t\tbest_rank = rank
+\treturn best
+
+func _on_pressed_seen() -> void:
+\t_pressed_seen = true
+
+# Click the button's centre like a player; emit pressed when the click did not reach it.
+func _press(index: int, label: String, timeout: float) -> void:
+\tvar button: BaseButton = _find_button(label)
+\tvar deadline: int = Time.get_ticks_msec() + roundi(timeout * 1000.0)
+\twhile button == null and Time.get_ticks_msec() < deadline:
+\t\tawait get_tree().create_timer(0.1, true).timeout
+\t\tbutton = _find_button(label)
+\tif button == null:
+\t\t_warnings.append('steps[%d]: no visible, enabled button "%s" within %.1f s.' % [index, label, timeout])
+\t\treturn
+\t_pressed_seen = false
+\tbutton.pressed.connect(_on_pressed_seen, CONNECT_ONE_SHOT)
+\tvar centre: Vector2 = button.get_global_transform_with_canvas() * (button.size / 2.0)
+\tawait _click(centre)
+\tif not _pressed_seen and is_instance_valid(button):
+\t\tif button.pressed.is_connected(_on_pressed_seen):
+\t\t\tbutton.pressed.disconnect(_on_pressed_seen)
+\t\tbutton.pressed.emit()
+\tawait get_tree().process_frame
+
+func _errors() -> Array[String]:
+\tvar errors: Array[String] = []
 \tvar path: String = summer_out_dir.path_join("errors.log")
 \tif FileAccess.file_exists(path):
 \t\tvar f: FileAccess = FileAccess.open(path, FileAccess.READ)
@@ -171,6 +515,8 @@ export async function captureGameplay(input, overrides = {}) {
     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 userArgs = checkArgs(input.args);
+    const steps = probeSteps(input.steps);
     const started = deps.now();
     const binary = deps.findBinary();
     if (!binary) {
@@ -185,19 +531,25 @@ export async function captureGameplay(input, overrides = {}) {
     }
     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).
+    // A never-opened checkout has no .godot/ caches, and a pull (or LFS files
+    // fetched later) leaves them stale; the game would boot into missing or old
+    // imports. Import headless first (same as tests/autopilot).
     let imported = false;
-    if (!existsSync(join(project, ".godot"))) {
+    const importCheck = importState(project);
+    if (importCheck.needed) {
         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 importReason = importCheck.reason;
     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));
+    await writeFile(probe, captureProbeSource(frames, waitSeconds, intervalSeconds, steps));
+    // The engine's verify backstop counts frames, not seconds; with the frame rate
+    // capped at 60 twice the planned run leaves room for slow loads.
+    const plannedSeconds = waitSeconds + (frames - 1) * intervalSeconds + stepSeconds(steps) + 15;
+    const maxSeconds = Math.min(ENGINE_MAX_SECONDS, Math.ceil(2 * plannedSeconds));
     const args = [
         "--disable-crash-handler",
         // No local HTTP API or ~/.summer discovery files for this throwaway run.
@@ -206,13 +558,18 @@ export async function captureGameplay(input, overrides = {}) {
         project,
         "--resolution",
         resolution.text,
+        "--max-fps",
+        String(CAPTURE_MAX_FPS),
         ...(scene ? ["--scene", scene] : []),
+        // The verify instance is offscreen already; the posture flag says so explicitly.
+        "--summer-offscreen",
         "--summer-verify",
         probe,
         "--summer-verify-out",
         out,
         "--summer-verify-max",
         String(maxSeconds),
+        ...(userArgs.length ? ["--", ...userArgs] : []),
     ];
     let run;
     try {
@@ -259,6 +616,9 @@ export async function captureGameplay(input, overrides = {}) {
         captured.push({ path, ...size });
     }
     const warnings = [...(results.frame_warnings ?? [])];
+    if (importCheck.lfsPointers.length) {
+        warnings.push(`These files are Git LFS pointers, not the real files, so the game shows them missing: ${importCheck.lfsPointers.join(", ")}. Run "git lfs pull" in the project, then capture again.`);
+    }
     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);
@@ -276,6 +636,7 @@ export async function captureGameplay(input, overrides = {}) {
         out,
         engine: binary,
         imported,
+        ...(imported && importReason ? { importReason } : {}),
         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/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-engine-version.d.ts

@@ -4,6 +4,13 @@
  * summer_export_game writes and fails after a full engine start.
  */
 export declare const EXPORT_MIN_ENGINE_VERSION = "0.7.0";
+/** Bundle targets that need a newer engine than EXPORT_MIN_ENGINE_VERSION. */
+export declare const TARGET_MIN_ENGINE_VERSION: Readonly<Record<string, string>>;
+/** The requested targets this engine version cannot export; an unreadable version skips none. */
+export declare function targetsNeedingNewerEngine(targets: readonly string[], version: string | null): Array<{
+    target: string;
+    needs: string;
+}>;
 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;