summer-engine 3.2.1 → 3.4.0

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

@@ -0,0 +1,168 @@
+import { basename, extname } from "node:path";
+import { stat } from "node:fs/promises";
+import { resolveGatewayUrl } from "../config.js";
+import { OAuthError } from "../oauth.js";
+import { appendStoreJsonLine } from "../store.js";
+import { readZipEntries } from "../util/zip.js";
+import { BuildToolError } from "./summer-bundle.js";
+import { createStore, readGrants, uploadParts } from "./publish-build.js";
+/**
+ * The store's second build path (summer-platform store versions,
+ * internal/creatorstore): a web build (an HTML5 .zip played on summer.games)
+ * 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
+ * routes as Studio (PSE /api/creator-store/* -> /v1/management/*):
+ *
+ *   GET  games/{g}/store/versions?platform=      resume an unfinished upload of the same file
+ *   POST games/{g}/store/versions                {platform, fileName, sizeBytes, label} -> part plan
+ *   GET  .../{v}/parts                           parts storage already has
+ *   POST .../{v}:signParts                       {partNumbers} -> presigned PUT per part
+ *   POST .../{v}:complete                        seal; Summer checks the file
+ *   GET  .../{v}                                 until ready or rejected
+ *
+ * Players get the newest ready version of a platform, so on a game that is
+ * already live the store refuses an agent's :complete (the owner finishes it).
+ */
+export const DOWNLOAD_PLATFORMS = ["web", "macos-universal", "windows-x64", "linux-x64"];
+/** summer-platform creatorstore limits (versions.go, webzip.go). */
+const WEB_MAX_BYTES = 500 * 1024 * 1024;
+const WEB_MAX_FILES = 2000;
+const WEB_MAX_FILE_BYTES = 200 * 1024 * 1024;
+const NATIVE_MAX_BYTES = 20 * 1024 ** 3;
+const WEB_PART_BYTES = 16 * 1024 * 1024;
+const NATIVE_PART_BYTES = 64 * 1024 * 1024;
+const DEFAULT_WAIT_SECONDS = 300;
+const POLL_MS = 3_000;
+const seg = encodeURIComponent;
+export function isDownloadPlatform(value) {
+    return DOWNLOAD_PLATFORMS.includes(value);
+}
+/** The store's file name rule: a letter or digit first, then letters, digits, ". _ -" and spaces, at most 128. */
+export function storeFileName(file) {
+    const cleaned = basename(file).replace(/[^A-Za-z0-9._ -]/g, "-").replace(/^[^A-Za-z0-9]+/, "");
+    return (cleaned || "game.zip").slice(-128);
+}
+/** What the store will refuse, checked before anything is sent. */
+async function checkFile(file, platform, sizeBytes) {
+    const lower = file.toLowerCase();
+    if (platform === "web") {
+        if (extname(lower) !== ".zip")
+            throw new BuildToolError("download_format_unsupported", "A web build is a .zip.", 'Recovery: export with summer_export_game targets ["web"].');
+        if (sizeBytes > WEB_MAX_BYTES)
+            throw new BuildToolError("download_too_large", `The web build is ${Math.ceil(sizeBytes / 1024 ** 2)} MiB; the store takes at most 500 MiB.`, "Recovery: make the build smaller (compress textures, remove unused assets) and export again.");
+        let entries;
+        try {
+            entries = await readZipEntries(file);
+        }
+        catch (error) {
+            throw new BuildToolError("download_unreadable", `${file} is not a readable .zip (${error instanceof Error ? error.message : String(error)}).`, "Recovery: export again.");
+        }
+        const files = entries.filter((entry) => !entry.name.endsWith("/"));
+        if (!files.some((entry) => entry.name === "index.html"))
+            throw new BuildToolError("web_entry_missing", "The web build has no index.html at the top of the .zip.", 'Recovery: export with summer_export_game targets ["web"]; do not wrap the files in a folder.');
+        if (files.length > WEB_MAX_FILES)
+            throw new BuildToolError("web_too_many_files", `The web build has ${files.length} files; the store takes at most ${WEB_MAX_FILES}.`, "Recovery: export again; a Summer web export has a handful of files.");
+        const big = files.find((entry) => entry.uncompressedSize > WEB_MAX_FILE_BYTES);
+        if (big)
+            throw new BuildToolError("web_file_too_large", `${big.name} is larger than 200 MiB.`, "Recovery: make the pack smaller and export again.");
+        return { fileCount: files.length };
+    }
+    if (!(lower.endsWith(".zip") || lower.endsWith(".tar.gz") || lower.endsWith(".tgz"))) {
+        throw new BuildToolError("download_format_unsupported", "A native download is a .zip or .tar.gz.", 'Recovery: export with summer_export_game format "download".');
+    }
+    if (sizeBytes > NATIVE_MAX_BYTES)
+        throw new BuildToolError("download_too_large", "The download is larger than 20 GiB.", "Recovery: make the build smaller and export again.");
+    return {};
+}
+export async function publishDownload(input, deps) {
+    const { gameId, file, clientVersion } = input;
+    if (!isDownloadPlatform(input.platform)) {
+        throw new BuildToolError("platform_invalid", `"${input.platform}" is not a store download platform.`, `Recovery: pass platform as one of ${DOWNLOAD_PLATFORMS.join(", ")}.`);
+    }
+    const platform = input.platform;
+    const sizeBytes = (await stat(file)).size;
+    const { fileCount } = await checkFile(file, platform, sizeBytes);
+    const fileName = storeFileName(file);
+    const target = { gameId, file, platform, fileName, sizeBytes, clientVersion, ...(fileCount ? { fileCount } : {}) };
+    if (input.confirm !== true) {
+        return {
+            ok: true,
+            status: "confirmation_required",
+            target,
+            next: "Show the user this exact game, file, platform, size and version. Only after they approve, call again with confirm=true. Nothing was uploaded.",
+        };
+    }
+    let token;
+    try {
+        token = await deps.token();
+    }
+    catch (error) {
+        if (error instanceof OAuthError)
+            throw new BuildToolError(error.code, error.message.replace(` ${error.recovery}`, ""), error.recovery);
+        throw error;
+    }
+    const store = createStore(await resolveGatewayUrl(), token, deps);
+    const audit = { at: new Date(deps.now()).toISOString(), operation: "publish_download", face: input.face, ...target };
+    await appendStoreJsonLine("creator-audit.jsonl", { ...audit, outcome: "started" });
+    const versions = `games/${seg(gameId)}/store/versions`;
+    try {
+        // The same file and version still waiting for its bytes: continue it.
+        const listed = await store.call("GET", `${versions}?platform=${seg(platform)}`);
+        let version = (listed.items ?? []).find((item) => item.status === "awaiting_upload" && item.platform === platform && item.fileName === fileName && item.sizeBytes === sizeBytes && item.label === clientVersion);
+        let plan = null;
+        const resumed = Boolean(version);
+        if (!version) {
+            const created = await store.call("POST", versions, {
+                body: { platform, fileName, sizeBytes, label: clientVersion },
+            });
+            version = created.version;
+            plan = { partSizeBytes: Number(created.upload?.partSizeBytes), partCount: Number(created.upload?.partCount) };
+        }
+        if (!version?.id)
+            throw new BuildToolError("store_invalid_response", "The store did not return a version id.", "Recovery: retry.");
+        const versionPath = `${versions}/${seg(version.id)}`;
+        if (version.status === "awaiting_upload") {
+            const partSizeBytes = plan?.partSizeBytes || (platform === "web" ? WEB_PART_BYTES : NATIVE_PART_BYTES);
+            const partCount = plan?.partCount || Math.max(1, Math.ceil(sizeBytes / partSizeBytes));
+            if (!(partSizeBytes > 0) || partCount !== Math.max(1, Math.ceil(sizeBytes / partSizeBytes))) {
+                throw new BuildToolError("store_invalid_response", "The store's part plan does not fit this file.", "Recovery: retry; if it repeats, report the store as unhealthy.");
+            }
+            const expected = (n) => (n < partCount ? partSizeBytes : sizeBytes - (partCount - 1) * partSizeBytes);
+            const stored = resumed ? (await store.call("GET", `${versionPath}/parts`)).parts ?? [] : [];
+            const done = new Set(stored.filter((part) => part.sizeBytes === expected(part.partNumber)).map((part) => part.partNumber));
+            const missing = Array.from({ length: partCount }, (_, index) => index + 1).filter((n) => !done.has(n));
+            if (missing.length) {
+                await uploadParts(async (numbers) => readGrants(await store.call("POST", `${versionPath}:signParts`, { body: { partNumbers: numbers } })), file, sizeBytes, { partSizeBytes, partCount }, deps, missing);
+            }
+            version = (await store.call("POST", `${versionPath}:complete`, { body: {} })).version ?? version;
+        }
+        const deadline = deps.now() + (input.waitSeconds ?? DEFAULT_WAIT_SECONDS) * 1000;
+        while (version.status !== "ready" && version.status !== "rejected" && deps.now() < deadline) {
+            await deps.sleep(POLL_MS);
+            version = await store.call("GET", versionPath);
+        }
+        const outcome = version.status === "ready" ? "ready" : version.status === "rejected" ? "rejected" : "processing";
+        await appendStoreJsonLine("creator-audit.jsonl", { ...audit, outcome, versionId: version.id });
+        if (version.status === "rejected") {
+            throw new BuildToolError("download_rejected", version.rejectionReason || "Summer Games did not accept this file.", "Recovery: fix what the reason says, export again and upload with a new clientVersion.", undefined, { versionId: version.id });
+        }
+        return {
+            ok: true,
+            status: outcome,
+            gameId,
+            versionId: version.id,
+            platform,
+            clientVersion,
+            resumed,
+            ...(version.playUrl ? { playUrl: version.playUrl } : {}),
+            next: outcome === "ready"
+                ? "The file is checked. Players get it once the store page is live; submit the page with summer_store_submit (the owner approves)."
+                : "Summer is still checking the file. Call summer_publish_build again with the same file and clientVersion to keep waiting; nothing is uploaded twice.",
+        };
+    }
+    catch (error) {
+        await appendStoreJsonLine("creator-audit.jsonl", { ...audit, outcome: "failed", code: error instanceof BuildToolError ? error.code : "publish_download_failed" });
+        throw error;
+    }
+}

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

@@ -97,14 +97,14 @@ export declare const runtimeSetArgsSchema: z.ZodObject<{
     field: z.ZodOptional<z.ZodString>;
     instance: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    path: string;
     value: string | number | boolean;
+    path: string;
     property: string;
     instance?: string | undefined;
     field?: string | undefined;
 }, {
-    path: string;
     value: string | number | boolean;
+    path: string;
     property: string;
     instance?: string | undefined;
     field?: string | undefined;
@@ -117,13 +117,13 @@ export declare const runtimeCallArgsSchema: z.ZodObject<{
     args: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
     instance: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    path: string;
     method: string;
+    path: string;
     args?: unknown[] | undefined;
     instance?: string | undefined;
 }, {
-    path: string;
     method: string;
+    path: string;
     args?: unknown[] | undefined;
     instance?: string | undefined;
 }>;
@@ -183,13 +183,13 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     path: string;
     target: "tree" | "player" | "bones";
+    state?: string | undefined;
+    value?: string | number | boolean | undefined;
     instance?: string | undefined;
     name?: string | undefined;
-    value?: string | number | boolean | undefined;
-    cmd?: "pause" | "play" | "stop" | "state" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
+    cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
     space?: "local" | "global" | "both" | undefined;
     blend?: number | undefined;
-    state?: string | undefined;
     position?: number | undefined;
     speed?: number | undefined;
     bones?: string[] | undefined;
@@ -202,13 +202,13 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
 }, {
     path: string;
     target: "tree" | "player" | "bones";
+    state?: string | undefined;
+    value?: string | number | boolean | undefined;
     instance?: string | undefined;
     name?: string | undefined;
-    value?: string | number | boolean | undefined;
-    cmd?: "pause" | "play" | "stop" | "state" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
+    cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
     space?: "local" | "global" | "both" | undefined;
     blend?: number | undefined;
-    state?: string | undefined;
     position?: number | undefined;
     speed?: number | undefined;
     bones?: string[] | undefined;

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

@@ -0,0 +1,49 @@
+/**
+ * The summer.games export (summer-platform ADR 0033): one .zip with
+ * summer-bundle.json, client.pck, and for a game with a host server.pck plus
+ * config/. This reads what the build upload declares; the Platform verifies
+ * the uploaded bytes again. Same rules as Studio's browser check
+ * (publicsummerengine src/lib/creator-store/pck-check.ts, checkBundle).
+ */
+export declare const BUNDLE_SCHEMA = "summer.bundle.v1";
+export declare const BUNDLE_MANIFEST = "summer-bundle.json";
+/** A failure with a stable code, a plain message and the next step. */
+export declare class BuildToolError extends Error {
+    readonly code: string;
+    readonly recovery: string;
+    readonly status?: number | undefined;
+    readonly detail?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, recovery: string, status?: number | undefined, detail?: Record<string, unknown> | undefined);
+}
+export interface BundleFile {
+    path: string;
+    sha256: string;
+    size: number;
+}
+export interface SummerBundle {
+    schema: typeof BUNDLE_SCHEMA;
+    summerVersion: string | null;
+    engineSha: string | null;
+    /** res:// scene the client pack opens. */
+    mainScene: string;
+    /** Client platforms the export was made for (ios, macos, windows, ...). */
+    targetPlatforms: string[];
+    /** True when the game has a host (server.pck + config/summer.build.json). */
+    hosted: boolean;
+    compositionPath: string | null;
+    /** client.pck as summer-bundle.json lists it ("sha256:<hex>"). */
+    clientPack: {
+        sha256: string;
+        size: number;
+    };
+    /** Hosted only: config/summer.build.json, sent as the Build declaration. */
+    hostedBuild?: Record<string, unknown>;
+    files: BundleFile[];
+}
+/** Read and check summer-bundle.json in an exported .zip. */
+export declare function readSummerBundle(path: string): Promise<SummerBundle>;
+/** "sha256:<hex>" and size of a whole file, streamed. */
+export declare function hashFile(path: string): Promise<{
+    sha256: string;
+    sizeBytes: number;
+}>;

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

@@ -0,0 +1,156 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readZipEntries, readZipEntry, ZipReadError } from "../util/zip.js";
+/**
+ * The summer.games export (summer-platform ADR 0033): one .zip with
+ * summer-bundle.json, client.pck, and for a game with a host server.pck plus
+ * config/. This reads what the build upload declares; the Platform verifies
+ * the uploaded bytes again. Same rules as Studio's browser check
+ * (publicsummerengine src/lib/creator-store/pck-check.ts, checkBundle).
+ */
+export const BUNDLE_SCHEMA = "summer.bundle.v1";
+export const BUNDLE_MANIFEST = "summer-bundle.json";
+const BUNDLE_CLIENT = "client.pck";
+const BUNDLE_SERVER = "server.pck";
+const BUNDLE_BUILD = "config/summer.build.json";
+const SHA256 = /^sha256:[0-9a-f]{64}$/;
+const AS_EXPORTED = "Recovery: export the game again with the summer.games preset and use the .zip exactly as Summer Engine wrote it.";
+/** A failure with a stable code, a plain message and the next step. */
+export class BuildToolError extends Error {
+    code;
+    recovery;
+    status;
+    detail;
+    constructor(code, message, recovery, status, detail) {
+        super(`${message} ${recovery}`);
+        this.code = code;
+        this.recovery = recovery;
+        this.status = status;
+        this.detail = detail;
+        this.name = "BuildToolError";
+    }
+}
+function bundleError(message) {
+    return new BuildToolError("bundle_invalid", message, AS_EXPORTED);
+}
+/** Read and check summer-bundle.json in an exported .zip. */
+export async function readSummerBundle(path) {
+    let entries;
+    try {
+        entries = await readZipEntries(path);
+    }
+    catch (error) {
+        throw bundleError(`${path} is not a readable summer.games export (${error instanceof Error ? error.message : String(error)}).`);
+    }
+    const byName = new Map(entries.map((entry) => [entry.name, entry]));
+    const manifestEntry = byName.get(BUNDLE_MANIFEST);
+    const clientEntry = byName.get(BUNDLE_CLIENT);
+    if (!manifestEntry || !clientEntry) {
+        throw bundleError(`${path} is not a summer.games export: it has no ${BUNDLE_MANIFEST} and ${BUNDLE_CLIENT}.`);
+    }
+    if (byName.size !== entries.length ||
+        entries.some((entry) => entry.encrypted ||
+            entry.name.endsWith("/") ||
+            entry.name.split("/").some((part) => !part || part === "." || part === "..") ||
+            /[\\\0\r\n]/.test(entry.name))) {
+        throw bundleError("The export contains a repeated or unsafe file path.");
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse((await readZipEntry(path, manifestEntry)).toString("utf8"));
+    }
+    catch (error) {
+        if (error instanceof ZipReadError)
+            throw bundleError(`${BUNDLE_MANIFEST} could not be read: ${error.message}`);
+        throw bundleError(`${BUNDLE_MANIFEST} is not valid JSON.`);
+    }
+    const client = manifest?.client;
+    const mainScene = typeof client?.mainScene === "string" ? client.mainScene : null;
+    if (manifest?.schema !== BUNDLE_SCHEMA ||
+        client?.path !== BUNDLE_CLIENT ||
+        !mainScene?.startsWith("res://") ||
+        !Array.isArray(client?.targetPlatforms) ||
+        !client.targetPlatforms.every((value) => typeof value === "string") ||
+        !Array.isArray(manifest.files)) {
+        throw new BuildToolError("bundle_invalid", `${BUNDLE_MANIFEST} is not a ${BUNDLE_SCHEMA} manifest.`, "Recovery: update Summer Engine and export again.");
+    }
+    const hosted = Boolean(manifest.server);
+    const compositionPath = typeof manifest.compositionPath === "string" ? manifest.compositionPath : null;
+    if ((!hosted && manifest.compositionPath != null) ||
+        hosted !== byName.has(BUNDLE_SERVER) ||
+        (hosted &&
+            (manifest.server?.path !== BUNDLE_SERVER ||
+                typeof manifest.server.mainScene !== "string" ||
+                !/^res:\/\/.+\.tscn$/.test(manifest.server.mainScene) ||
+                !compositionPath ||
+                !/^res:\/\/.+\.tres$/.test(compositionPath)))) {
+        throw bundleError("The export must name its server pack, main scene and network composition together.");
+    }
+    const allowed = (name) => name === BUNDLE_MANIFEST ||
+        name === BUNDLE_CLIENT ||
+        name === BUNDLE_BUILD ||
+        (hosted && (name === BUNDLE_SERVER || name.startsWith("config/")));
+    const extra = entries.find((entry) => !allowed(entry.name));
+    if (extra)
+        throw bundleError(`The export contains ${extra.name}, which a summer.games export never has.`);
+    const files = [];
+    for (const item of manifest.files) {
+        const entry = typeof item?.path === "string" ? byName.get(item.path) : undefined;
+        if (!entry ||
+            item.path === BUNDLE_MANIFEST ||
+            typeof item.sha256 !== "string" ||
+            !SHA256.test(item.sha256) ||
+            item.size !== entry.uncompressedSize) {
+            throw bundleError(`The files do not match ${BUNDLE_MANIFEST}.`);
+        }
+        files.push({ path: entry.name, sha256: item.sha256, size: entry.uncompressedSize });
+    }
+    if (new Set(files.map((file) => file.path)).size !== files.length || files.length !== entries.length - 1) {
+        throw bundleError(`The files do not match ${BUNDLE_MANIFEST}.`);
+    }
+    const listedClient = files.find((file) => file.path === BUNDLE_CLIENT);
+    if (clientEntry.method !== 0) {
+        throw bundleError(`${BUNDLE_CLIENT} is compressed in this zip; Summer reads it in place, so it must be stored.`);
+    }
+    let hostedBuild;
+    if (hosted) {
+        const config = byName.get(BUNDLE_BUILD);
+        let build;
+        try {
+            build = config ? JSON.parse((await readZipEntry(path, config, 64 * 1024)).toString("utf8")) : undefined;
+        }
+        catch {
+            build = undefined;
+        }
+        if (!build || typeof build !== "object" || Array.isArray(build) || build.executionMode !== "hosted") {
+            throw bundleError(`${BUNDLE_BUILD} is missing or does not declare a hosted game.`);
+        }
+        hostedBuild = build;
+    }
+    const targetPlatforms = client.targetPlatforms;
+    if (new Set(targetPlatforms).size !== targetPlatforms.length || targetPlatforms.length === 0) {
+        throw bundleError("The export must name at least one platform, each once.");
+    }
+    return {
+        schema: BUNDLE_SCHEMA,
+        summerVersion: typeof manifest.export?.summerVersion === "string" ? manifest.export.summerVersion : null,
+        engineSha: typeof manifest.export?.engineSha === "string" ? manifest.export.engineSha : null,
+        mainScene: mainScene,
+        targetPlatforms,
+        hosted,
+        compositionPath,
+        clientPack: { sha256: listedClient.sha256, size: listedClient.size },
+        ...(hostedBuild ? { hostedBuild } : {}),
+        files,
+    };
+}
+/** "sha256:<hex>" and size of a whole file, streamed. */
+export async function hashFile(path) {
+    const hash = createHash("sha256");
+    let sizeBytes = 0;
+    for await (const chunk of createReadStream(path)) {
+        hash.update(chunk);
+        sizeBytes += chunk.length;
+    }
+    return { sha256: `sha256:${hash.digest("hex")}`, sizeBytes };
+}

package/dist/core/capabilities/tool-dispatch.js

@@ -47,6 +47,10 @@ import open from "open";
 import { openArgsSchema, runOpen } from "./navigation/open.js";
 import { shapeEngineLogResponse } from "../log-filters.js";
 import { listCreatorReleases, publishCreator, } from "./creator.js";
+import { exportGame } from "./export-game.js";
+import { exportTemplates } from "./export-templates.js";
+import { captureGameplay } from "./capture-gameplay.js";
+import { publishBuild } from "./publish-build.js";
 import { CONFIG_KEYS, getConfigValue, isConfigKey, readSummerConfig, resolveGatewayUrl, setConfigValue, unsetConfigValue, } from "../config.js";
 import { createDebugReportArtifact } from "./debug-report.js";
 import { buildGameTaskPlan, gameTaskPlanInputSchema } from "./game-task-plan.js";
@@ -608,7 +612,45 @@ export const TOOL_DISPATCH = [
             throw err;
         }
     }),
-    entry("summer_creator_publish", "Publish an exported .pck through the creator API (confirm-gated)", false, (args) => publishCreator({
+    entry("summer_export_game", "Export the game as a summer.games .zip with the installed engine (headless)", false, (args) => exportGame({
+        project: optStr(args, "project"),
+        out: optStr(args, "out"),
+        targets: Array.isArray(args.targets) ? args.targets.map(String) : undefined,
+        format: optStr(args, "format"),
+        debug: args.debug === true,
+        ...(typeof args.timeoutSeconds === "number" ? { timeoutMs: args.timeoutSeconds * 1000 } : {}),
+    })),
+    entry("summer_export_templates", "List or install Summer export templates from the CDN (web, macos, windows)", false, (args) => {
+        const action = optStr(args, "action");
+        if (action !== "list" && action !== "install")
+            throw new ToolDispatchError('action must be "list" or "install".');
+        return exportTemplates({
+            action,
+            platforms: Array.isArray(args.platforms) ? args.platforms.map(String) : undefined,
+            includeDebug: args.includeDebug === true,
+            summerVersion: optStr(args, "summerVersion"),
+        });
+    }),
+    entry("summer_capture_gameplay", "Capture real gameplay frames offscreen, without a running editor", false, (args) => captureGameplay({
+        project: optStr(args, "project"),
+        scene: optStr(args, "scene"),
+        resolution: optStr(args, "resolution"),
+        frames: optNumberOrUndefined(args, "frames"),
+        waitSeconds: optNumberOrUndefined(args, "waitSeconds"),
+        intervalSeconds: optNumberOrUndefined(args, "intervalSeconds"),
+        out: optStr(args, "out"),
+    })),
+    entry("summer_publish_build", "Upload a summer.games export to your store game (confirm-gated)", false, (args) => publishBuild({
+        gameId: optStr(args, "gameId"),
+        file: optStr(args, "file"),
+        clientVersion: optStr(args, "clientVersion"),
+        publish: args.publish === true,
+        platform: optStr(args, "platform"),
+        confirm: args.confirm === true,
+        ...(typeof args.waitSeconds === "number" ? { waitSeconds: args.waitSeconds } : {}),
+        face: "cli",
+    })),
+    entry("summer_creator_publish", "Deprecated: publish a .pck to the legacy creator API; use publish-build", false, (args) => publishCreator({
         project: optStr(args, "project"),
         artifact: optStr(args, "artifact"),
         version: optStr(args, "version"),

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

@@ -88,17 +88,17 @@ export declare const uiActivateArgsSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     button: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    value?: string | number | undefined;
     title?: string | undefined;
     path?: string | undefined;
-    value?: string | number | undefined;
     action?: "focus" | "press" | "toggle" | "select_tab" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
     button?: string | undefined;
     index?: number | undefined;
     submit?: boolean | undefined;
 }, {
+    value?: string | number | undefined;
     title?: string | undefined;
     path?: string | undefined;
-    value?: string | number | undefined;
     action?: "focus" | "press" | "toggle" | "select_tab" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
     button?: string | undefined;
     index?: number | undefined;

package/dist/core/config.js

@@ -30,7 +30,7 @@ function validateGatewayUrl(value) {
     }
     const local = parsed.hostname === "localhost" ||
         parsed.hostname === "127.0.0.1" ||
-        parsed.hostname === "::1";
+        parsed.hostname === "[::1]";
     if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) {
         throw new Error("gateway.url must use HTTPS (HTTP is allowed only for localhost). Recovery: set an HTTPS URL and retry.");
     }
@@ -49,7 +49,7 @@ function validateCreatorApiUrl(value) {
     }
     const local = parsed.hostname === "localhost" ||
         parsed.hostname === "127.0.0.1" ||
-        parsed.hostname === "::1";
+        parsed.hostname === "[::1]";
     if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) {
         throw new Error("creator.apiUrl must use HTTPS (HTTP is allowed only for localhost). Recovery: set an HTTPS URL and retry.");
     }

package/dist/core/engine-install.d.ts

@@ -58,6 +58,22 @@ export declare function linuxEngineInstallDir(): string;
 export declare function macEnginePaths(env?: NodeJS.ProcessEnv): string[];
 export declare function windowsEnginePaths(env?: NodeJS.ProcessEnv): string[];
 export declare function linuxEnginePaths(): string[];
+/** Where `summer install` records the engine it installed last
+ *  (~/.summer/engine-install.json), so an install with --path is found later
+ *  without SUMMER_BIN. */
+export declare const ENGINE_INSTALL_FILE = "engine-install.json";
+export interface RecordedEngineInstall {
+    schemaVersion: 1;
+    /** The engine executable (on macOS the one inside Summer.app). */
+    binary: string;
+    version: string | null;
+    installedAt: string;
+}
+export declare function recordEngineInstall(binary: string, version: string | null): Promise<void>;
+/** The engine `summer install` installed last, or null (sync: findEngineBinary is). */
+export declare function recordedEngineBinary(): string | null;
+/** The bundle summer install writes on macOS: <path>/Summer.app, or the path itself when it names a .app. */
+export declare function macInstallDestination(customPath?: string): string;
 export declare function engineBinaryCandidates(os?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string[];
 /** First existing engine binary for this machine, or null. SUMMER_BIN /
  *  SUMMER_ENGINE_BINARY wins when set and present; a set-but-missing override

package/dist/core/engine-install.js

@@ -1,6 +1,7 @@
-import { existsSync, statSync } from "fs";
+import { existsSync, readFileSync, statSync } from "fs";
 import { homedir, platform } from "os";
 import { basename, join } from "path";
+import { getSummerDir, writeStoreJson } from "./store.js";
 /**
  * Where each platform's engine binary lives, shared by `summer install`,
  * `summer run`, and `summer doctor` so they can never disagree about what
@@ -95,6 +96,31 @@ export function windowsEnginePaths(env = process.env) {
 export function linuxEnginePaths() {
     return [join(linuxEngineInstallDir(), LINUX_ENGINE_BINARY_NAME)];
 }
+/** Where `summer install` records the engine it installed last
+ *  (~/.summer/engine-install.json), so an install with --path is found later
+ *  without SUMMER_BIN. */
+export const ENGINE_INSTALL_FILE = "engine-install.json";
+export async function recordEngineInstall(binary, version) {
+    const record = { schemaVersion: 1, binary, version, installedAt: new Date().toISOString() };
+    await writeStoreJson(ENGINE_INSTALL_FILE, record);
+}
+/** The engine `summer install` installed last, or null (sync: findEngineBinary is). */
+export function recordedEngineBinary() {
+    try {
+        const record = JSON.parse(readFileSync(join(getSummerDir(), ENGINE_INSTALL_FILE), "utf8"));
+        return record.schemaVersion === 1 && typeof record.binary === "string" && record.binary ? record.binary : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The bundle summer install writes on macOS: <path>/Summer.app, or the path itself when it names a .app. */
+export function macInstallDestination(customPath) {
+    if (!customPath?.trim())
+        return "/Applications/Summer.app";
+    const trimmed = customPath.trim().replace(/\/+$/, "");
+    return /\.app$/i.test(trimmed) ? trimmed : join(trimmed, "Summer.app");
+}
 export function engineBinaryCandidates(os = platform(), env = process.env) {
     const override = engineBinaryOverride(env)?.path;
     const platformPaths = os === "darwin"
@@ -102,7 +128,11 @@ export function engineBinaryCandidates(os = platform(), env = process.env) {
         : os === "linux"
             ? linuxEnginePaths()
             : windowsEnginePaths(env);
-    return override ? [override, ...platformPaths] : platformPaths;
+    // The engine summer install put in place last wins over the default
+    // locations (an install with --path next to an older /Applications copy).
+    const recorded = recordedEngineBinary();
+    const paths = recorded ? [recorded, ...platformPaths.filter((path) => path !== recorded)] : platformPaths;
+    return override ? [override, ...paths] : paths;
 }
 /** First existing engine binary for this machine, or null. SUMMER_BIN /
  *  SUMMER_ENGINE_BINARY wins when set and present; a set-but-missing override