summer-engine 2.8.2 → 3.1.0

package/dist/core/capabilities/asset-import.js

@@ -0,0 +1,134 @@
+import { ToolInputError } from "../tool-errors.js";
+/** Kenney Cloudinary URL pattern: .../summer_art/kenney/3d/{pack-slug}/{filename}.glb */
+const KENNEY_URL_PATTERN = /\/kenney\/3d\/([^/]+)\//;
+function getPackSlugFromUrl(fileUrl) {
+    return fileUrl.match(KENNEY_URL_PATTERN)?.[1] ?? null;
+}
+export function buildKenneyTextureUrl(fileUrl) {
+    const lastSlash = fileUrl.lastIndexOf("/");
+    const base = lastSlash >= 0 ? fileUrl.slice(0, lastSlash) : fileUrl;
+    return `${base}/Textures/colormap.png`;
+}
+export async function textureExists(url) {
+    try {
+        const res = await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(5000) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build import entries for Kenney 3D assets: texture first, then GLB.
+ * Pack-scoped paths prevent texture collision (each pack has its own Textures/colormap.png).
+ */
+async function buildKenneyImportEntries(fileUrl, packSlug, fileName) {
+    const textureUrl = buildKenneyTextureUrl(fileUrl);
+    const hasTexture = await textureExists(textureUrl);
+    if (!hasTexture) {
+        return [{ url: fileUrl, path: `res://assets/models/kenney/${packSlug}/${fileName}` }];
+    }
+    const glbPath = `res://assets/models/kenney/${packSlug}/${fileName}`;
+    const glbDir = glbPath.replace(/\/[^/]+$/, "");
+    const texturePath = `${glbDir}/Textures/colormap.png`;
+    return [
+        { url: textureUrl, path: texturePath },
+        { url: fileUrl, path: glbPath },
+    ];
+}
+function fileNameFromUrl(fileUrl) {
+    return fileUrl.split("/").pop()?.split("?")[0] || "asset";
+}
+/** Godot node names reject . : @ / " %; keep letters, digits and underscores. */
+export function sanitizeNodeName(name) {
+    return ((name || "Asset")
+        .replace(/[^\p{L}\p{N}_]+/gu, "_")
+        .replace(/^_+|_+$/g, "") || "Asset");
+}
+async function buildImportEntriesForAsset(asset, targetPath) {
+    const fileUrl = asset.importUrl || asset.fileUrl;
+    if (!fileUrl)
+        throw new Error("Asset has no import URL.");
+    const fileName = targetPath?.split("/").pop() || asset.fileName || fileNameFromUrl(fileUrl);
+    const packSlug = asset.packSlug ?? getPackSlugFromUrl(fileUrl) ?? "misc";
+    if (targetPath) {
+        if (asset.type === "3d_model" && fileUrl.includes("kenney/3d/")) {
+            const textureUrl = buildKenneyTextureUrl(fileUrl);
+            const hasTexture = await textureExists(textureUrl);
+            if (hasTexture) {
+                const glbDir = targetPath.replace(/\/[^/]+$/, "");
+                return {
+                    importPath: targetPath,
+                    imports: [
+                        { url: textureUrl, path: `${glbDir}/Textures/colormap.png` },
+                        { url: fileUrl, path: targetPath },
+                    ],
+                };
+            }
+        }
+        return {
+            importPath: targetPath,
+            imports: [{ url: fileUrl, path: targetPath }],
+        };
+    }
+    if (asset.type === "3d_model" && fileUrl.includes("kenney/3d/")) {
+        const imports = await buildKenneyImportEntries(fileUrl, packSlug, fileName);
+        return { imports, importPath: imports[imports.length - 1].path };
+    }
+    const path = asset.type === "3d_model"
+        ? `res://assets/models/${fileName}`
+        : `res://assets/${fileName}`;
+    return { imports: [{ url: fileUrl, path }], importPath: path };
+}
+/** Import a resolved gateway asset into the project (texture + GLB for Kenney
+ *  packs) and, for 3D models with a `parent`, instantiate it into `scenePath`
+ *  and save. Throws with a user-facing message on any engine refusal. */
+export async function importResolvedAsset(client, args) {
+    const { asset, parent, scenePath, path, name } = args;
+    if (parent && !scenePath) {
+        throw new ToolInputError("scenePath is required when importing an asset into a scene");
+    }
+    const { imports, importPath } = await buildImportEntriesForAsset(asset, path);
+    const importResult = imports.length === 1
+        ? await client.executeOps([
+            { op: "ImportFromUrl", url: imports[0].url, path: imports[0].path },
+        ])
+        : await client.executeOps([{ op: "ImportFromUrlBatch", imports }]);
+    const importReceipts = importResult?.results ?? [];
+    const importFailure = importReceipts.find((receipt) => receipt?.ok === false);
+    if (importResult?.status === "error" || importFailure) {
+        throw new Error(importFailure?.error || "Could not import asset. Check engine logs.");
+    }
+    let addedToScene = false;
+    let sceneReceipt = null;
+    if (parent && asset.type === "3d_model") {
+        sceneReceipt = await client.executeIdentityBoundOps([
+            {
+                op: "InstantiateScene",
+                parent,
+                scene: importPath,
+                name: sanitizeNodeName(name || asset.title),
+            },
+            { op: "SaveScene" },
+        ], { scenePath });
+        const placementReceipts = sceneReceipt?.results ?? [];
+        const placementFailure = placementReceipts.find((receipt) => receipt?.ok !== true);
+        if (sceneReceipt?.status === "error" ||
+            placementReceipts.length !== 2 ||
+            placementFailure) {
+            throw new Error(placementFailure?.error || `Could not add asset to ${scenePath}`);
+        }
+        addedToScene = true;
+    }
+    return {
+        success: true,
+        assetId: asset.id,
+        asset: asset.title,
+        type: asset.type,
+        importedTo: importPath,
+        addedToScene,
+        parent: parent || null,
+        scenePath: scenePath || null,
+        sceneReceipt,
+    };
+}

package/dist/core/capabilities/camera-view.d.ts

@@ -0,0 +1,98 @@
+export declare const CAMERA_BOOKMARK_ACTIONS: readonly ["save", "list", "delete"];
+export type CameraBookmarkAction = (typeof CAMERA_BOOKMARK_ACTIONS)[number];
+/** Engine op kind per action — the pre-flight checks THIS kind, not all three. */
+export declare const CAMERA_BOOKMARK_OPS: Record<CameraBookmarkAction, string>;
+/** What the engine_lacks_op result tells the model to do instead. */
+export declare const CAMERA_BOOKMARK_FALLBACK = "pass the pose explicitly on every capture with summer_screenshot framing:\"free\" (camera_position + camera_look_at), or render through a Camera3D placed in the scene with framing:\"camera\"";
+/** Bookmark name grammar (preview_ops.cpp): 1-64 of [A-Za-z0-9_-]. */
+export declare const BOOKMARK_NAME_PATTERN: RegExp;
+export interface CameraBookmarkArgs {
+    action: CameraBookmarkAction;
+    name?: string;
+    /** Godot literal, e.g. "Vector3(0, 5, 10)". Goes together with look_at. */
+    position?: string;
+    look_at?: string;
+    fov?: number;
+}
+/** Build the engine op for one bookmark action. Throws ToolInputError (nothing
+ *  sent) for a missing/invalid name or a half-given pose. */
+export declare function buildCameraBookmarkOp(args: CameraBookmarkArgs): Record<string, unknown>;
+export declare const PRESET_FRAMINGS: readonly ["auto", "iso", "top", "front", "back", "left", "right", "camera"];
+export declare const FIXED_POSE_FRAMINGS: readonly ["free", "bookmark"];
+/** The framing enum both faces expose. "bookmark" pairs with `bookmark_name`
+ *  (the wire form is "bookmark:<name>"; the enum stays closed so the
+ *  descriptor/zod parity holds and agents see a finite list). */
+export declare const SCREENSHOT_FRAMINGS: readonly ["auto", "iso", "top", "front", "back", "left", "right", "camera", "free", "bookmark"];
+export type ScreenshotFraming = (typeof SCREENSHOT_FRAMINGS)[number];
+export interface ScenePreviewArgs {
+    scenePath?: string;
+    framing?: ScreenshotFraming;
+    bookmark_name?: string;
+    size?: [number, number];
+    nodePath?: string;
+    camera_path?: string;
+    camera_position?: string;
+    camera_look_at?: string;
+    fov?: number;
+    marks?: boolean;
+    max_marks?: number;
+}
+/** The api-client scenePreview input, with the framing resolved to its wire
+ *  form ("bookmark" + bookmark_name -> "bookmark:<name>"). */
+export interface ScenePreviewInput {
+    scenePath?: string;
+    /** Wire framing: a preset, "free", or "bookmark:<name>". */
+    framing?: string;
+    size?: [number, number];
+    nodePath?: string;
+    cameraPath?: string;
+    cameraPosition?: string;
+    cameraLookAt?: string;
+    fov?: number;
+    marks?: boolean;
+    maxMarks?: number;
+}
+export declare const MAX_MARKS_CAP = 128;
+/**
+ * Resolve screenshot args into the ScenePreview input. Infers framing "free"
+ * from a camera pose and "bookmark" from a bookmark_name when `framing` is
+ * omitted; refuses (ToolInputError, nothing sent) when they contradict a
+ * preset, when "free" lacks half its pose, or when "bookmark" has no name.
+ */
+export declare function buildScenePreviewInput(args: ScenePreviewArgs): ScenePreviewInput;
+/** True for the wave-I fixed-pose framings ("free", "bookmark:<name>"). */
+export declare function isFixedPoseFraming(wireFraming: string | undefined): boolean;
+export interface SceneMark {
+    id: number;
+    path: string;
+    class: string;
+    screen_rect?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+export interface SceneMarksSummary {
+    marks: SceneMark[];
+    skipped?: number;
+    candidates?: number;
+    truncated?: boolean;
+    maxMarks?: number;
+    /** "2d_scene" when the engine could not mark this scene. */
+    unsupported?: string;
+}
+/** Read the Set-of-Mark fields off a ScenePreview payload (`metadata` of the
+ *  EngineSnapshot). Returns null when the payload carries no marks key at all —
+ *  i.e. the engine ignored `marks:true` (an older build). */
+export declare function readSceneMarks(payload: Record<string, unknown> | undefined): SceneMarksSummary | null;
+export interface CameraPose {
+    position?: string;
+    look_at?: string;
+    fov?: number;
+}
+/** camera_pose {position, look_at, fov} as the engine echoes it (3dp literals). */
+export declare function readCameraPose(payload: Record<string, unknown> | undefined): CameraPose | null;
+/** One compact line per mark so the model can map a numbered label in the
+ *  image to a node path: `1 -> Props/Crate_02 (MeshInstance3D) @ 120,80 200x140`. */
+export declare function formatSceneMarks(summary: SceneMarksSummary): string[];

package/dist/core/capabilities/camera-view.js

@@ -0,0 +1,222 @@
+/**
+ * Camera viewpoints (perception): camera bookmarks and the fixed-pose
+ * ScenePreview framings. Shared by the MCP tools (src/mcp/tools/visual-tools.ts)
+ * and the CLI dispatcher so both faces validate the same way and send the same
+ * op.
+ *
+ * Engine contract (doc/SUMMER/SCENE_SCRIPTING_CONTRACTS.md, "Wave I"):
+ *   SaveCameraBookmark { name, position?, look_at?, fov? }  -> pose_source
+ *   ListCameraBookmarks {}                                   -> names, bookmarks
+ *   DeleteCameraBookmark { name }                            -> remaining
+ * and ScenePreview framings "free" (camera_position, camera_look_at, fov) and
+ * "bookmark:<name>" plus the Set-of-Mark overlay (marks, max_marks).
+ *
+ * Bookmarks live in the PROJECT (res://.summer/camera_bookmarks.json), so a
+ * viewpoint saved once is the same viewpoint next session and on another
+ * machine — the point is before/after screenshots that actually line up.
+ */
+import { ToolInputError } from "../tool-errors.js";
+export const CAMERA_BOOKMARK_ACTIONS = ["save", "list", "delete"];
+/** Engine op kind per action — the pre-flight checks THIS kind, not all three. */
+export const CAMERA_BOOKMARK_OPS = {
+    save: "SaveCameraBookmark",
+    list: "ListCameraBookmarks",
+    delete: "DeleteCameraBookmark",
+};
+/** What the engine_lacks_op result tells the model to do instead. */
+export const CAMERA_BOOKMARK_FALLBACK = "pass the pose explicitly on every capture with summer_screenshot framing:\"free\" (camera_position + camera_look_at), or render through a Camera3D placed in the scene with framing:\"camera\"";
+/** Bookmark name grammar (preview_ops.cpp): 1-64 of [A-Za-z0-9_-]. */
+export const BOOKMARK_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+function requireBookmarkName(name, action) {
+    const trimmed = name?.trim() ?? "";
+    if (!trimmed) {
+        throw new ToolInputError(`action "${action}" needs a bookmark name (1-64 of A-Z a-z 0-9 _ -). Nothing was sent.`);
+    }
+    if (!BOOKMARK_NAME_PATTERN.test(trimmed)) {
+        throw new ToolInputError(`Bookmark name "${trimmed}" is invalid — use 1-64 characters from A-Z a-z 0-9 _ - (no spaces or slashes). Nothing was sent.`);
+    }
+    return trimmed;
+}
+/** Build the engine op for one bookmark action. Throws ToolInputError (nothing
+ *  sent) for a missing/invalid name or a half-given pose. */
+export function buildCameraBookmarkOp(args) {
+    const kind = CAMERA_BOOKMARK_OPS[args.action];
+    if (!kind) {
+        throw new ToolInputError(`Unknown action "${String(args.action)}". Use save, list, or delete.`);
+    }
+    if (args.action === "list")
+        return { op: kind };
+    const name = requireBookmarkName(args.name, args.action);
+    if (args.action === "delete")
+        return { op: kind, name };
+    const op = { op: kind, name };
+    const position = args.position?.trim();
+    const lookAt = args.look_at?.trim();
+    if ((position && !lookAt) || (!position && lookAt)) {
+        throw new ToolInputError("position and look_at go together: pass both as Godot literals (\"Vector3(x, y, z)\") for an explicit pose, or omit both to capture the CURRENT editor 3D viewport camera. Nothing was sent.");
+    }
+    if (position && lookAt) {
+        op.position = position;
+        op.look_at = lookAt;
+    }
+    if (args.fov !== undefined)
+        op.fov = args.fov;
+    return op;
+}
+// ---------------------------------------------------------------------------
+// ScenePreview framing (summer_screenshot target:"scene")
+// ---------------------------------------------------------------------------
+export const PRESET_FRAMINGS = ["auto", "iso", "top", "front", "back", "left", "right", "camera"];
+export const FIXED_POSE_FRAMINGS = ["free", "bookmark"];
+/** The framing enum both faces expose. "bookmark" pairs with `bookmark_name`
+ *  (the wire form is "bookmark:<name>"; the enum stays closed so the
+ *  descriptor/zod parity holds and agents see a finite list). */
+export const SCREENSHOT_FRAMINGS = [...PRESET_FRAMINGS, ...FIXED_POSE_FRAMINGS];
+export const MAX_MARKS_CAP = 128;
+/**
+ * Resolve screenshot args into the ScenePreview input. Infers framing "free"
+ * from a camera pose and "bookmark" from a bookmark_name when `framing` is
+ * omitted; refuses (ToolInputError, nothing sent) when they contradict a
+ * preset, when "free" lacks half its pose, or when "bookmark" has no name.
+ */
+export function buildScenePreviewInput(args) {
+    const position = args.camera_position?.trim();
+    const lookAt = args.camera_look_at?.trim();
+    const bookmark = args.bookmark_name?.trim();
+    let framing = args.framing;
+    if (!framing) {
+        if (bookmark)
+            framing = "bookmark";
+        else if (position || lookAt)
+            framing = "free";
+    }
+    if (framing === "bookmark") {
+        if (!bookmark) {
+            throw new ToolInputError('framing:"bookmark" needs bookmark_name — the name you saved with summer_camera_bookmark (list them with action:"list"). Nothing was sent.');
+        }
+        if (!BOOKMARK_NAME_PATTERN.test(bookmark)) {
+            throw new ToolInputError(`bookmark_name "${bookmark}" is invalid — bookmark names are 1-64 characters from A-Z a-z 0-9 _ -. Nothing was sent.`);
+        }
+        if (position || lookAt) {
+            throw new ToolInputError('framing:"bookmark" takes its pose from the bookmark; drop camera_position/camera_look_at, or use framing:"free" with both. Nothing was sent.');
+        }
+    }
+    else if (framing === "free") {
+        if (!position || !lookAt) {
+            throw new ToolInputError('framing:"free" needs BOTH camera_position and camera_look_at as Godot literals ("Vector3(x, y, z)"). Nothing was sent.');
+        }
+        if (bookmark) {
+            throw new ToolInputError('framing:"free" and bookmark_name contradict each other — use framing:"bookmark" with bookmark_name, or framing:"free" with a pose. Nothing was sent.');
+        }
+    }
+    else if (framing && (position || lookAt || bookmark)) {
+        throw new ToolInputError(`framing:"${framing}" is a fixed preset; camera_position/camera_look_at need framing:"free" and bookmark_name needs framing:"bookmark". Nothing was sent.`);
+    }
+    if (args.max_marks !== undefined && (!Number.isInteger(args.max_marks) || args.max_marks < 1 || args.max_marks > MAX_MARKS_CAP)) {
+        throw new ToolInputError(`max_marks must be an integer from 1 through ${MAX_MARKS_CAP}. Nothing was sent.`);
+    }
+    const input = {};
+    if (args.scenePath)
+        input.scenePath = args.scenePath;
+    if (framing)
+        input.framing = framing === "bookmark" ? `bookmark:${bookmark}` : framing;
+    if (args.size)
+        input.size = args.size;
+    if (args.nodePath)
+        input.nodePath = args.nodePath;
+    if (args.camera_path)
+        input.cameraPath = args.camera_path;
+    if (framing === "free") {
+        input.cameraPosition = position;
+        input.cameraLookAt = lookAt;
+    }
+    if (args.fov !== undefined && (framing === "free" || framing === "bookmark"))
+        input.fov = args.fov;
+    if (args.marks !== undefined)
+        input.marks = args.marks;
+    if (args.max_marks !== undefined)
+        input.maxMarks = args.max_marks;
+    return input;
+}
+/** True for the wave-I fixed-pose framings ("free", "bookmark:<name>"). */
+export function isFixedPoseFraming(wireFraming) {
+    return wireFraming === "free" || (wireFraming?.startsWith("bookmark:") ?? false);
+}
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** Read the Set-of-Mark fields off a ScenePreview payload (`metadata` of the
+ *  EngineSnapshot). Returns null when the payload carries no marks key at all —
+ *  i.e. the engine ignored `marks:true` (an older build). */
+export function readSceneMarks(payload) {
+    if (!payload || !("marks" in payload))
+        return null;
+    const raw = Array.isArray(payload.marks) ? payload.marks : [];
+    const marks = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const mark = entry;
+        const id = num(mark.id);
+        if (id === undefined)
+            continue;
+        const rect = mark.screen_rect;
+        const x = num(rect?.x);
+        const y = num(rect?.y);
+        const w = num(rect?.w);
+        const h = num(rect?.h);
+        marks.push({
+            id,
+            path: typeof mark.path === "string" ? mark.path : "?",
+            class: typeof mark.class === "string" ? mark.class : "?",
+            ...(x !== undefined && y !== undefined && w !== undefined && h !== undefined
+                ? { screen_rect: { x, y, w, h } }
+                : {}),
+        });
+    }
+    return {
+        marks,
+        skipped: num(payload.marks_skipped),
+        candidates: num(payload.marks_candidates),
+        truncated: payload.marks_truncated === true ? true : undefined,
+        maxMarks: num(payload.max_marks),
+        unsupported: typeof payload.marks_unsupported === "string" ? payload.marks_unsupported : undefined,
+    };
+}
+/** camera_pose {position, look_at, fov} as the engine echoes it (3dp literals). */
+export function readCameraPose(payload) {
+    const raw = payload?.camera_pose;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const pose = raw;
+    return {
+        position: typeof pose.position === "string" ? pose.position : undefined,
+        look_at: typeof pose.look_at === "string" ? pose.look_at : undefined,
+        fov: num(pose.fov),
+    };
+}
+/** One compact line per mark so the model can map a numbered label in the
+ *  image to a node path: `1 -> Props/Crate_02 (MeshInstance3D) @ 120,80 200x140`. */
+export function formatSceneMarks(summary) {
+    const lines = [];
+    if (summary.unsupported) {
+        lines.push(`marks: unsupported for this scene (${summary.unsupported}) — no overlay was drawn; the image carries no numbered labels.`);
+        return lines;
+    }
+    const counts = [];
+    if (summary.candidates !== undefined)
+        counts.push(`${summary.candidates} candidate(s)`);
+    if (summary.skipped)
+        counts.push(`${summary.skipped} skipped off-screen/extent-less`);
+    if (summary.truncated)
+        counts.push(`truncated at max_marks ${summary.maxMarks ?? "?"}`);
+    lines.push(`marks: ${summary.marks.length} numbered label(s) drawn${counts.length ? ` (${counts.join(", ")})` : ""}` +
+        (summary.marks.length ? " — label -> node path:" : "."));
+    for (const mark of summary.marks) {
+        const rect = mark.screen_rect
+            ? ` @ ${Math.round(mark.screen_rect.x)},${Math.round(mark.screen_rect.y)} ${Math.round(mark.screen_rect.w)}x${Math.round(mark.screen_rect.h)}`
+            : "";
+        lines.push(`  ${mark.id} -> ${mark.path} (${mark.class})${rect}`);
+    }
+    return lines;
+}

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

@@ -0,0 +1,63 @@
+/**
+ * capture — frame capture with the toolkit-side honesty checks, ONE copy for
+ * both faces (src/mcp/tools/visual-tools.ts renders the MCP caption from it;
+ * src/core/capabilities/tool-dispatch.ts returns the receipt as JSON).
+ *
+ * Frame honesty (E2E 2026-09-03, F-01 / F-05):
+ *  - Every frame goes through a zero-dependency content check
+ *    (./frame-quality.ts). A "viewport" frame that comes back flat (uniformly
+ *    black/grey) is recaptured ONCE after a settle delay; the result says which
+ *    frame it is and what the first one looked like, so no face can present a
+ *    blank frame as evidence about the scene. Root-cause status is written in
+ *    frame-quality.ts: the engine reads the editor SubViewport texture as-is
+ *    (no forced draw, no blank retry), consistent with — but not proven to be —
+ *    a not-yet-redrawn 2D subviewport right after the editor switched tabs.
+ *  - The "scene" target's no-camera confession is phrased for the scene's
+ *    kind: a 3D scene without a Camera3D plays grey/black; a 2D scene without
+ *    a Camera2D simply plays from the origin and is NOT an error. The engine
+ *    receipt reports scene_has_camera for both kinds without saying which, so
+ *    the kind comes from a scene-tree read (./scene-kind.ts).
+ */
+import type { EngineSnapshot } from "../api-client.js";
+import { type FrameQuality } from "./frame-quality.js";
+import { type SceneKindResult } from "./scene-kind.js";
+import type { ScenePreviewInput } from "./camera-view.js";
+/** Settle delay before the single automatic viewport recapture. */
+export declare const VIEWPORT_RECAPTURE_DELAY_MS = 700;
+export interface RecaptureInfo {
+    delayMs: number;
+    /** Analysis of the flat frame that triggered the recapture. */
+    firstFrame: FrameQuality;
+    /** Set when the second capture itself failed — the FIRST frame is returned. */
+    error?: string;
+}
+/** EngineSnapshot plus the toolkit-side honesty fields both faces read. */
+export type CaptureResult = EngineSnapshot & {
+    frameQuality?: FrameQuality;
+    recapture?: RecaptureInfo;
+    sceneKind?: SceneKindResult;
+};
+/** The ScenePreview input in its wire form (framing resolved to a preset,
+ *  "free", or "bookmark:<name>"; camera pose / marks fields) is owned by
+ *  ./camera-view.ts, where both faces build it from their arguments. */
+export type { ScenePreviewInput } from "./camera-view.js";
+/** The engine reads capture needs — a structural subset of EngineApiClient. */
+export interface CaptureClient {
+    viewportSnapshot(): Promise<EngineSnapshot>;
+    scenePreview(input?: ScenePreviewInput): Promise<EngineSnapshot>;
+    gameSnapshot(): Promise<EngineSnapshot>;
+    getSceneState(scenePath?: string, options?: {
+        depth?: number;
+        limit?: number;
+    }): Promise<unknown>;
+}
+/** Stamp the content check onto a successful frame. */
+export declare function analyzedSnapshot(snap: EngineSnapshot): CaptureResult;
+/** Viewport capture with ONE automatic recapture when the first frame is flat. */
+export declare function captureViewport(client: CaptureClient): Promise<CaptureResult>;
+/** Offscreen scene render; when the engine confesses the scene has no camera
+ *  of its own, read the tree to learn whether that is a 3D or a 2D scene. */
+export declare function captureScene(client: CaptureClient, input: ScenePreviewInput): Promise<CaptureResult>;
+/** Running-game frame with the content check (no recapture: a booting or
+ *  fading game legitimately shows a flat frame). */
+export declare function captureGame(client: CaptureClient): Promise<CaptureResult>;

package/dist/core/capabilities/capture.js

@@ -0,0 +1,67 @@
+import { analyzeFrameBase64 } from "./frame-quality.js";
+import { classifySceneKindFromTree } from "./scene-kind.js";
+import { sleep } from "../util/sleep.js";
+/** Settle delay before the single automatic viewport recapture. */
+export const VIEWPORT_RECAPTURE_DELAY_MS = 700;
+/** Bounds for the scene-kind tree read (the engine honours depth/limit only on
+ *  scene-targeted reads; an untargeted read is the depth-2 snapshot). */
+const SCENE_KIND_TREE_DEPTH = 8;
+const SCENE_KIND_TREE_LIMIT = 600;
+/** Stamp the content check onto a successful frame. */
+export function analyzedSnapshot(snap) {
+    if (!snap.ok || !snap.base64)
+        return snap;
+    return { ...snap, frameQuality: analyzeFrameBase64(snap.base64, snap.mime) };
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Viewport capture with ONE automatic recapture when the first frame is flat. */
+export async function captureViewport(client) {
+    const first = analyzedSnapshot(await client.viewportSnapshot());
+    const quality = first.frameQuality;
+    if (!quality?.analyzable || !quality.flat)
+        return first;
+    await sleep(VIEWPORT_RECAPTURE_DELAY_MS);
+    const recapture = { delayMs: VIEWPORT_RECAPTURE_DELAY_MS, firstFrame: quality };
+    let second;
+    try {
+        second = await client.viewportSnapshot();
+    }
+    catch (err) {
+        return { ...first, recapture: { ...recapture, error: errorMessage(err) } };
+    }
+    if (!second.ok || !second.base64) {
+        return {
+            ...first,
+            recapture: { ...recapture, error: second.error ?? "recapture returned no image data" },
+        };
+    }
+    return { ...analyzedSnapshot(second), recapture };
+}
+/** Offscreen scene render; when the engine confesses the scene has no camera
+ *  of its own, read the tree to learn whether that is a 3D or a 2D scene. */
+export async function captureScene(client, input) {
+    const snap = analyzedSnapshot(await client.scenePreview(input));
+    if (!snap.ok || !snap.base64 || snap.sceneHasCamera !== false)
+        return snap;
+    return { ...snap, sceneKind: await readSceneKind(client, input.scenePath) };
+}
+/** Running-game frame with the content check (no recapture: a booting or
+ *  fading game legitimately shows a flat frame). */
+export async function captureGame(client) {
+    return analyzedSnapshot(await client.gameSnapshot());
+}
+async function readSceneKind(client, scenePath) {
+    try {
+        const trimmed = scenePath?.trim();
+        const targeted = trimmed && trimmed !== "." && trimmed !== "./" ? trimmed : undefined;
+        const state = targeted
+            ? await client.getSceneState(targeted, { depth: SCENE_KIND_TREE_DEPTH, limit: SCENE_KIND_TREE_LIMIT })
+            : await client.getSceneState();
+        return classifySceneKindFromTree(state);
+    }
+    catch (err) {
+        return { kind: "unknown", reason: errorMessage(err) };
+    }
+}

package/dist/core/capabilities/console-read.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Scope note stamped on every shaped summer_get_console result.
+ *
+ * E2E 2026-09-03 F-07: right after a play session that produced four runtime
+ * errors, `summer_get_console` reported `errors 0` — correctly. The editor
+ * Output panel (EditorLog) never received them: a running game's errors are
+ * collected by the debugger (summer_get_debugger_errors / the `debugger`
+ * section of summer_get_diagnostics). The engine types console lines straight
+ * from EditorLog::MSG_TYPE (error / warning / std / editor — debug_ops.cpp
+ * GetConsoleOutput), so dropping `std` lines by default hides nothing that
+ * was an error; the trap is treating this tool's count as the post-play
+ * verdict at all. The note travels with the result because tool descriptions
+ * are read once and results are read every time.
+ */
+export declare const CONSOLE_SCOPE_NOTE = "Editor Output panel only. Runtime errors from a played game are collected by the debugger, not here \u2014 this count is NOT the post-play verdict. Read summer_get_diagnostics (console + debugger + script errors together) or summer_get_debugger_errors for that.";
+/** Attach `_scope` to a shaped console result. Non-object results pass through. */
+export declare function withConsoleScope<T>(result: T): T;

package/dist/core/capabilities/console-read.js

@@ -0,0 +1,21 @@
+/**
+ * Scope note stamped on every shaped summer_get_console result.
+ *
+ * E2E 2026-09-03 F-07: right after a play session that produced four runtime
+ * errors, `summer_get_console` reported `errors 0` — correctly. The editor
+ * Output panel (EditorLog) never received them: a running game's errors are
+ * collected by the debugger (summer_get_debugger_errors / the `debugger`
+ * section of summer_get_diagnostics). The engine types console lines straight
+ * from EditorLog::MSG_TYPE (error / warning / std / editor — debug_ops.cpp
+ * GetConsoleOutput), so dropping `std` lines by default hides nothing that
+ * was an error; the trap is treating this tool's count as the post-play
+ * verdict at all. The note travels with the result because tool descriptions
+ * are read once and results are read every time.
+ */
+export const CONSOLE_SCOPE_NOTE = "Editor Output panel only. Runtime errors from a played game are collected by the debugger, not here — this count is NOT the post-play verdict. Read summer_get_diagnostics (console + debugger + script errors together) or summer_get_debugger_errors for that.";
+/** Attach `_scope` to a shaped console result. Non-object results pass through. */
+export function withConsoleScope(result) {
+    if (!result || typeof result !== "object" || Array.isArray(result))
+        return result;
+    return { ...result, _scope: CONSOLE_SCOPE_NOTE };
+}

package/dist/{lib → core/capabilities}/creator.d.ts

@@ -1,27 +1,6 @@
-export type CreatorOperation = "publish" | "releases" | "logs";
+export type CreatorOperation = "publish" | "releases";
 export type CreatorFace = "cli" | "mcp";
 export declare const CREATOR_API_CONTRACT: "summer.creator.v1";
-export declare const CREATOR_API_AUDIT: {
-    readonly auditedAt: "2026-07-30";
-    readonly repository: "SummerEngine/summercraft";
-    readonly contract: "summer.creator.v1";
-    readonly credentialAudience: "summercraft-creator";
-    readonly requiredServerScope: "publish";
-    readonly operations: {
-        readonly publish: {
-            readonly supported: true;
-            readonly route: "/api/creator/v1/publish";
-        };
-        readonly releases: {
-            readonly supported: true;
-            readonly route: "/api/creator/v1/releases";
-        };
-        readonly logs: {
-            readonly supported: false;
-            readonly route: null;
-        };
-    };
-};
 export declare class CreatorOperationError extends Error {
     readonly code: string;
     readonly operation: CreatorOperation;
@@ -84,10 +63,3 @@ export interface CreatorReleasesResult {
     nextCursor: string | null;
 }
 export declare function listCreatorReleases(input: ListCreatorReleasesInput, overrides?: Partial<CreatorClientDependencies>): Promise<CreatorReleasesResult>;
-export interface ReadCreatorLogsInput {
-    projectId?: string;
-    releaseId?: string;
-    limit?: number;
-    face: CreatorFace;
-}
-export declare function readCreatorLogs(input: ReadCreatorLogsInput): Promise<never>;