summer-engine 4.3.0 → 4.6.0

package/dist/core/capabilities/item-manifest.js

@@ -0,0 +1,247 @@
+import { readFile } from "node:fs/promises";
+import { extname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { BuildToolError } from "./summer-bundle.js";
+/**
+ * summer.items.json: the Game's items, keyed by creator slug, next to
+ * summer.build.json in the project root and committed with the game.
+ *
+ * It names no Game, environment or platform id: the same file syncs to the
+ * staging Game and to the production Game, and the slug (the creator key the
+ * game's code uses, e.g. "emote_ponder") is what identifies an item in both.
+ * The gameId comes with each sync call, as with summer_publish_build.
+ *
+ *   {
+ *     "schema": "summer.items/v1",
+ *     "items": [
+ *       {
+ *         "slug": "emote_ponder",
+ *         "name": "Ponder",
+ *         "description": "Strike a thoughtful pose.",
+ *         "class": "COSMETIC",
+ *         "cosmetic": { "familyId": "emote", "variantKey": "ponder" },
+ *         "tags": ["emote"],
+ *         "ownership": "OWNED",
+ *         "priceSparks": 150,
+ *         "media": ["art/items/emote_ponder.png"]
+ *       }
+ *     ]
+ *   }
+ *
+ * The checks here are the platform's own create rules (management API
+ * item-definitions), so a file that passes is not refused for its shape.
+ */
+export const ITEMS_MANIFEST_FILE = "summer.items.json";
+export const ITEMS_MANIFEST_SCHEMA = "summer.items/v1";
+/** The platform's slug rule: 1-64 characters, lowercase, words joined by one ".", "_" or "-". */
+export const ITEM_SLUG = /^[a-z][a-z0-9]*([._-][a-z0-9]+)*$/;
+const TAG = /^[a-z0-9][a-z0-9._-]{0,47}$/;
+/** Cosmetic familyId and variantKey: the platform's compatibility value rule, at most 128 characters. */
+const COSMETIC_KEY = /^[a-z][a-z0-9]*([._-][a-z0-9]+)*$/;
+const BACKGROUND = /^#[0-9A-Fa-f]{6}$/;
+const MAX_ITEMS = 500;
+const MAX_MEDIA = 20;
+const MAX_NAME = 120;
+const MAX_DESCRIPTION = 5000;
+const MAX_TAGS = 20;
+export const ITEM_CLASSES = ["STANDARD", "COSMETIC"];
+export const OWNERSHIP_MODES = ["INSTANCE", "QUANTITY"];
+export const OWNERSHIP_POLICIES = ["SOULBOUND", "OWNED", "MARKETABLE"];
+export const MEDIA_TYPES = {
+    ".png": { kind: "IMAGE", contentType: "image/png", maxBytes: 32 << 20 },
+    ".jpg": { kind: "IMAGE", contentType: "image/jpeg", maxBytes: 32 << 20 },
+    ".jpeg": { kind: "IMAGE", contentType: "image/jpeg", maxBytes: 32 << 20 },
+    ".webp": { kind: "IMAGE", contentType: "image/webp", maxBytes: 32 << 20 },
+    ".glb": { kind: "MODEL_3D", contentType: "model/gltf-binary", maxBytes: 64 << 20 },
+};
+/** The platform behavior a manifest entry declares (item-definitions create body). */
+export function behaviorOf(item) {
+    const marketable = item.ownership === "MARKETABLE";
+    return {
+        class: item.class,
+        ownershipMode: item.ownershipMode,
+        ...(item.maxOwned !== undefined ? { maxOwned: item.maxOwned } : {}),
+        rights: {
+            policy: item.ownership,
+            consumable: item.consumable,
+            directTransferAllowed: marketable,
+            giftingAfterOwnershipAllowed: marketable,
+            publicResalePolicyEligible: marketable,
+        },
+        // Studio's defaults: the game's server may grant it, and Summer support may restore it.
+        issuance: { serverMintAllowed: true, supportGrantAllowed: true },
+        ...(item.cosmetic ? { cosmetic: item.cosmetic } : {}),
+    };
+}
+class ManifestProblems {
+    list = [];
+    add(where, problem) {
+        if (this.list.length < 50)
+            this.list.push(`${where}: ${problem}`);
+    }
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const positiveInt = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+const ITEM_FIELDS = new Set([
+    "slug", "name", "description", "class", "cosmetic", "tags", "ownershipMode", "maxOwned",
+    "ownership", "consumable", "supply", "priceSparks", "backgroundColor", "media",
+]);
+function mediaPath(project, value, where, problems) {
+    if (typeof value !== "string" || !value.trim()) {
+        problems.add(where, "a project-relative file path");
+        return null;
+    }
+    const clean = normalize(value.trim());
+    const full = resolve(project, clean);
+    const inside = relative(project, full);
+    if (isAbsolute(value) || inside.startsWith("..") || isAbsolute(inside)) {
+        problems.add(where, `"${value}" is outside the project; use a path inside it`);
+        return null;
+    }
+    if (!MEDIA_TYPES[extname(clean).toLowerCase()]) {
+        problems.add(where, `"${value}" is not a store image (.png, .jpg, .webp) or model (.glb)`);
+        return null;
+    }
+    return inside.split(sep).join("/");
+}
+function readItem(project, raw, index, problems) {
+    const at = `items[${index}]`;
+    if (!isObject(raw)) {
+        problems.add(at, "an object");
+        return null;
+    }
+    const where = typeof raw.slug === "string" ? `${at} (${raw.slug})` : at;
+    for (const key of Object.keys(raw))
+        if (!ITEM_FIELDS.has(key))
+            problems.add(where, `unknown field "${key}"`);
+    const before = problems.list.length;
+    const slug = raw.slug;
+    if (typeof slug !== "string" || slug.length > 64 || !ITEM_SLUG.test(slug)) {
+        problems.add(where, 'slug: 1-64 lowercase letters and digits, words joined by ".", "_" or "-", starting with a letter (e.g. "emote_ponder")');
+    }
+    const name = raw.name;
+    if (typeof name !== "string" || name !== name.trim() || name.length < 1 || [...name].length > MAX_NAME) {
+        problems.add(where, `name: 1-${MAX_NAME} characters, no surrounding spaces`);
+    }
+    const description = raw.description;
+    if (typeof description !== "string" || description !== description.trim() || description.length < 1 || [...description].length > MAX_DESCRIPTION) {
+        problems.add(where, `description: 1-${MAX_DESCRIPTION} characters, no surrounding spaces`);
+    }
+    const itemClass = raw.class ?? "STANDARD";
+    if (!ITEM_CLASSES.includes(itemClass))
+        problems.add(where, `class: one of ${ITEM_CLASSES.join(", ")}`);
+    const ownershipMode = raw.ownershipMode ?? "INSTANCE";
+    if (!OWNERSHIP_MODES.includes(ownershipMode))
+        problems.add(where, `ownershipMode: one of ${OWNERSHIP_MODES.join(", ")}`);
+    const ownership = raw.ownership ?? "OWNED";
+    if (!OWNERSHIP_POLICIES.includes(ownership))
+        problems.add(where, `ownership: one of ${OWNERSHIP_POLICIES.join(", ")}`);
+    if (raw.consumable !== undefined && typeof raw.consumable !== "boolean")
+        problems.add(where, "consumable: true or false");
+    if (raw.maxOwned !== undefined && !positiveInt(raw.maxOwned))
+        problems.add(where, "maxOwned: a whole number, 1 or more");
+    if (raw.supply !== undefined && !positiveInt(raw.supply))
+        problems.add(where, "supply: a whole number, 1 or more (omit it for unlimited)");
+    if (raw.priceSparks !== undefined && !positiveInt(raw.priceSparks))
+        problems.add(where, "priceSparks: a whole number of Sparks, 1 or more (omit it to set no price)");
+    if (raw.backgroundColor !== undefined && (typeof raw.backgroundColor !== "string" || !BACKGROUND.test(raw.backgroundColor))) {
+        problems.add(where, 'backgroundColor: "#RRGGBB"');
+    }
+    const tags = raw.tags ?? [];
+    if (!Array.isArray(tags) || tags.length > MAX_TAGS || tags.some((tag) => typeof tag !== "string" || !TAG.test(tag)) || new Set(tags).size !== tags.length) {
+        problems.add(where, `tags: up to ${MAX_TAGS} different lowercase tags (letters, digits, ".", "_", "-")`);
+    }
+    let cosmetic;
+    if (itemClass === "COSMETIC") {
+        const facet = raw.cosmetic;
+        if (!isObject(facet) || typeof facet.familyId !== "string" || typeof facet.variantKey !== "string" || facet.familyId.length > 128 || facet.variantKey.length > 128 || !COSMETIC_KEY.test(facet.familyId) || !COSMETIC_KEY.test(facet.variantKey)) {
+            problems.add(where, 'cosmetic: { "familyId": ..., "variantKey": ... }, each lowercase words joined by ".", "_" or "-", at most 128 characters');
+        }
+        else {
+            cosmetic = { familyId: facet.familyId, variantKey: facet.variantKey };
+        }
+        if (ownershipMode === "QUANTITY" && raw.maxOwned !== 1)
+            problems.add(where, "a COSMETIC with ownershipMode QUANTITY needs maxOwned 1");
+    }
+    else if (raw.cosmetic !== undefined) {
+        problems.add(where, "cosmetic: only for class COSMETIC");
+    }
+    const mediaRaw = raw.media ?? [];
+    const media = [];
+    if (!Array.isArray(mediaRaw) || mediaRaw.length > MAX_MEDIA) {
+        problems.add(where, `media: up to ${MAX_MEDIA} project-relative image or model paths`);
+    }
+    else {
+        mediaRaw.forEach((value, mediaIndex) => {
+            const path = mediaPath(project, value, `${where} media[${mediaIndex}]`, problems);
+            if (path && media.includes(path))
+                problems.add(`${where} media[${mediaIndex}]`, `"${value}" is listed twice`);
+            else if (path)
+                media.push(path);
+        });
+    }
+    if (problems.list.length !== before)
+        return null;
+    return {
+        slug: slug,
+        name: name,
+        description: description,
+        class: itemClass,
+        ...(cosmetic ? { cosmetic } : {}),
+        tags: tags,
+        ownershipMode: ownershipMode,
+        ...(raw.maxOwned !== undefined ? { maxOwned: raw.maxOwned } : {}),
+        ownership: ownership,
+        consumable: raw.consumable === true,
+        ...(raw.supply !== undefined ? { supply: raw.supply } : {}),
+        ...(raw.priceSparks !== undefined ? { priceSparks: raw.priceSparks } : {}),
+        ...(raw.backgroundColor !== undefined ? { backgroundColor: raw.backgroundColor } : {}),
+        media,
+    };
+}
+/** Parse and check a manifest document; every problem is reported at once. */
+export function parseItemsManifest(project, document, path = join(project, ITEMS_MANIFEST_FILE)) {
+    const problems = new ManifestProblems();
+    if (!isObject(document))
+        problems.add(ITEMS_MANIFEST_FILE, "a JSON object");
+    else {
+        if (document.schema !== ITEMS_MANIFEST_SCHEMA)
+            problems.add("schema", `"${ITEMS_MANIFEST_SCHEMA}"`);
+        for (const key of Object.keys(document))
+            if (key !== "schema" && key !== "items")
+                problems.add(ITEMS_MANIFEST_FILE, `unknown field "${key}"`);
+        if (!Array.isArray(document.items) || document.items.length > MAX_ITEMS)
+            problems.add("items", `a list of up to ${MAX_ITEMS} items`);
+    }
+    const rawItems = isObject(document) && Array.isArray(document.items) ? document.items : [];
+    const items = rawItems.map((raw, index) => readItem(project, raw, index, problems));
+    const seen = new Set();
+    for (const item of items) {
+        if (!item)
+            continue;
+        if (seen.has(item.slug))
+            problems.add(`items (${item.slug})`, "the same slug is used twice; each item needs its own");
+        seen.add(item.slug);
+    }
+    if (problems.list.length) {
+        throw new BuildToolError("items_manifest_invalid", `${ITEMS_MANIFEST_FILE} has ${problems.list.length === 50 ? "50 or more" : problems.list.length} problem${problems.list.length === 1 ? "" : "s"}. Nothing was sent.`, "Recovery: fix each listed field and call again.", undefined, { problems: problems.list, path });
+    }
+    return { path, project, items: items };
+}
+export async function readItemsManifest(project, file) {
+    const path = file ? resolve(project, file) : join(project, ITEMS_MANIFEST_FILE);
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch {
+        throw new BuildToolError("items_manifest_missing", `There is no ${ITEMS_MANIFEST_FILE} at ${path}.`, `Recovery: write ${ITEMS_MANIFEST_FILE} in the project root ({"schema": "${ITEMS_MANIFEST_SCHEMA}", "items": [...]}), then call again.`);
+    }
+    let document;
+    try {
+        document = JSON.parse(text);
+    }
+    catch (error) {
+        throw new BuildToolError("items_manifest_invalid", `${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}.`, "Recovery: fix the JSON and call again.");
+    }
+    return parseItemsManifest(project, document, path);
+}

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

@@ -159,8 +159,8 @@ export declare const measureArgsSchema: z.ZodObject<{
     scenePath: string;
     mode?: "pair" | "plane" | undefined;
     a?: string | undefined;
-    space?: "local" | "world" | undefined;
     b?: string | undefined;
+    space?: "local" | "world" | undefined;
     nodes?: string[] | undefined;
     axis?: "y" | "z" | "x" | undefined;
     tolerance?: number | undefined;
@@ -178,8 +178,8 @@ export declare const raycastArgsSchema: z.ZodObject<{
     evidence: z.ZodDefault<z.ZodOptional<z.ZodEnum<["auto", "physics", "visual_aabb"]>>>;
     exclude: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, "many">>;
 }, "strip", z.ZodTypeAny, {
-    scenePath: string;
     origin: [number, number, number];
+    scenePath: string;
     direction: [number, number, number];
     evidence: "auto" | "physics" | "visual_aabb";
     maxDistance: number;
@@ -187,8 +187,8 @@ export declare const raycastArgsSchema: z.ZodObject<{
     collideWithAreas: boolean;
     exclude?: string[] | undefined;
 }, {
-    scenePath: string;
     origin: [number, number, number];
+    scenePath: string;
     direction: [number, number, number];
     evidence?: "auto" | "physics" | "visual_aabb" | undefined;
     maxDistance?: number | undefined;
@@ -222,9 +222,9 @@ export declare const placeAdjacentArgsSchema: z.ZodObject<{
     }>]>>>;
     space: z.ZodDefault<z.ZodOptional<z.ZodEnum<["world", "local"]>>>;
 }, "strip", z.ZodTypeAny, {
+    reference: string;
     scenePath: string;
     space: "local" | "world";
-    reference: string;
     subject: string;
     axis: "y" | "z" | "x";
     side: "min" | "max";
@@ -235,8 +235,8 @@ export declare const placeAdjacentArgsSchema: z.ZodObject<{
         x?: "none" | "min" | "max" | "center" | undefined;
     };
 }, {
-    scenePath: string;
     reference: string;
+    scenePath: string;
     subject: string;
     axis: "y" | "z" | "x";
     side: "min" | "max";
@@ -371,8 +371,8 @@ export declare const repeatAlongArgsSchema: z.ZodObject<{
     scale: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
     namePrefix: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
 }, "strip", z.ZodTypeAny, {
-    scenePath: string;
     template: string;
+    scenePath: string;
     parent: string;
     start: [number, number, number];
     align: "end" | "start" | "center";
@@ -384,8 +384,8 @@ export declare const repeatAlongArgsSchema: z.ZodObject<{
     rotationDegrees?: [number, number, number] | undefined;
     namePrefix?: string | undefined;
 }, {
-    scenePath: string;
     template: string;
+    scenePath: string;
     parent: string;
     start: [number, number, number];
     end?: [number, number, number] | undefined;

package/dist/core/capabilities/projects-local.d.ts

@@ -0,0 +1,68 @@
+import type { EngineApiClient } from "../api-client.js";
+import { type EngineSelection } from "../engine.js";
+import { type SelfStartDeps } from "../engine-self-start.js";
+/** The starter project when no template is named (the same as `summer dev`). */
+export declare const LOCAL_DEFAULT_TEMPLATE = "3d-basic";
+/** A failure the caller can fix: `code` is the answer's error code,
+ *  `recovery` its one next step, `reason` the install's own code when an install failed. */
+export declare class LocalProjectError extends Error {
+    readonly code: "invalid_input" | "not_found" | "unavailable" | "conflict" | "unsupported";
+    readonly recovery: string;
+    readonly reason?: string | undefined;
+    constructor(code: "invalid_input" | "not_found" | "unavailable" | "conflict" | "unsupported", message: string, recovery: string, reason?: string | undefined);
+}
+/** `{ok:false, code, error, recovery}`, the shape every face prints. */
+export declare function localProjectFailure(error: LocalProjectError): Record<string, unknown>;
+/**
+ * Where a new project goes when no folder is named. Next to the project the
+ * session is in (never inside another project); else the session's folder
+ * when it is a folder of the person's own inside home (not home itself, not
+ * an app's folder: chat apps start their server in an install or app-data
+ * folder, or in / or home); else ~/Documents/Summer.
+ */
+export declare function defaultProjectParent(cwd: string, home?: string): string;
+export interface CreateLocalInput {
+    template?: string;
+    name?: string;
+    dir?: string;
+}
+export interface CreatedLocalProject {
+    ok: true;
+    projectPath: string;
+    /** The template it was made from; null when a project was already there. */
+    template: string | null;
+    created: boolean;
+    next: {
+        op: "projects.open_local";
+        input: {
+            path: string;
+        };
+    };
+}
+/** Write a new project from a template; a folder that already holds one is left as it is. */
+export declare function createLocalProject(input: CreateLocalInput, cwd?: string, waitMs?: number): Promise<CreatedLocalProject>;
+export interface OpenLocalInput {
+    path?: string;
+    install?: boolean;
+}
+export interface OpenedLocalProject {
+    ok: true;
+    projectPath: string;
+    engineVersion: string | null;
+    /** `summer preview`'s address, and the .claude/launch.json that registers it for Claude Code Desktop (null: not written). */
+    preview: {
+        url: string;
+        launchJson: string | null;
+    };
+    next: string;
+}
+/**
+ * Open a project in Summer Engine and wait until it connects (core/engine-self-start.ts):
+ * an editor that already has it is used as it is. Throws LocalProjectError
+ * when there is no project, EngineNotRunningError with the next step otherwise.
+ */
+export declare function openLocalProject(input: OpenLocalInput, selection: EngineSelection | undefined, deps?: SelfStartDeps, 
+/** The MCP binds its session to the opened project with the connected client. */
+onOpen?: (projectRoot: string, client: EngineApiClient) => void, 
+/** The folder the agent session runs in: its .claude/launch.json gets summer-preview. */
+sessionFolder?: string): Promise<OpenedLocalProject>;

package/dist/core/capabilities/projects-local.js

@@ -0,0 +1,172 @@
+/**
+ * projects.create_local and projects.open_local: `summer dev` for agents
+ * with no shell (Claude Desktop, chat apps). create_local writes a project
+ * from a template to this computer; open_local opens a project in Summer
+ * Engine and waits until it connects, installing the engine first only when
+ * the person said yes (install: true). Both run in this package; the cloud
+ * projects.create makes a plan on Summer's server instead.
+ */
+import { existsSync, statSync } from "fs";
+import { homedir } from "os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "path";
+import { findProjectRoot } from "../engine.js";
+import { EngineInstallError } from "../engine-install.js";
+import { openProjectInEditor, sessionProject } from "../engine-self-start.js";
+import { createProject, isEmptyProjectFolder, projectRootAbove } from "../local-project.js";
+import { PREVIEW_URL, registerPreview } from "../preview/launch-config.js";
+import { getTemplateRegistry, resolveTemplate } from "../templates.js";
+import { settlesWithin } from "../util/sleep.js";
+/** The starter project when no template is named (the same as `summer dev`). */
+export const LOCAL_DEFAULT_TEMPLATE = "3d-basic";
+const DEFAULT_NAME = "my-game";
+/** A failure the caller can fix: `code` is the answer's error code,
+ *  `recovery` its one next step, `reason` the install's own code when an install failed. */
+export class LocalProjectError extends Error {
+    code;
+    recovery;
+    reason;
+    constructor(code, message, recovery, reason) {
+        super(message);
+        this.code = code;
+        this.recovery = recovery;
+        this.reason = reason;
+        this.name = "LocalProjectError";
+    }
+}
+/** `{ok:false, code, error, recovery}`, the shape every face prints. */
+export function localProjectFailure(error) {
+    return { ok: false, code: error.code, error: error.message, recovery: error.recovery, ...(error.reason ? { reason: error.reason } : {}) };
+}
+/** An approved install that failed, with its own reason (disk_space, download, ...). */
+function installFailure(error) {
+    const code = { unsupported_platform: "unsupported", app_running: "conflict" }[error.reason] ?? "unavailable";
+    return new LocalProjectError(code, "Summer Engine could not be installed.", error.message, error.reason);
+}
+/** App folders a chat app may start its server in: never a place for a game. */
+const APP_FOLDERS = /(^|[\\/])(AppData|Library|\.config|\.local|Program Files( \(x86\))?|WindowsApps)([\\/]|$)/i;
+/**
+ * Where a new project goes when no folder is named. Next to the project the
+ * session is in (never inside another project); else the session's folder
+ * when it is a folder of the person's own inside home (not home itself, not
+ * an app's folder: chat apps start their server in an install or app-data
+ * folder, or in / or home); else ~/Documents/Summer.
+ */
+export function defaultProjectParent(cwd, home = homedir()) {
+    const dir = resolve(cwd);
+    const enclosing = projectRootAbove(dir, home);
+    if (enclosing)
+        return dirname(enclosing);
+    const inHome = relative(resolve(home), dir);
+    if (inHome && !inHome.startsWith("..") && !isAbsolute(inHome) && !APP_FOLDERS.test(inHome))
+        return dir;
+    return join(resolve(home), "Documents", "Summer");
+}
+/** With no name, a new game never reuses a folder: my-game, then my-game-2, my-game-3, ...
+ *  (a download this process is still running keeps its folder). */
+function freeDefaultFolder(parent, base) {
+    for (let n = 1;; n++) {
+        const dir = join(parent, n === 1 ? base : `${base}-${n}`);
+        if (creating.has(dir) || !existsSync(dir) || (statSync(dir).isDirectory() && isEmptyProjectFolder(dir) && !existsSync(join(dir, "project.godot"))))
+            return dir;
+    }
+}
+/** Projects being written by this process, by folder: a slow template download outlives one tool call. */
+const creating = new Map();
+/** One call waits this long for a template download, then answers "still creating". */
+const CREATE_WAIT_MS = 40_000;
+/** The error for a folder that cannot be written, a full disk, or the template fetch. */
+function createFailure(error, dir) {
+    const code = error.code;
+    if (code === "EACCES" || code === "EPERM" || code === "EROFS") {
+        return new LocalProjectError("invalid_input", `Cannot write to ${dir} (${code}).`, "Pass dir: a folder you can write to, e.g. ~/Documents/Summer/my-game.");
+    }
+    if (code === "ENOSPC")
+        return new LocalProjectError("unavailable", `The disk is full (${dir}).`, "Free up space, then call again.");
+    return new LocalProjectError("unavailable", `Could not create the project: ${error.message}`, "Check the network, then call again.");
+}
+/** Write a new project from a template; a folder that already holds one is left as it is. */
+export async function createLocalProject(input, cwd = process.cwd(), waitMs = CREATE_WAIT_MS) {
+    const entries = getTemplateRegistry();
+    const asked = input.template?.trim() || LOCAL_DEFAULT_TEMPLATE;
+    const resolution = resolveTemplate(asked, entries);
+    if (resolution.kind !== "match") {
+        const which = resolution.kind === "ambiguous" ? resolution.candidates : entries.filter((entry) => entry.status !== "deprecated");
+        throw new LocalProjectError("invalid_input", `${resolution.kind === "ambiguous" ? `'${asked}' matches several templates` : `No template matches '${asked}'`}.`, `Pass one of: ${which.map((entry) => entry.slug).join(", ")}.`);
+    }
+    const entry = resolution.entry;
+    const name = input.name?.trim();
+    if (name && (/[\\/]/.test(name) || name === "." || name === "..")) {
+        throw new LocalProjectError("invalid_input", `name is the project's name, not a path: '${name}'.`, "Put the folder in dir.");
+    }
+    const askedDir = input.dir?.trim().replace(/^~(?=$|[\\/])/, homedir());
+    const dir = askedDir ? resolve(cwd, askedDir) : name ? join(defaultProjectParent(cwd), name) : freeDefaultFolder(defaultProjectParent(cwd), input.template ? entry.slug : DEFAULT_NAME);
+    const next = { op: "projects.open_local", input: { path: dir } };
+    // A call that timed out left the download running: wait for it again, never start a second one.
+    let job = creating.get(dir);
+    if (!job) {
+        if (existsSync(join(dir, "project.godot")))
+            return { ok: true, projectPath: dir, template: null, created: false, next };
+        const around = projectRootAbove(dirname(dir));
+        if (around) {
+            throw new LocalProjectError("invalid_input", `${dir} is inside the project ${around}.`, `Pass dir: a folder outside it, e.g. ${join(dirname(around), basename(dir))}.`);
+        }
+        if (existsSync(dir) && (!statSync(dir).isDirectory() || !isEmptyProjectFolder(dir))) {
+            throw new LocalProjectError("invalid_input", `${dir} has files but no project.godot.`, "Pass dir: a new folder, or an empty one.");
+        }
+        job = createProject(entry, dir, { name: name || basename(dir), log: () => { } }).then(() => ({ ok: true, projectPath: dir, template: entry.slug, created: true, next }), (error) => {
+            throw createFailure(error, dir);
+        });
+        job.catch(() => undefined);
+        creating.set(dir, job);
+    }
+    const done = await settlesWithin(job, waitMs);
+    if (!done) {
+        throw new LocalProjectError("unavailable", `Still creating ${dir} (downloading the template).`, "Call projects.create_local again in 30 seconds with the same input.");
+    }
+    creating.delete(dir);
+    return job;
+}
+/**
+ * Open a project in Summer Engine and wait until it connects (core/engine-self-start.ts):
+ * an editor that already has it is used as it is. Throws LocalProjectError
+ * when there is no project, EngineNotRunningError with the next step otherwise.
+ */
+export async function openLocalProject(input, selection, deps = {}, 
+/** The MCP binds its session to the opened project with the connected client. */
+onOpen, 
+/** The folder the agent session runs in: its .claude/launch.json gets summer-preview. */
+sessionFolder = process.cwd()) {
+    const asked = input.path?.trim();
+    const root = asked ? await findProjectRoot(resolve(selection?.cwd ?? process.cwd(), asked)) : await sessionProject(selection);
+    if (!root) {
+        throw new LocalProjectError("not_found", asked ? `Project not found: no project.godot at or above ${asked}.` : "Project not found: this session has no project.", "Make one with projects.create_local, then pass its projectPath as path.");
+    }
+    let client;
+    try {
+        client = await openProjectInEditor(root, { cwd: root }, { install: input.install === true }, deps);
+    }
+    catch (error) {
+        if (error instanceof EngineInstallError)
+            throw installFailure(error);
+        throw error;
+    }
+    onOpen?.(root, client);
+    // Claude Code Desktop's Browser pane shows the game from the session's launch.json (only adds; never in home).
+    let launchJson = null;
+    try {
+        const written = registerPreview(sessionFolder, root);
+        if (written && written.status !== "skipped")
+            launchJson = written.path;
+    }
+    catch {
+        // the game still opened; the preview is optional
+    }
+    return {
+        ok: true,
+        projectPath: root,
+        engineVersion: client.getEngineVersion() ?? null,
+        preview: { url: PREVIEW_URL, launchJson },
+        next: `Call summer_get_project_context, then build the scene. See the game at ${PREVIEW_URL}: ` +
+            "Claude Code Desktop's Browser pane starts it; elsewhere run: npx -y summer-engine@latest preview --open",
+    };
+}

package/dist/core/capabilities/publish-build.d.ts

@@ -6,7 +6,7 @@ export interface PublishBuildInput {
     /** Exported .zip. Defaults to the last summer_export_game result. */
     file?: string;
     clientVersion?: string;
-    /** Also approve the Build for players (needs a game that passed review). */
+    /** Also make the Build available to players (summer_go_live does this and the release in one step). */
     publish?: boolean;
     /**
      * A web build or native download (summer_export_game format "download"):
@@ -30,9 +30,10 @@ export interface Store {
     call<T = Record<string, unknown>>(method: string, path: string, options?: {
         body?: unknown;
         key?: string;
+        headers?: Record<string, string>;
     }): Promise<T>;
 }
-export declare function storeError(status: number, code: string, message: string | undefined, requestId?: string): BuildToolError;
+export declare function storeError(status: number, code: string, message: string | undefined, requestId?: string, detail?: Record<string, unknown>): BuildToolError;
 export declare function createStore(baseUrl: string, token: string, deps: PublishBuildDependencies): Store;
 /** Whole-file and per-part SHA-256 ("sha256:<hex>") in one pass. */
 export declare function hashParts(path: string, partSize: number): Promise<{
@@ -61,6 +62,9 @@ export declare function uploadParts(sign: (partNumbers: number[]) => Promise<Gra
     partCount: number;
 }, deps: PublishBuildDependencies, parts?: number[]): Promise<void>;
 export declare function normalizeClientVersion(value?: string): string;
+/** gameId is required: the error carries the person's games, or why the store did not list them. */
+export declare function listGamesOrThrow(deps: PublishBuildDependencies): Promise<never>;
+export declare function storeToken(deps: PublishBuildDependencies): Promise<string>;
 /**
  * Before the person confirms, prove the target is real: the game exists for
  * this account, and its store page lists the platforms the export targets.
@@ -74,6 +78,13 @@ export declare function checkStoreGame(gameId: string, exportTargets: string[],
     };
     warnings: string[];
 }>;
+/**
+ * Why the platform did not take a Build to players when asked: the Game's
+ * approval state as the platform reports it. Staff review is becoming a
+ * step after launch, so a pending review is reported as Summer's hold, not
+ * as something the creator waits on or fixes.
+ */
+export declare function platformHold(store: Store, gameId: string): Promise<Record<string, unknown>>;
 export type PublishBuildResult = Record<string, unknown> & {
     ok: true;
     status: string;