summer-engine 4.3.0 → 4.5.0

package/dist/core/ops/save-files.js

@@ -5,6 +5,7 @@ import { copyFile, link, mkdir, open, readdir, readFile, stat, unlink } from "no
 import { BlockList, isIP } from "node:net";
 import { homedir } from "node:os";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { cloudinaryOgvUrl, isConvertibleVideo } from "../capabilities/video-ogv.js";
 /**
  * Generated files on this machine (4.0). The generate operations, assets.get
  * and jobs.wait take `out` here: a folder or a file path. This package keeps
@@ -42,7 +43,7 @@ const DOWNLOAD_TIMEOUT_MS = 120_000;
 export const MAX_DOWNLOAD_BYTES = 500 * 1024 * 1024;
 const MAX_REDIRECTS = 5;
 /** The file types a save writes: media and models, never code or a library a game engine would load. */
-const ALLOWED_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif", ".mp3", ".wav", ".ogg", ".mp4", ".webm", ".glb", ".gltf", ".fbx", ".obj"]);
+const ALLOWED_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif", ".mp3", ".wav", ".ogg", ".mp4", ".webm", ".ogv", ".glb", ".gltf", ".fbx", ".obj"]);
 const EXTENSIONS = {
     "image/png": ".png",
     "image/jpeg": ".jpg",
@@ -55,6 +56,7 @@ const EXTENSIONS = {
     "audio/ogg": ".ogg",
     "video/mp4": ".mp4",
     "video/webm": ".webm",
+    "video/ogg": ".ogv",
     "model/gltf-binary": ".glb",
     "model/gltf+json": ".gltf",
 };
@@ -120,6 +122,12 @@ function holdersOf(result) {
     const list = [...(Array.isArray(record.assets) ? record.assets : []), record.asset, record];
     return list.map(asRecord).filter((holder) => holder !== null && urlOf(holder) !== undefined);
 }
+/** A video file Summer Engine cannot load as is (mime type, file name or URL). */
+function isVideoHolder(holder, url) {
+    if (text(holder.mimeType)?.toLowerCase().startsWith("video/"))
+        return true;
+    return [text(holder.fileName), url].some((name) => name !== undefined && isConvertibleVideo({ url: name }));
+}
 function withWarnings(answer, warnings) {
     return answer.ok && warnings.length ? { ...answer, warnings: [...(answer.warnings ?? []), ...warnings] } : answer;
 }
@@ -287,18 +295,24 @@ export class FileSaver {
             return withWarnings(answer, [target.error]);
         const copy = structuredClone(answer);
         const warnings = [];
+        // Summer Engine plays video only as Ogg Theora: in a Godot project a stored video saves as its .ogv rendition.
+        const godot = (await findGameProject(target.dir))?.engine === "godot";
         // With out the caller asked for a copy there; without it, a file this session already saved is reused.
         const saved = out ? new Map() : this.defaultSaves;
         let first = true;
         for (const holder of holdersOf(resultOf(copy))) {
-            const url = urlOf(holder);
+            const original = urlOf(holder);
+            const ogv = godot && isVideoHolder(holder, original) ? cloudinaryOgvUrl(text(holder.fileUrl) ?? original) : null;
+            const url = ogv ?? original;
             const known = saved.get(url);
             if (known && (await isFile(known))) {
                 holder.localPath = known;
                 continue;
             }
             try {
-                const path = await this.download(url, holder, target, first, warnings);
+                const path = await this.download(url, holder, target, first, warnings, ogv ? ".ogv" : undefined);
+                if (ogv)
+                    warnings.push(`Saved as ${path}: Summer Engine plays video only as Ogg Theora (.ogv).`);
                 first = false;
                 saved.set(url, path);
                 holder.localPath = path;
@@ -340,15 +354,15 @@ export class FileSaver {
         return folder ? { dir: path } : { dir: dirname(path), file: basename(path) };
     }
     /** Download one file into the target under a free name; notes what changed from the caller's file name. */
-    async download(url, holder, target, first, warnings) {
+    async download(url, holder, target, first, warnings, forcedExt) {
         const { temp, finalUrl, contentType } = await this.fetchToTemp(url, target.dir);
         try {
-            const detected = allowed(extname(text(holder.fileName) ?? "")) ?? allowed(extname(finalUrl.pathname)) ?? EXTENSIONS[contentType ?? ""] ?? EXTENSIONS[text(holder.mimeType) ?? ""] ?? ".bin";
+            const detected = forcedExt ?? allowed(extname(text(holder.fileName) ?? "")) ?? allowed(extname(finalUrl.pathname)) ?? EXTENSIONS[contentType ?? ""] ?? EXTENSIONS[text(holder.mimeType) ?? ""] ?? ".bin";
             if (target.file) {
                 const asked = extname(target.file);
-                const ext = allowed(asked) ?? detected;
+                const ext = forcedExt ?? allowed(asked) ?? detected;
                 const path = await claimName(temp, target.dir, basename(target.file, asked), ext);
-                const wanted = join(target.dir, target.file);
+                const wanted = join(target.dir, forcedExt ? `${basename(target.file, asked)}${forcedExt}` : target.file);
                 if (first && path !== wanted) {
                     warnings.push(allowed(asked) ? `${wanted} already exists, so the file was saved as ${path}.` : `out: ${asked || "no extension"} is not a media or model file type, so the file was saved as ${path}.`);
                 }
@@ -362,52 +376,55 @@ export class FileSaver {
             await unlink(temp).catch(() => undefined);
         }
     }
-    /** The file in a hidden temp file in `dir` (engines skip dot files), from a public https host, within the size limit. */
-    async fetchToTemp(url, dir) {
-        const lookupHost = this.options.lookup ?? lookupAll;
-        const fetchFile = this.options.fetch ?? fetch;
-        let current = await publicHttps(url, lookupHost);
-        let response;
-        for (let hops = 0;; hops++) {
-            response = await fetchFile(current.href, { redirect: "manual", signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
-            const location = response.headers.get("location");
-            if (response.status < 300 || response.status >= 400 || !location)
-                break;
-            await response.body?.cancel().catch(() => undefined);
-            if (hops >= MAX_REDIRECTS)
-                throw new Error("the download redirected too many times");
-            current = await publicHttps(new URL(location, current).href, lookupHost);
-        }
-        if (!response.ok)
-            throw new Error(`the download answered HTTP ${response.status}`);
-        if (response.url)
-            current = await publicHttps(response.url, lookupHost);
-        const maxBytes = this.options.maxBytes ?? MAX_DOWNLOAD_BYTES;
-        const limit = maxBytes >= 1024 * 1024 ? `${Math.floor(maxBytes / 1024 / 1024)} MB` : `${maxBytes} bytes`;
-        if (Number(response.headers.get("content-length") ?? 0) > maxBytes)
-            throw new Error(`the file is larger than ${limit}`);
-        await mkdir(dir, { recursive: true });
-        const temp = join(dir, `.summer-download-${randomBytes(6).toString("hex")}.part`);
-        const handle = await open(temp, "wx");
-        try {
-            let size = 0;
-            if (response.body) {
-                for await (const chunk of response.body) {
-                    size += chunk.byteLength;
-                    if (size > maxBytes)
-                        throw new Error(`the file is larger than ${limit}`);
-                    await handle.write(chunk);
-                }
+    fetchToTemp(url, dir) {
+        return fetchPublicToTemp(url, dir, this.options);
+    }
+}
+/** The file in a hidden temp file in `dir` (engines skip dot files), from a public https host, within the size limit. */
+export async function fetchPublicToTemp(url, dir, options = {}) {
+    const lookupHost = options.lookup ?? lookupAll;
+    const fetchFile = options.fetch ?? fetch;
+    let current = await publicHttps(url, lookupHost);
+    let response;
+    for (let hops = 0;; hops++) {
+        response = await fetchFile(current.href, { redirect: "manual", signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+        const location = response.headers.get("location");
+        if (response.status < 300 || response.status >= 400 || !location)
+            break;
+        await response.body?.cancel().catch(() => undefined);
+        if (hops >= MAX_REDIRECTS)
+            throw new Error("the download redirected too many times");
+        current = await publicHttps(new URL(location, current).href, lookupHost);
+    }
+    if (!response.ok)
+        throw new Error(`the download answered HTTP ${response.status}`);
+    if (response.url)
+        current = await publicHttps(response.url, lookupHost);
+    const maxBytes = options.maxBytes ?? MAX_DOWNLOAD_BYTES;
+    const limit = maxBytes >= 1024 * 1024 ? `${Math.floor(maxBytes / 1024 / 1024)} MB` : `${maxBytes} bytes`;
+    if (Number(response.headers.get("content-length") ?? 0) > maxBytes)
+        throw new Error(`the file is larger than ${limit}`);
+    await mkdir(dir, { recursive: true });
+    const temp = join(dir, `.summer-download-${randomBytes(6).toString("hex")}.part`);
+    const handle = await open(temp, "wx");
+    try {
+        let size = 0;
+        if (response.body) {
+            for await (const chunk of response.body) {
+                size += chunk.byteLength;
+                if (size > maxBytes)
+                    throw new Error(`the file is larger than ${limit}`);
+                await handle.write(chunk);
             }
-            await handle.close();
-        }
-        catch (error) {
-            await handle.close().catch(() => undefined);
-            await unlink(temp).catch(() => undefined);
-            throw error;
         }
-        return { temp, finalUrl: current, contentType: response.headers.get("content-type")?.split(";")[0].trim() };
+        await handle.close();
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        await unlink(temp).catch(() => undefined);
+        throw error;
     }
+    return { temp, finalUrl: current, contentType: response.headers.get("content-type")?.split(";")[0].trim() };
 }
 /** ops.describe of an operation that takes `out`: its input shows `out` too. */
 function describedWithOut(answer) {

package/dist/core/ops/search.js

@@ -16,7 +16,9 @@ import { stem } from "../registry-search.js";
  *   action the query names gains a quarter: "publish" is store.publish
  *   before store.cancel_publish.
  * - A title or tag the query says nearly word for word, articles aside
- *   ("how is my game doing" for "how did my game do"), adds 2 per word.
+ *   ("how is my game doing" for "how did my game do"), adds 2 per word, and
+ *   4 when the query is the title exactly: "list my games" is games.list
+ *   ("List my games") before content.list_games ("List the team's games").
  */
 const STOP = new Set([
     "a", "an", "the", "my", "of", "for", "to", "in", "on", "and", "or", "with", "is", "it", "me", "i", "please", "how", "do", "what",
@@ -130,6 +132,11 @@ function phraseBonus(entry, all) {
     }
     return bonus;
 }
+/** The query is the row's title word for word, articles included: "list my games" for "List my games". */
+function saysTitle(entry, all) {
+    const title = tokens(entry.title);
+    return title.length === all.length && title.every((word, index) => word.normed === all[index].normed);
+}
 /**
  * The query names the row's whole action, and its area too when the action
  * is only an everyday verb: "list my games" names games.list, "run my game"
@@ -167,7 +174,7 @@ function scoreAll(entries, query) {
         });
         if (total === 0)
             return 0;
-        return total * (0.5 + (0.5 * strong) / terms.length) * (!missed && namesAction(entry, terms) ? 1.25 : 1) + phraseBonus(entry, all);
+        return total * (0.5 + (0.5 * strong) / terms.length) * (!missed && namesAction(entry, terms) ? 1.25 : 1) + phraseBonus(entry, all) * (saysTitle(entry, all) ? 2 : 1);
     });
 }
 const STATUS_RANK = { stable: 0, preview: 1, deprecated: 2 };

package/dist/core/preview/input.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Browser input -> the running game's input, for `summer preview`. The page
+ * sends what the person (or the agent's browser) did on the frame; this turns
+ * it into SimulateInputScript events (core/capabilities/runtime-control.ts),
+ * the same op summer_game_input sends.
+ *
+ * Keys: KeyboardEvent.code (the physical key) -> Godot's Key enum, sent as
+ * keycode AND physical_keycode so an InputMap action bound either way fires.
+ * Godot names letters by their upper-case code point and the special keys
+ * SPECIAL (1 << 22) | n (core/os/keyboard.h). Clicks: frame pixels scaled to
+ * the game window's own size (the engine downscales the frames it sends).
+ */
+export type PreviewInput = {
+    kind: "key";
+    code: string;
+    pressed: boolean;
+} | {
+    kind: "click";
+    x: number;
+    y: number;
+    button?: number;
+};
+/** Godot Key enum value for a KeyboardEvent.code, or null when unmapped. */
+export declare function godotKeycode(code: string): number | null;
+/** Frame size and the game window size it was scaled from. */
+export interface FrameGeometry {
+    width: number;
+    height: number;
+    sourceWidth?: number;
+    sourceHeight?: number;
+}
+/** One SimulateInputScript event, or null for input the game cannot take. */
+export declare function engineInputEvent(input: PreviewInput, frame: FrameGeometry | null): Record<string, unknown> | null;
+/** Parse the page's POST body: {inputs: PreviewInput[]} (at most 64). */
+export declare function parsePreviewInputs(body: unknown): PreviewInput[] | null;

package/dist/core/preview/input.js

@@ -0,0 +1,105 @@
+/**
+ * Browser input -> the running game's input, for `summer preview`. The page
+ * sends what the person (or the agent's browser) did on the frame; this turns
+ * it into SimulateInputScript events (core/capabilities/runtime-control.ts),
+ * the same op summer_game_input sends.
+ *
+ * Keys: KeyboardEvent.code (the physical key) -> Godot's Key enum, sent as
+ * keycode AND physical_keycode so an InputMap action bound either way fires.
+ * Godot names letters by their upper-case code point and the special keys
+ * SPECIAL (1 << 22) | n (core/os/keyboard.h). Clicks: frame pixels scaled to
+ * the game window's own size (the engine downscales the frames it sends).
+ */
+const SPECIAL = 1 << 22;
+const NAMED_KEYS = {
+    Escape: SPECIAL | 0x01,
+    Tab: SPECIAL | 0x02,
+    Backspace: SPECIAL | 0x04,
+    Enter: SPECIAL | 0x05,
+    NumpadEnter: SPECIAL | 0x06,
+    Insert: SPECIAL | 0x07,
+    Delete: SPECIAL | 0x08,
+    Home: SPECIAL | 0x0d,
+    End: SPECIAL | 0x0e,
+    ArrowLeft: SPECIAL | 0x0f,
+    ArrowUp: SPECIAL | 0x10,
+    ArrowRight: SPECIAL | 0x11,
+    ArrowDown: SPECIAL | 0x12,
+    PageUp: SPECIAL | 0x13,
+    PageDown: SPECIAL | 0x14,
+    ShiftLeft: SPECIAL | 0x15,
+    ShiftRight: SPECIAL | 0x15,
+    ControlLeft: SPECIAL | 0x16,
+    ControlRight: SPECIAL | 0x16,
+    MetaLeft: SPECIAL | 0x17,
+    MetaRight: SPECIAL | 0x17,
+    AltLeft: SPECIAL | 0x18,
+    AltRight: SPECIAL | 0x18,
+    CapsLock: SPECIAL | 0x19,
+    Space: 32,
+    Quote: 39,
+    Comma: 44,
+    Minus: 45,
+    Period: 46,
+    Slash: 47,
+    Semicolon: 59,
+    Equal: 61,
+    BracketLeft: 91,
+    Backslash: 92,
+    BracketRight: 93,
+    Backquote: 96,
+};
+/** Godot Key enum value for a KeyboardEvent.code, or null when unmapped. */
+export function godotKeycode(code) {
+    const letter = /^Key([A-Z])$/.exec(code);
+    if (letter)
+        return letter[1].charCodeAt(0);
+    const digit = /^Digit([0-9])$/.exec(code);
+    if (digit)
+        return digit[1].charCodeAt(0);
+    const fn = /^F([1-9]|1[0-2])$/.exec(code);
+    if (fn)
+        return SPECIAL | (0x1c + Number(fn[1]) - 1);
+    return NAMED_KEYS[code] ?? null;
+}
+/** One SimulateInputScript event, or null for input the game cannot take. */
+export function engineInputEvent(input, frame) {
+    if (input.kind === "key") {
+        const keycode = godotKeycode(input.code);
+        if (keycode === null)
+            return null;
+        return { type: "key", keycode, physical_keycode: keycode, pressed: input.pressed !== false };
+    }
+    if (!frame || !Number.isFinite(input.x) || !Number.isFinite(input.y))
+        return null;
+    if (input.x < 0 || input.y < 0 || input.x > frame.width || input.y > frame.height)
+        return null;
+    const scaleX = frame.sourceWidth && frame.width ? frame.sourceWidth / frame.width : 1;
+    const scaleY = frame.sourceHeight && frame.height ? frame.sourceHeight / frame.height : 1;
+    const button = input.button === 2 || input.button === 3 ? input.button : 1;
+    return {
+        type: "mouse_click",
+        position: [Math.round(input.x * scaleX), Math.round(input.y * scaleY)],
+        button,
+    };
+}
+/** Parse the page's POST body: {inputs: PreviewInput[]} (at most 64). */
+export function parsePreviewInputs(body) {
+    const inputs = body?.inputs;
+    if (!Array.isArray(inputs) || inputs.length === 0 || inputs.length > 64)
+        return null;
+    const out = [];
+    for (const item of inputs) {
+        const record = item;
+        if (record?.kind === "key" && typeof record.code === "string") {
+            out.push({ kind: "key", code: record.code, pressed: record.pressed !== false });
+        }
+        else if (record?.kind === "click" && typeof record.x === "number" && typeof record.y === "number") {
+            out.push({ kind: "click", x: record.x, y: record.y, button: typeof record.button === "number" ? record.button : 1 });
+        }
+        else {
+            return null;
+        }
+    }
+    return out;
+}

package/dist/core/preview/launch-config.d.ts

@@ -0,0 +1,52 @@
+export declare const PREVIEW_LAUNCH_NAME = "summer-preview";
+export declare const DEFAULT_PREVIEW_PORT = 5199;
+/** The schema version Desktop writes and documents. */
+export declare const LAUNCH_JSON_VERSION = "0.0.1";
+export interface LaunchEntry {
+    name: string;
+    runtimeExecutable: string;
+    runtimeArgs: string[];
+    port: number;
+    /** Working directory relative to the session folder (Desktop's `cwd`). */
+    cwd?: string;
+}
+/** The entry that starts `summer preview` on `port`, in `cwd` (relative to
+ *  the session folder) when the project is below it. */
+export declare function previewLaunchEntry(port?: number, cwd?: string): LaunchEntry;
+/** The indentation of a JSON text's first indented line (2 when none). */
+export declare function jsonIndent(text: string): string | number;
+export type LaunchConfigResult = {
+    /** created: a new file; added: our entry joined an existing file;
+     *  kept: an entry with our name was already there, nothing written. */
+    status: "created" | "added" | "kept";
+    path: string;
+    entry: LaunchEntry;
+    /** The file's autoVerify after the write (Desktop's default is on). */
+    autoVerify: boolean;
+} | {
+    status: "skipped";
+    path: string;
+    entry: LaunchEntry;
+    reason: string;
+};
+export interface LaunchConfigOptions {
+    /** The entry to add (default previewLaunchEntry()). `summer dev` can pass its own. */
+    entry?: LaunchEntry;
+}
+/**
+ * Add the preview entry to <sessionRoot>/.claude/launch.json, creating the
+ * file when there is none. sessionRoot is the folder Claude Code Desktop's
+ * session starts in. Never overwrites another entry or setting, and never
+ * rewrites a file it cannot parse as plain JSON.
+ */
+export declare function writeClaudeLaunchConfig(sessionRoot: string, options?: LaunchConfigOptions): LaunchConfigResult;
+/** Where `summer preview` serves the running game (Claude Code Desktop opens localhost:<port>). */
+export declare const PREVIEW_URL = "http://localhost:5199";
+/**
+ * Register `summer preview` in <session folder>/.claude/launch.json, so
+ * Claude Code Desktop's Browser pane shows the game as soon as the session
+ * opens (core/preview/launch-config.ts: it only adds). Null when the session
+ * folder is the home folder or a filesystem root (~/.claude is Claude Code's
+ * own config), or the project is neither at, above nor below it.
+ */
+export declare function registerPreview(sessionFolder: string, projectDir: string): LaunchConfigResult | null;

package/dist/core/preview/launch-config.js

@@ -0,0 +1,137 @@
+/**
+ * .claude/launch.json: how Claude Code Desktop's Browser pane finds a local
+ * server to open, screenshot and check (https://code.claude.com/docs/en/desktop,
+ * "Preview", read 2026-10-19):
+ *
+ *   { "version": "0.0.1", "autoVerify": true,
+ *     "configurations": [{ "name", "runtimeExecutable", "runtimeArgs", "port", ... }] }
+ *
+ * The file lives in the folder the session was started in (the caller passes
+ * that folder; an entry whose project sits below it carries `cwd`, relative
+ * to it). autoVerify is a file-level switch and on by default: after each edit Claude screenshots the
+ * page, checks it for errors and fixes what is wrong. The pane opens
+ * http://localhost:<port>. When that port is taken, Desktop picks a free one
+ * and rewrites the `--port` value in runtimeArgs, so the entry passes its port
+ * there and sets no `url` (a localhost url must match the port).
+ *
+ * The writer only adds. Other entries and settings stay as they are, an
+ * existing summer-preview entry is kept as it is (the person may have changed
+ * it), and a file it cannot rewrite without losing something (comments, not
+ * JSON, an unexpected shape) is left alone; the result then carries the entry
+ * to add by hand. A rewrite keeps the file's indentation and replaces the
+ * file in one step (temp file + rename). The Codex app has an in-app browser too, but its docs
+ * describe no file that names a server or a URL, so there is nothing to write
+ * for it.
+ */
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { isHomeOrRoot } from "../local-project.js";
+import { asRecord } from "../util/json.js";
+export const PREVIEW_LAUNCH_NAME = "summer-preview";
+export const DEFAULT_PREVIEW_PORT = 5199;
+/** The schema version Desktop writes and documents. */
+export const LAUNCH_JSON_VERSION = "0.0.1";
+/** The entry that starts `summer preview` on `port`, in `cwd` (relative to
+ *  the session folder) when the project is below it. */
+export function previewLaunchEntry(port = DEFAULT_PREVIEW_PORT, cwd) {
+    return {
+        name: PREVIEW_LAUNCH_NAME,
+        runtimeExecutable: "npx",
+        runtimeArgs: ["-y", "summer-engine@latest", "preview", "--port", String(port)],
+        port,
+        ...(cwd ? { cwd } : {}),
+    };
+}
+/** The indentation of a JSON text's first indented line (2 when none). */
+export function jsonIndent(text) {
+    const match = /^([ \t]+)\S/m.exec(text);
+    if (!match)
+        return 2;
+    return match[1].startsWith("\t") ? "\t" : match[1].length;
+}
+/** Replace `path` in one step, so a reader never sees half a file. */
+function writeAtomic(path, text) {
+    const temp = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(temp, text);
+        renameSync(temp, path);
+    }
+    catch (err) {
+        rmSync(temp, { force: true });
+        throw err;
+    }
+}
+/**
+ * Add the preview entry to <sessionRoot>/.claude/launch.json, creating the
+ * file when there is none. sessionRoot is the folder Claude Code Desktop's
+ * session starts in. Never overwrites another entry or setting, and never
+ * rewrites a file it cannot parse as plain JSON.
+ */
+export function writeClaudeLaunchConfig(sessionRoot, options = {}) {
+    const entry = options.entry ?? previewLaunchEntry();
+    const dir = join(sessionRoot, ".claude");
+    const path = join(dir, "launch.json");
+    if (!existsSync(path)) {
+        mkdirSync(dir, { recursive: true });
+        const file = { version: LAUNCH_JSON_VERSION, autoVerify: true, configurations: [entry] };
+        writeAtomic(path, `${JSON.stringify(file, null, 2)}\n`);
+        return { status: "created", path, entry, autoVerify: true };
+    }
+    const text = readFileSync(path, "utf-8");
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // Desktop accepts comments; rewriting would drop them.
+        const name = entry.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        if (new RegExp(`"name"\\s*:\\s*"${name}"`).test(text)) {
+            return { status: "kept", path, entry, autoVerify: !/"autoVerify"\s*:\s*false/.test(text) };
+        }
+        return {
+            status: "skipped",
+            path,
+            entry,
+            reason: "it has comments or is not plain JSON, so it was not rewritten",
+        };
+    }
+    const file = asRecord(parsed);
+    if (!file || (file.configurations !== undefined && !Array.isArray(file.configurations))) {
+        return { status: "skipped", path, entry, reason: "it is not an object with a configurations list" };
+    }
+    const configurations = file.configurations ?? [];
+    const autoVerifySet = typeof file.autoVerify === "boolean";
+    if (configurations.some((item) => asRecord(item)?.name === entry.name)) {
+        return { status: "kept", path, entry, autoVerify: file.autoVerify !== false };
+    }
+    // A person's explicit autoVerify (on or off) is theirs; only fill it in.
+    const next = { ...file, configurations: [...configurations, entry] };
+    if (!autoVerifySet)
+        next.autoVerify = true;
+    writeAtomic(path, `${JSON.stringify(next, null, jsonIndent(text))}${text.endsWith("\n") ? "\n" : ""}`);
+    return { status: "added", path, entry, autoVerify: next.autoVerify !== false };
+}
+/** Where `summer preview` serves the running game (Claude Code Desktop opens localhost:<port>). */
+export const PREVIEW_URL = `http://localhost:${DEFAULT_PREVIEW_PORT}`;
+/**
+ * Register `summer preview` in <session folder>/.claude/launch.json, so
+ * Claude Code Desktop's Browser pane shows the game as soon as the session
+ * opens (core/preview/launch-config.ts: it only adds). Null when the session
+ * folder is the home folder or a filesystem root (~/.claude is Claude Code's
+ * own config), or the project is neither at, above nor below it.
+ */
+export function registerPreview(sessionFolder, projectDir) {
+    const real = (path) => (existsSync(path) ? realpathSync(path) : resolve(path));
+    const session = real(sessionFolder);
+    const project = real(projectDir);
+    if (isHomeOrRoot(session))
+        return null;
+    const below = relative(session, project);
+    const isBelow = !below.startsWith("..") && !isAbsolute(below);
+    const isAbove = !isBelow && !relative(project, session).startsWith("..") && !isAbsolute(relative(project, session));
+    if (!isBelow && !isAbove)
+        return null;
+    // Below: the preview starts in the project; above: it finds the project from the session folder.
+    const cwd = isBelow && below ? below.split(sep).join("/") : undefined;
+    return writeClaudeLaunchConfig(session, { entry: previewLaunchEntry(DEFAULT_PREVIEW_PORT, cwd) });
+}

package/dist/core/preview/page.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The one page `summer preview` serves. Self-contained: inline style and
+ * script, no fonts, no CDN, no request leaves 127.0.0.1 (the server's
+ * Content-Security-Policy enforces it), and no token anywhere (the server
+ * holds the engine connection).
+ *
+ * Loop: fetch /api/frame, show it, wait the interval the server derived from
+ * the measured capture time, repeat. Hidden tab = no requests. Each frame
+ * response carries the status (x-summer-status) so one request a frame is all
+ * the page makes. The first frame after the page loads or comes back into
+ * view, and the Refresh button, ask for a fresh one (?fresh=1): game frames
+ * are otherwise about 20 s apart, and the header says how old the frame is.
+ * While the game runs, keys and clicks on the frame go to it; a key release is
+ * always sent, so no key stays held in the game. A page framed inside another
+ * page sends no input.
+ *
+ * For agents checking the page: <body data-state> is connecting, no_editor,
+ * editor or game; #status holds the status line; #refresh fetches a fresh
+ * frame; the page logs nothing to the console in normal operation, so a
+ * console error is a real one.
+ */
+export declare const PREVIEW_PAGE_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>Summer preview</title>\n<style>\n  :root { --cobalt: #0047ab; --ink: #111; --muted: #6b6b6b; --line: #e6e6e6; }\n  * { box-sizing: border-box; }\n  html, body { height: 100%; margin: 0; }\n  body { display: flex; flex-direction: column; background: #fff; color: var(--ink);\n    font: 13px/1.4 -apple-system, BlinkMacSystemFont, \"Segoe UI\", system-ui, sans-serif; }\n  header, footer { display: flex; align-items: center; gap: 12px; padding: 8px 14px; min-height: 36px; }\n  header { border-bottom: 1px solid var(--line); }\n  footer { border-top: 1px solid var(--line); color: var(--muted); }\n  .brand { color: var(--cobalt); font-weight: 700; }\n  #project { font-weight: 600; }\n  #scene { color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n  .spacer { flex: 1; }\n  #source { color: #fff; background: var(--cobalt); border-radius: 4px; padding: 1px 8px; font-weight: 600; }\n  #source:empty { display: none; }\n  #rate { color: var(--muted); font-variant-numeric: tabular-nums; }\n  #refresh { font: inherit; color: var(--cobalt); background: #fff; border: 1px solid var(--line); border-radius: 4px; padding: 1px 8px; cursor: pointer; }\n  body[data-state=\"no_editor\"] #refresh, body[data-state=\"connecting\"] #refresh { display: none; }\n  main { flex: 1; min-height: 0; position: relative; display: flex; align-items: center; justify-content: center; outline: none; }\n  #frame { width: 100%; height: 100%; object-fit: contain; display: block; user-select: none; -webkit-user-drag: none; }\n  body[data-state=\"game\"] #frame { cursor: crosshair; }\n  #empty { display: none; text-align: center; max-width: 520px; padding: 24px; }\n  #empty h1 { font-size: 20px; margin: 0 0 8px; }\n  #empty code { display: inline-block; margin-top: 8px; padding: 6px 10px; border: 1px solid var(--line); border-radius: 4px; color: var(--cobalt); }\n  body[data-state=\"no_editor\"] #frame, body[data-state=\"connecting\"] #frame { display: none; }\n  body[data-state=\"no_editor\"] #empty, body[data-state=\"connecting\"] #empty { display: block; }\n  #status { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n</style>\n</head>\n<body data-state=\"connecting\">\n<header>\n  <span class=\"brand\">Summer</span>\n  <span id=\"project\"></span>\n  <span id=\"scene\"></span>\n  <span class=\"spacer\"></span>\n  <span id=\"source\"></span>\n  <span id=\"rate\"></span>\n  <button id=\"refresh\" type=\"button\" title=\"Capture a fresh frame now\">Refresh</button>\n</header>\n<main id=\"stage\" tabindex=\"0\">\n  <img id=\"frame\" alt=\"Live frame from Summer Engine\">\n  <div id=\"empty\">\n    <h1 id=\"empty-title\">Looking for Summer Engine</h1>\n    <div id=\"empty-text\"></div>\n  </div>\n</main>\n<footer><span id=\"status\">Looking for Summer Engine</span></footer>\n<script>\n(() => {\n  const $ = (id) => document.getElementById(id);\n  const frame = $(\"frame\");\n  const stage = $(\"stage\");\n  const framed = window.top !== window.self;\n  let status = null;\n  let timer = null;\n  let loop = 0;\n  let lastUrl = null;\n  let note = null;\n  const shown = [];\n\n  function render() {\n    const s = status;\n    if (!s) return;\n    const message = typeof s.message === \"string\" ? s.message : \"\";\n    document.body.dataset.state = s.state;\n    document.body.dataset.source = s.frame ? s.frame.source : \"\";\n    $(\"project\").textContent = s.project || \"\";\n    $(\"scene\").textContent = s.scene || \"\";\n    $(\"source\").textContent = s.state === \"game\" ? \"Game\" : s.state === \"editor\" ? \"Editor\" : \"\";\n    const now = Date.now();\n    while (shown.length > 2 && now - shown[0] > 12000) shown.shift();\n    const fps = shown.length > 1 ? (shown.length - 1) / ((shown[shown.length - 1] - shown[0]) / 1000) : 0;\n    const rate = [];\n    if (s.frame && s.frame.source === \"game\") rate.push(\"frame \" + Math.max(0, Math.round((now - s.frame.capturedAt) / 1000)) + \" s old\");\n    else if (s.frame && fps) rate.push(fps.toFixed(1) + \" fps\");\n    if (s.frame && s.latencyMs != null) rate.push(s.latencyMs + \" ms per frame\");\n    $(\"rate\").textContent = rate.join(\" \u00B7 \");\n    $(\"status\").textContent = note && now < note.until ? note.text : message;\n    const parts = message.split(\": run \");\n    $(\"empty-title\").textContent = s.state === \"connecting\" ? \"Looking for Summer Engine\" : parts[0];\n    const empty = $(\"empty-text\");\n    empty.textContent = \"\";\n    if (parts[1]) {\n      const code = document.createElement(\"code\");\n      code.textContent = parts[1];\n      empty.append(\"Run this in the project folder:\", document.createElement(\"br\"), code);\n    }\n    document.title = (s.project ? s.project + \" \u00B7 \" : \"\") + \"Summer preview\";\n  }\n\n  async function show(blob) {\n    const url = URL.createObjectURL(blob);\n    const next = new Image();\n    next.src = url;\n    try { await next.decode(); } catch (_) {}\n    frame.src = url;\n    if (lastUrl) URL.revokeObjectURL(lastUrl);\n    lastUrl = url;\n    shown.push(Date.now());\n  }\n\n  function readStatus(value) {\n    return value && typeof value === \"object\" && typeof value.state === \"string\" ? value : null;\n  }\n\n  async function tick(id, fresh) {\n    if (id !== loop || document.hidden) return;\n    const started = performance.now();\n    let wait = 2000;\n    try {\n      const res = await fetch(fresh ? \"/api/frame?fresh=1\" : \"/api/frame\", { cache: \"no-store\" });\n      const header = res.headers.get(\"x-summer-status\");\n      let next = null;\n      if (res.status === 200) {\n        if (header) next = readStatus(JSON.parse(decodeURIComponent(header)));\n        await show(await res.blob());\n      } else {\n        next = readStatus(await res.json().catch(() => null));\n      }\n      if (next) {\n        status = next;\n        wait = status.intervalMs || 2000;\n      }\n    } catch (_) {\n      status = { state: \"no_editor\", message: \"The preview server stopped: run npx -y summer-engine@latest preview\", frame: null };\n    }\n    try { render(); } catch (_) {}\n    if (id !== loop || document.hidden) return;\n    timer = setTimeout(() => tick(id, false), Math.max(0, wait - (performance.now() - started)));\n  }\n\n  function start() {\n    clearTimeout(timer);\n    loop += 1;\n    if (!document.hidden) tick(loop, true);\n  }\n  document.addEventListener(\"visibilitychange\", start);\n  $(\"refresh\").addEventListener(\"click\", start);\n  setInterval(() => { if (!document.hidden) { try { render(); } catch (_) {} } }, 1000);\n\n  function framePoint(event) {\n    const rect = frame.getBoundingClientRect();\n    const w = frame.naturalWidth, h = frame.naturalHeight;\n    if (!w || !h) return null;\n    const scale = Math.min(rect.width / w, rect.height / h);\n    const x = (event.clientX - rect.left - (rect.width - w * scale) / 2) / scale;\n    const y = (event.clientY - rect.top - (rect.height - h * scale) / 2) / scale;\n    return x < 0 || y < 0 || x > w || y > h ? null : { x: x, y: y };\n  }\n\n  function inputOn() {\n    return !framed && status && status.input;\n  }\n\n  // Releases go out even while input is off, so a key never stays held.\n  async function send(inputs, release) {\n    if (framed || (!release && !inputOn())) return;\n    try {\n      const res = await fetch(\"/api/input\", { method: \"POST\", headers: { \"content-type\": \"application/json\" }, body: JSON.stringify({ inputs: inputs }) });\n      const body = await res.json();\n      note = body.ok || release ? null : { text: \"Input not sent: \" + body.error, until: Date.now() + 4000 };\n    } catch (_) {\n      note = { text: \"Input not sent: the preview server did not answer\", until: Date.now() + 4000 };\n    }\n    try { render(); } catch (_) {}\n  }\n\n  frame.addEventListener(\"click\", (event) => {\n    const point = framePoint(event);\n    stage.focus();\n    if (point && status && status.state === \"game\") send([{ kind: \"click\", x: point.x, y: point.y, button: 1 }], false);\n  });\n  frame.addEventListener(\"contextmenu\", (event) => {\n    if (!inputOn() || status.state !== \"game\") return;\n    event.preventDefault();\n    const point = framePoint(event);\n    if (point) send([{ kind: \"click\", x: point.x, y: point.y, button: 2 }], false);\n  });\n  const held = new Set();\n  function onKey(event, pressed) {\n    if (pressed) {\n      if (!inputOn() || event.metaKey) return;\n      event.preventDefault();\n      if (held.has(event.code)) return;\n      held.add(event.code);\n      send([{ kind: \"key\", code: event.code, pressed: true }], false);\n    } else if (held.delete(event.code)) {\n      event.preventDefault();\n      send([{ kind: \"key\", code: event.code, pressed: false }], true);\n    }\n  }\n  stage.addEventListener(\"keydown\", (event) => onKey(event, true));\n  stage.addEventListener(\"keyup\", (event) => onKey(event, false));\n  stage.addEventListener(\"blur\", () => {\n    const codes = Array.from(held);\n    held.clear();\n    if (codes.length) send(codes.map((code) => ({ kind: \"key\", code: code, pressed: false })), true);\n  });\n\n  start();\n})();\n</script>\n</body>\n</html>\n";