summer-engine 3.0.0 → 3.2.0

package/dist/mcp/tools/scene-tools.js

@@ -1,7 +1,12 @@
 import { z } from "zod";
 import { withEngine, ToolInputError } from "./with-engine.js";
-import { executeOpsChunked, executeSceneMutation } from "../../core/capabilities/engine-ops.js";
-import { annotateVariantTypes } from "../../core/capabilities/variant-types.js";
+import { executeSceneMutation } from "../../core/capabilities/engine-ops.js";
+import { instantiateScene, runBatch } from "../../core/capabilities/placement-batch.js";
+import { renderPlacementResult } from "./placement-tools.js";
+import { inspectNodeFields, inspectNodeInputShape } from "../../core/capabilities/inspect-node.js";
+import { inspectResource, inspectResourceInputShape } from "../../core/capabilities/inspect-resource.js";
+import { rawSceneReplaceRefusal, replaceNodeInputShape, replaceNodePersisted, } from "../../core/capabilities/replace-node.js";
+import { connectSignalInputShape, connectSignalPersisted } from "../../core/capabilities/connect-signal.js";
 import { FALLBACK_SINGLE_ONLY_OPS, resolveSingleOnlyOps, } from "../../core/capability-skew.js";
 // Re-exported for tests and for callers that reason about dispatch classes.
 // executeSceneMutation is the ONE copy in core/capabilities/engine-ops.ts,
@@ -28,6 +33,8 @@ function requireSuccessfulOps(result, context) {
 function minimalSceneText(rootName, rootType) {
     return `[gd_scene format=3]\n\n[node name="${rootName}" type="${rootType}"]\n`;
 }
+const finiteNumber = z.number().finite();
+const finiteVector3 = z.tuple([finiteNumber, finiteNumber, finiteNumber]);
 // Node names reject . : @ / " %; the type must be a plain class name.
 // Both are interpolated into quoted .tscn fields, so validate before composing.
 const VALID_ROOT_NAME = /^[A-Za-z_][A-Za-z0-9_\- ]*$/;
@@ -194,7 +201,9 @@ Do not guess paths. Prefer:
 
 The scene must already exist in the project. Use summer_import_from_url first if importing from external sources.
 
-PASS target_size FOR IMPORTED MODELS. Downloaded/generated .glb assets arrive at arbitrary scale (a "chair" can be 40 units tall). target_size uniformly scales the instanced subtree so its largest world-AABB dimension equals that many units — commit to real-world size: chair 1.0, door 2.0, car 4.5, person 1.7, tree 6-10. The result then reports dimensions + scale_applied; verify placement afterwards (summer_world_snapshot AABBs, summer_screenshot). Older engine builds ignore target_size — when the result lacks scale_applied, this tool appends a note and you must scale the node yourself (summer_set_prop scale) and re-check.`, {
+PASS target_size FOR IMPORTED MODELS. Downloaded/generated .glb assets arrive at arbitrary scale (a "chair" can be 40 units tall). target_size uniformly scales the instanced subtree so its largest world-AABB dimension equals that many units — commit to real-world size: chair 1.0, door 2.0, car 4.5, person 1.7, tree 6-10. The result then reports dimensions + scale_applied; verify placement afterwards (summer_world_snapshot AABBs, summer_screenshot). Older engine builds ignore target_size — when the result lacks scale_applied, this tool appends a note and you must scale the node yourself (summer_set_prop scale) and re-check.
+
+PLACE IT IN THE SAME CALL: position, rotation_degrees and scale ([x, y, z], parent-local, like summer_set_prop), or transform (a "Transform3D(...)" string). The instance is created, then those properties are set on the exact node path the receipt reports (a name collision rename is followed), then the scene is saved: one call per piece, no window at the origin. The result adds placement {nodePath, applied, fields}. Do not combine transform with the others, or scale/transform with target_size. Measure a kit piece first with summer_inspect_asset.`, {
         scenePath: z.string().describe("Target scene to receive the instance, e.g. 'res://main.tscn'"),
         parent: z.string().describe("Parent node path, e.g. './World'"),
         scene: z.string().describe("Scene/model path, e.g. 'res://player.tscn' or 'res://models/tree.glb'"),
@@ -204,30 +213,18 @@ PASS target_size FOR IMPORTED MODELS. Downloaded/generated .glb assets arrive at
             .positive()
             .optional()
             .describe("Normalize the instance's physical size: uniformly scale it so its largest world-AABB dimension equals this many units (chair 1.0, car 4.5, person 1.7). Strongly recommended for imported .glb/.gltf models."),
-    }, async ({ scenePath, parent, scene, name, target_size }) => withEngine(async (client) => {
-        const op = { op: "InstantiateScene", parent, scene };
-        if (name)
-            op.name = name;
-        if (target_size !== undefined)
-            op.target_size = target_size;
-        const result = await executeSceneMutation(client, scenePath, [op]);
-        // An older engine applies the op but silently drops target_size — its
-        // receipt then lacks scale_applied. Confess that instead of letting a
-        // 40-unit "chair" pass as normalized.
-        if (target_size !== undefined && result && typeof result === "object") {
-            const envelope = result;
-            const instanced = envelope.results?.find((entry) => entry.op === "InstantiateScene" && entry.ok === true);
-            if (instanced && !("scale_applied" in instanced)) {
-                return {
-                    ...envelope,
-                    target_size_note: `This Summer Engine build IGNORED target_size (no scale_applied in the receipt) — the instance is at the asset's raw scale, NOT normalized to ${target_size}. ` +
-                        "Scale it yourself (summer_set_prop scale, or ctx code in summer_run_script), verify with summer_world_snapshot/summer_screenshot, or update Summer Engine.",
-                };
-            }
-        }
-        return result;
-    }));
-    server.tool("summer_connect_signal", `Connect a signal between two nodes. Signals are Godot's event system — they notify when something happens.
+        position: finiteVector3.optional().describe("Parent-local position [x, y, z] set right after the instance is created."),
+        rotation_degrees: finiteVector3.optional().describe("Parent-local rotation in degrees [x, y, z] (Godot rotation_degrees)."),
+        scale: finiteVector3.optional().describe("Local scale [x, y, z]. Not with target_size."),
+        transform: z
+            .string()
+            .optional()
+            .describe('Full local transform as "Transform3D(xx, xy, xz, yx, yy, yz, zx, zy, zz, ox, oy, oz)" (Godot row-major basis, then origin). Not with position/rotation_degrees/scale/target_size.'),
+    }, async (args) => 
+    // E2E: an older engine applies the op but silently drops target_size —
+    // instantiateScene appends target_size_note when scale_applied is absent.
+    withEngine(async (client) => instantiateScene(client, args)));
+    server.tool("summer_connect_signal", `Connect a signal between two nodes so the connection is SAVED in the scene. Signals are Godot's event system — they notify when something happens.
 
 Common signals:
 - "body_entered" / "body_exited" — Area3D/Area2D detects physics bodies
@@ -236,15 +233,9 @@ Common signals:
 - "area_entered" — Area detects another area
 - "input_event" — CollisionObject received input
 
-The receiver node must have a script with the specified method.`, {
-        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
-        emitter: z.string().describe("Node that fires the signal, e.g. './Player/HitArea'"),
-        signal: z.string().describe("Signal name, e.g. 'body_entered'"),
-        receiver: z.string().describe("Node with the handler script, e.g. './Player'"),
-        method: z.string().describe("Method name in the receiver's script, e.g. '_on_hit_area_body_entered'"),
-    }, async ({ scenePath, emitter, signal, receiver, method }) => withEngine(async (client) => executeSceneMutation(client, scenePath, [
-        { op: "ConnectSignal", emitter, signal, receiver, method },
-    ])));
+The receiver should have the method (a script method, or a built-in such as queue_free); a missing one is saved anyway and reported in warnings. scenePath must be a .tscn.
+
+PERSISTENCE IS VERIFIED: the engine's ConnectSignal op connects without CONNECT_PERSIST, so its connection never reached the file. This tool connects through a RunSceneScript probe with CONNECT_PERSIST (replacing a non-persistent connection of the same pair), saves, reads the saved .tscn back and returns persisted:true / verified:true only when the [connection] line is there; otherwise an error with failure_reason not_persisted. The probe runs in the active tab: a scene in a background tab is brought forward and the user's tab restored (tab_switched). One Ctrl+Z reverts it.`, connectSignalInputShape, async (args) => withEngine(async (client) => connectSignalPersisted(client, args)));
     server.tool("summer_select_node", "Select a node in the editor's scene tree and show it in the inspector panel. Useful for focusing the editor on a specific node.", {
         nodePath: z.string().describe("Node path to select"),
         scenePath: z.string().optional().describe("Open this scene first, then select the node"),
@@ -254,35 +245,29 @@ The receiver node must have a script with the specified method.`, {
             op.scenePath = scenePath;
         return client.executeOps([op]);
     }));
-    server.tool("summer_replace_node", "Replace a node with a different type or scene, preserving its position in the tree and its children. Useful for changing a StaticBody3D to a RigidBody3D, or swapping a placeholder with a proper prefab.", {
-        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
-        path: z.string().describe("Node path to replace"),
-        type: z.string().optional().describe("New node type, e.g. 'RigidBody3D'"),
-        scene: z.string().optional().describe("Scene to replace with, e.g. 'res://enemies/boss.tscn'"),
-    }, async ({ scenePath, path, type, scene }) => withEngine(async (client) => {
-        const op = { op: "ReplaceNode", path };
-        if (type)
-            op.type = type;
-        if (scene)
-            op.scene = scene;
-        return executeSceneMutation(client, scenePath, [op]);
-    }));
+    server.tool("summer_replace_node", `Replace a node with a different scene/model or node type, keeping its parent, sibling index, name, transform and property overrides, and the children the scene added under it. Use it to swap a kit piece for another (a wall host for a door host), a placeholder for a prefab, or a StaticBody3D for a RigidBody3D.
+
+Give exactly one of scene or type. The scenePath must be a .tscn.
+
+PERSISTENCE IS VERIFIED: the tool saves, reads the saved .tscn back and checks that the node at path now instances the new scene (or has the new type), under the same parent, with every child present. persisted:true is proven from the file; a mismatch is an error with failure_reason not_persisted — never report that as done.
+
+How: a scene swap runs as InstantiateScene (temporary name) -> SetProp each property override -> ReparentNode the children -> MoveNode to the old index -> RemoveNode the old node -> rename -> SaveScene, because the engine's own ReplaceNode keeps the OLD scene reference in the saved file. A type change of a plain node uses the engine's ReplaceNode. State that cannot travel (groups, signal connections, scene-local sub_resource values, overrides of nodes inside the old scene) is listed in not_carried_over. Undo takes one Ctrl+Z per step.`, replaceNodeInputShape, async (args) => withEngine(async (client) => replaceNodePersisted(client, args)));
     server.tool("summer_inspect_node", `Get all editable properties of a node with their current values, types, and resource info.
 
 Call this before modifying a node to understand its current state. Returns every property the Godot inspector would show. Each prop carries the engine's raw Variant.Type integer as "type" plus its name as "type_name" (e.g. type 5 = TYPE_VECTOR2, 20 = TYPE_COLOR, 24 = TYPE_OBJECT); resource-valued props also carry resource_type / resource_path.
 
 Reads the currently OPEN scene — "path" is relative to its root (there is no scenePath argument; open the scene first if needed).
 
-Example: inspect a light to see its energy, color, shadow settings before changing them.`, {
-        path: z.string().describe("Node path from scene tree, e.g. 'Player', 'World/Enemies/Boss', 'DirectionalLight3D'"),
-    }, async ({ path }) => 
+Example: inspect a light to see its energy, color, shadow settings before changing them.
+
+The full read is about 5 KB. To read only what you need, pass fields: property names or globs ('position', 'surface_material_override/*'), plus derived fields: transform (local position / rotation_degrees / scale, and a Transform3D literal for 3D nodes), global_transform (world origin + Transform3D, composed from the world snapshot), scene_file_path (the scene this node instances), aabb (world bounds), warnings. Example: fields:['transform','global_transform','scene_file_path'] is a few hundred bytes. missing_fields and unavailable say what could not be read.`, inspectNodeInputShape, async (args) => 
     // E2E 2026-09-03 F-14: the engine returns Variant.Type as a bare int.
-    withEngine(async (client) => annotateVariantTypes(await client.inspectNode(path))));
-    server.tool("summer_inspect_resource", `Get all properties of a resource (material, mesh, shape, environment, etc).
+    withEngine(async (client) => inspectNodeFields(client, args)));
+    server.tool("summer_inspect_resource", `Read a resource: a material, mesh, shape, texture, environment, or a scene/model file.
 
-Use when you need the sub-properties of a resource attached to a node. For example, summer_inspect_node tells you a MeshInstance3D has a "StandardMaterial3D" material — this tool tells you that material's albedo_color, metallic, roughness, etc.`, {
-        path: z.string().describe("Resource path, e.g. 'res://materials/ground.tres' or 'res://models/player.glb'"),
-    }, async ({ path }) => withEngine(async (client) => client.inspectResource(path)));
+Two forms, pass exactly one:
+- path: a resource FILE ('res://materials/ground.tres', a mesh 'res://kit/meshes/wall_01.res', 'res://models/player.glb'), loaded read-only in the editor. A Mesh returns its AABB, surface_count and per surface the primitive, vertex and index counts, attributes, triangles and material (class, path or embedded, albedo for standard materials), plus the unique materials and blend shapes. A scene or model (.tscn/.glb/.gltf) returns its node count, the first 40 nodes with type, instanced scene and mesh, and its meshes; summer_inspect_asset measures it (AABB, planes, ports). Every other resource (and a mesh) returns its editor properties that differ from the class default (props), with props_at_default counting the rest.
+- nodePath + property: a resource a node of the ACTIVE scene tab holds, e.g. nodePath 'Floor', property 'mesh'. For example, summer_inspect_node tells you a MeshInstance3D has a "StandardMaterial3D" material_override — this form returns its albedo_color, metallic, roughness, etc.`, inspectResourceInputShape, async (args) => withEngine(async (client) => inspectResource(client, args)));
     server.tool("summer_batch", `Execute multiple operations in a single call. Each op is forwarded to the engine VERBATIM, so this is also how you reach engine ops that have no dedicated tool.
 
 UNDO: when nothing in the list forces a split (see the single-op contract below), the whole batch is ONE undo step — the user undoes everything with a single Ctrl+Z. When single-only ops are present the list is split into sequential requests and EACH chunk is its own undo step (one Ctrl+Z per chunk; the receipt shows the chunks). Use this when building something that involves multiple nodes and properties — e.g., creating a player character with collision, camera, and properties.
@@ -297,6 +282,11 @@ RAW RUNTIME OPS (interactive verification — structured failure_reason passes t
 - RunVerification — spawn a hidden, disposable game instance that runs a GDScript probe and dies (never touches the editor): {"op": "RunVerification", "probe_source": "...", "max_seconds": 20}. Returns {ok, results, frames, out_dir}. Probe API: report(name, value) / save_frame(name) / press(action) / key(keycode) / finish(). save_frame REQUIRES a name argument — save_frame() with no args is a script error. Mount scenes deferred: get_tree().root.add_child.call_deferred(instance); await get_tree().process_frame; await settle() — a direct add_child in _ready can hit the parent-busy guard and capture a black frame.
 - SimulateInput — inject an action/key/mouse/axis into the RUNNING game (summer_play first): {"op": "SimulateInput", "type": "action", "action": "jump", "pressed": true}. It MUST be sent alone (single-op batch). failure_reason "not_running" = start the game first; "unsupported" = the running game build predates the handler — fall back to RunVerification or ask the user.
 
+A raw ReplaceNode with scene is refused (it saves the old scene reference); use summer_replace_node.
+A raw ConnectSignal is refused (the engine connects without CONNECT_PERSIST, so the file never holds it); use summer_connect_signal.
+
+REPARENTNODE KEEPS ITS SUBTREE AND IS VERIFIED: the engine's ReparentNode re-owns only the moved node, so its children and grandchildren were dropped from the saved file. A batch with ReparentNode saves first, reads the saved .tscn, sends each ReparentNode in its own request with an in-place ReparentNode (same parent, same index) per scene-owned descendant to give it back to the scene, then reads the saved file again: persisted:true / verified:true only when every moved node and descendant is at its new path; otherwise an error with failure_reason not_persisted. A move onto a parent that already has a child of that name is refused (failure_reason name_collision). The scenePath must be a .tscn, and Undo cannot share the batch.
+
 Do not mix OpenScene with scene mutations in one batch. OpenScene is a UI action;
 send it separately. scenePath selects every mutation target. The tool appends one
 final SaveScene when the batch mutates a scene; if supplied explicitly, SaveScene
@@ -306,10 +296,21 @@ SaveScene, InstantiateScene, ReplaceNode, SimulateInput, the runtime reads
 ops to travel as their own request, so this tool automatically splits your op
 list into sequential requests around them — each split chunk is its own undo
 step (NOT one step for the whole batch), and if a later chunk fails the receipt
-reports exactly which earlier ops already applied.`, {
+reports exactly which earlier ops already applied.
+
+PLACED INSTANCES: an InstantiateScene op may also carry position, rotation_degrees, scale ([x, y, z] or "Vector3(...)") or transform ("Transform3D(...)"); the tool sets them on the created node. One op per piece. Other ops are forwarded verbatim. Cost: each InstantiateScene is its own engine request (the engine requires it); the transforms of a run of InstantiateScene ops are then sent together (up to 200 per request) before the next other op, so N placed pieces plus the save cost about N + 2 requests and N + 2 undo steps. Every later op (a SetProp, SnapToSurface, the save) sees the pieces already placed; if an InstantiateScene fails, the pieces created before it still get their transforms.
+
+RECEIPTS: receipt "summary" returns only counts, failures [{index, op, error}] (index = position in your ops list), created node paths and renames, under 5 KB with any cut declared. Use it for any batch over a few ops; the full receipt of a large batch overflows the tool-output limit.
+
+scenePersistence.saved means the SaveScene ran; it does not prove what the file
+holds. verified:true is set only where the tool read the saved file back.`, {
         scenePath: z.string().optional().describe("Required when ops contains scene mutations; exact res:// target scene path"),
         ops: z.array(z.record(z.unknown())).describe("Array of operation objects, each with 'op' plus its parameters"),
-    }, async ({ scenePath, ops }) => withEngine(async (client) => {
+        receipt: z
+            .enum(["full", "summary"])
+            .optional()
+            .describe("full (default): every engine receipt. summary: counts, failures with op index, created node paths only (under 5 KB)."),
+    }, async ({ scenePath, ops, receipt }) => withEngine(async (client) => {
         const rawFileMutation = ops.find((op) => {
             const kind = String(op.op ?? "");
             return kind === "WriteFile" || kind === "ReplaceText";
@@ -318,28 +319,15 @@ reports exactly which earlier ops already applied.`, {
             throw new ToolInputError(`summer_batch does not accept raw ${String(rawFileMutation.op)} operations. ` +
                 "Use summer_write_file or summer_replace_text so project identity, content guards, and same-file ordering are enforced.");
         }
-        const sceneMutations = new Set([
-            "AddNode", "RemoveNode", "MoveNode", "ReparentNode", "ReplaceNode",
-            "SetProp", "SetResourceProperty", "ConnectSignal", "DisconnectSignal",
-            "InstantiateScene", "SaveScene", "SnapToSurface", "AlignDistribute3D", "Undo",
-        ]);
-        // Read-only spatial queries target an exact scene (identity-bound) but
-        // never save — no SaveScene is appended for them.
-        const sceneQueries = new Set([
-            "TestPlacement3D", "NavigationProbe3D", "Starcast3D",
-        ]);
-        const containsMutation = ops.some((op) => sceneMutations.has(String(op.op ?? "")));
-        const needsScenePath = containsMutation ||
-            ops.some((op) => sceneQueries.has(String(op.op ?? "")));
-        if (needsScenePath && !scenePath) {
-            throw new ToolInputError("summer_batch requires scenePath when ops targets a scene");
-        }
-        const options = { groupUndo: true, ...(scenePath ? { scenePath } : {}) };
-        if (containsMutation) {
-            return executeSceneMutation(client, scenePath, ops, options);
-        }
-        return executeOpsChunked((chunk) => needsScenePath
-            ? client.executeIdentityBoundOps(chunk, options)
-            : client.executeOps(chunk, options), ops, resolveSingleOnlyOps(client));
-    }));
+        const replaceRefusal = rawSceneReplaceRefusal(ops);
+        if (replaceRefusal)
+            throw new ToolInputError(replaceRefusal);
+        // Scene mutations get one final SaveScene; read-only spatial queries
+        // (TestPlacement3D, NavigationProbe3D, Starcast3D) are identity-bound
+        // to the scene but never saved (core/capabilities/placement-batch.ts).
+        const result = await runBatch(client, { scenePath, ops: ops, receipt });
+        return receipt === "summary" ? { summaryReceipt: result } : result;
+    }, receipt === "summary"
+        ? { onResult: (wrapped) => renderPlacementResult(wrapped.summaryReceipt) }
+        : undefined));
 }

package/dist/mcp/tools/seeing-tools.d.ts

@@ -0,0 +1,24 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type SeeingResult } from "../../core/capabilities/seeing/seeing.js";
+/**
+ * Seeing tools: look at a 3D environment the way a player and an artist do.
+ * Every image comes back INLINE as an MCP image block (one grid image for a
+ * sheet, never N images), with a compact text caption (labels, poses, scores,
+ * mark -> path). Renders use the scene's REAL WorldEnvironment and lights.
+ * Implementation and the in-engine kernel: src/core/capabilities/seeing/.
+ */
+type ToolResultContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+type ToolResult = {
+    content: ToolResultContent[];
+    isError?: boolean;
+};
+export declare function seeingContent(result: SeeingResult): ToolResult;
+export declare function registerSeeingTools(server: McpServer): void;
+export {};

package/dist/mcp/tools/seeing-tools.js

@@ -0,0 +1,64 @@
+import { withEngine } from "./with-engine.js";
+import { debugViews, frameNodes, frameShot, shotSheet, zoom, } from "../../core/capabilities/seeing/seeing.js";
+import { debugViewsShape, frameNodesShape, frameShotShape, shotSheetShape, zoomShape, } from "../../core/capabilities/seeing/args.js";
+function wrap(result) {
+    return result.ok ? { seeing: result } : { seeing: result, failure_reason: result.failure_reason };
+}
+export function seeingContent(result) {
+    if (!result.ok) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: result.error,
+                        failure_reason: result.failure_reason,
+                        ...(result.hint ? { hint: result.hint } : {}),
+                        ...(result.detail ? { detail: result.detail } : {}),
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    const content = [];
+    if (result.image)
+        content.push({ type: "image", data: result.image.base64, mimeType: result.image.mime || "image/jpeg" });
+    content.push({ type: "text", text: result.caption });
+    return { content };
+}
+function run(op) {
+    return async (args) => withEngine(async (client) => wrap(await op(client, args)), {
+        onResult: (wrapped) => seeingContent(wrapped.seeing),
+    });
+}
+const COMMON = `Read-only: the scene file, the open tab and the undo history are never touched (the render is an offscreen copy of the SAVED scene). The image arrives inline; the caption carries poses, labels and numbers. Failures are structured (failure_reason), never a silent fallback.`;
+export function registerSeeingTools(server) {
+    server.tool("summer_frame_nodes", `Frame one or more nodes with a camera fitted to their WORLD bounds and render it with the scene's REAL WorldEnvironment, lights, fog and tonemap (unlike summer_screenshot nodePath, which only works with the flat preview environment).
+
+Pick the side with direction (front/back/left/right/top/iso) or an explicit from vector; fill sets how much of the frame they span. bookmark_name also saves the fitted pose so every later render (summer_shot_sheet, summer_debug_views, summer_screenshot framing:"bookmark") lines up with it. marks:true adds numbered labels mapped to node paths.
+
+An explicit from is checked in-engine before you trust the image: if walls block the nodes, or the camera stands behind or inside a one-sided surface (its back is not drawn, so the image would look THROUGH the wall), the caption opens with a WARNING and the nearest valid from (+ fov) to pass back. With marks:true every labelled node gets an occlusion test (centre + 4 bounds points); hidden ones are noted "(hidden behind <path>)".
+
+Returns the image + caption: the pose as Vector3 literals, the bounds, the environment used, the view check, and the mark list. ${COMMON}`, frameNodesShape, run(frameNodes));
+    server.tool("summer_shot_sheet", `Render several bookmarks and/or explicit poses into ONE labelled grid image in a single call: same tile size, same view, real lighting. Use it after every change to see all hero views at once instead of N screenshots.
+
+compare_previous:true turns each bookmark into a row of [previous | now | difference map] and reports the share of pixels that changed and where. Each bookmark keeps exactly one previous render (its compare baseline) at res://.summer/shots/<bookmark>.jpg (JPEG, <= 1024 px; the folder is capped at 20 MB, oldest first). Only compare_previous:true or update_previous:true replaces it; a plain sheet creates a missing baseline and never overwrites one. view renders every tile as lighting/unshaded/normals/overdraw/wireframe instead of beauty.
+
+Returns the grid + caption (tile number -> label and pose, difference stats). ${COMMON}`, shotSheetShape, run(shotSheet));
+    server.tool("summer_debug_views", `One pose rendered as a grid of debug views next to the beauty pass: beauty, lighting (light only: direction, pools, dead-dark areas), unshaded (albedo: texture quality, value grouping), normals (world-space, x red y green z blue: seams, flipped or faceted normals), overdraw (stacked transparent layers), wireframe (triangle density, floating or duplicated pieces).
+
+Use it on the weakest shot of a sheet to see WHY it reads badly. lighting/unshaded/overdraw/wireframe are the engine's Viewport debug draw modes; normals uses an unshaded override material on a private copy (normal maps and alpha cut-outs are not applied) and works on every renderer. The caption names the method per view.
+
+Returns the grid + caption. ${COMMON}`, debugViewsShape, run(debugViews));
+    server.tool("summer_zoom", `High-resolution close look at part of a frame: region [x, y, w, h] (fractions of the frame) or mark N from a marks render of the same pose. The camera renders the EXACT sub-frustum of that region at full output resolution, so you see real texture detail, seams, gaps and floating pieces, not upscaled pixels. A region is honoured exactly (no pad by default, never widened to an aspect ratio: the image takes the region's own aspect, with dark bars only for extreme shapes); a mark gets pad 0.15.
+
+Use after a sheet or debug view shows something suspicious. view picks beauty or a debug view. Returns the zoomed image + caption (the real zoom factor, the rendered region, widened_because when it is larger than asked, mark -> node path and a warning when that node is hidden). ${COMMON}`, zoomShape, run(zoom));
+    server.tool("summer_frame_shot", `Smart framing: find good camera poses for a shot type automatically, measured in-engine against the real geometry.
+
+shot: establishing (wide), eye_level (from a spawn node at player eye height), low_angle (hero, near the ground looking up: the camera moves closer and widens its FOV instead of sinking into the ground), detail (close-up), corridor (down a lane or corridor found inside the subject by a free-space scan, preferring the view in from its open end, walls on both sides).
+
+How: candidate poses on a ring/hemisphere (or along the corridor line) at the distance where the subject fills the shot's target share of the frame; each is checked with a THICK sphere sweep to points on the subject (thin rays miss corners), a near-lens sphere (camera inside or touching geometry is nudged forward or rejected), a ray grid through the frame, and a small beauty render per pose. Walls/terrain blocking the subject reject a pose, and so does a camera behind or inside a one-sided surface (a sight line or a quarter of the frame meeting a wall from behind: its back is not drawn, so the image would look through it). Foliage, fences, props and pipes in front are allowed (wanted, up to a limit) as framing; transparent materials (alpha, scissor, glass, foliage cards) are see-through cover at partial weight. Scored on rule-of-thirds placement, frame fill, level horizon, sky share, depth behind the subject (no flat wall right behind it), empty or featureless areas, near-wall clearance, near/far value contrast, foreground framing, surfaces seen from behind, the key light's direction (side or front-side beats a flat front-lit face) and the world edge (sky or void below the horizon).
+
+Returns the top 3 with score breakdowns and poses — three different views (one per side of the subject while the score allows, at least 25 degrees apart) — saves the best as a bookmark (default <shot>_<subject>), and renders the 3 as one sheet with real lighting (render:"best" or "none" to save context). ${COMMON} Saving the bookmark writes res://.summer/camera_bookmarks.json.`, frameShotShape, run(frameShot));
+}

package/dist/mcp/tools/spatial-tools.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { withEngine, missingEngineOpResult, ToolInputError, withOldEngineHint } from "./with-engine.js";
 import { executeSceneMutation } from "./scene-tools.js";
+import { SNAP_LIFT_MARGIN, SNAP_MAX_AUTO_LIFT, snapToSurface } from "../../core/capabilities/surface-snap.js";
 // engine_lacks_op fallbacks: ONE copy for every face (E2E 2026-09-03 F-16).
 import { ALIGN_DISTRIBUTE_FALLBACK, NAVIGATION_PROBE_FALLBACK, SNAP_TO_SURFACE_FALLBACK, STARCAST_FALLBACK, TEST_PLACEMENT_FALLBACK, } from "../../core/capabilities/engine-fallbacks.js";
 /** Hard budget for one tool's model-visible result. These ops are designed to
@@ -244,9 +245,14 @@ Use the default downward direction to seat props on floors, ramps, tables, or sh
 
 EVIDENCE BOUNDARY:
 - physics means Godot swept the subject's enabled collider shapes against body colliders and refined the first-contact bracket.
-- visual_aabb is an explicit broad-phase fallback for mesh-only geometry; it does not prove triangle contact, and alignUp is not applied from that approximate normal.
+- visual_aabb is the engine's broad-phase fallback for mesh-only geometry (no collider on the subject or the support): AABBs swept against AABBs. It does not prove triangle contact, and alignUp is not applied from that approximate normal.
+- visual_mesh: whenever the engine answers with visual_aabb (overlap_recovery_exceeded, gap_exceeds_hit_travel, surface_not_found, or a seat), a read-only probe measures the move from visible triangles instead: the subject's vertices cast along the direction onto the triangles of the meshes below (a surface cutting through the subject counts as sunk), plus the support's vertices under it cast back. One SetProp places the subject, a second read verifies the gap (the move is undone if it disagrees by more than 5 mm), and the scene is saved. The receipt says evidence visual_mesh, the engine's own answer under engine, verify {final_gap, ok}, and evidenceDetails (samples, triangles, whether the subject and the support have colliders). Meshes whose shader writes POSITION (screen-space quads) are not surfaces. When the triangles find no support either, the engine's failure is returned with mesh_fallback saying why.
 - initiallyOverlapping and backoffDistance expose bounded pre-sweep recovery. The tool fails instead of teleporting when the subject cannot be cleared within maxDistance.
 
+SUNK PROPS: when the subject starts inside its support (gap_exceeds_hit_travel with a start overlap), the tool lifts it against the cast direction by the overlap depth plus ${SNAP_LIFT_MARGIN} m (at most ${SNAP_MAX_AUTO_LIFT} m and the subject's own extent), snaps again from there, and keeps that only if it settles on a node it was sunk into; the receipt then carries recovery (lifted_by, original_local_position) and 'before' is the lifted pose. Otherwise the original position is restored.
+
+FAILURES EXPLAIN THEMSELVES: after gap_exceeds_hit_travel or overlap_recovery_exceeded a read-only starcast at the current pose adds start_overlap, blocking (the nodes it touches or sits inside), below, and a concrete next_step.
+
 The normal result is bounded below 5 KB and returns before/after transforms, supportPath, finalGap with an error bound, slopeDeg, evidence, and warnings. scenePath and subjectPath are always required; there is no editor-selection fallback. On an engine build that predates SnapToSurface the result is a structured engine_lacks_op failure naming the fallback.`, {
         scenePath: exactScenePath.describe("Exact scene containing the subject, e.g. 'res://levels/market.tscn'"),
         subjectPath: exactNodePath.describe("Exact Node3D path relative to the scene root, e.g. './Props/Crate'"),
@@ -286,14 +292,16 @@ The normal result is bounded below 5 KB and returns before/after transforms, sup
         // Cross-field: a raw zod shape cannot express it, so it stays here.
         if (gap > maxDistance)
             throw new ToolInputError("gap must not exceed maxDistance.");
-        const receipt = await executeSceneMutation(client, exactScene, [{
-                op: "SnapToSurface",
-                subject_path: exactSubject,
-                direction,
-                max_distance: maxDistance,
-                gap,
-                align_up: alignUp,
-            }]);
+        // ONE implementation for both faces (core/capabilities/surface-snap.ts):
+        // the snap, a starcast diagnosis on failure, and the sunk-prop lift.
+        const receipt = await snapToSurface(client, {
+            scenePath: exactScene,
+            subjectPath: exactSubject,
+            direction: direction,
+            maxDistance,
+            gap,
+            alignUp,
+        });
         return withOldEngineHint(receipt, "SnapToSurface", SNAP_TO_SURFACE_FALLBACK);
     }, compactResult({
         op: "SnapToSurface",

package/dist/mcp/tools/visual-tools.js

@@ -1,9 +1,12 @@
 import { z } from "zod";
-import { withEngine, missingEngineOpResult, withOldEngineHint } from "./with-engine.js";
+import { withEngine, missingEngineOpResult, withOldEngineHint, ToolInputError } from "./with-engine.js";
 import { withFailureReasonHint } from "./perception-tools.js";
 import { analyzedSnapshot, captureGame, captureScene, captureViewport, VIEWPORT_RECAPTURE_DELAY_MS, } from "../../core/capabilities/capture.js";
 import { describeFlatFrame } from "../../core/capabilities/frame-quality.js";
 import { CAMERA_BOOKMARK_ACTIONS, CAMERA_BOOKMARK_FALLBACK, SCREENSHOT_FRAMINGS, MAX_MARKS_CAP, buildCameraBookmarkOp, buildScenePreviewInput, formatSceneMarks, isFixedPoseFraming, readCameraPose, readSceneMarks, } from "../../core/capabilities/camera-view.js";
+import { checkMarkOcclusion, formatMarksWithOcclusion, rememberBookmarkRender, shotSheet, slotPolicy, } from "../../core/capabilities/seeing/seeing.js";
+import { parseVector3 } from "../../core/capabilities/seeing/math.js";
+import { seeingContent } from "./seeing-tools.js";
 // The capture path (content check, single viewport recapture, scene-kind read
 // for the no-camera confession) is ONE copy in core/capabilities/capture.ts,
 // shared with the CLI face; re-exported so tests and callers keep this door.
@@ -170,7 +173,7 @@ Static frame only — one moment, not motion. For a SEQUENCE of frames over time
         marks: z
             .boolean()
             .optional()
-            .describe('target:"scene" only, 3D scenes. Draw a Set-of-Mark overlay: numbered tags + box outlines over the largest visible VisualInstance3D nodes (lights excluded), ranked by projected screen area. The caption lists label -> node path (scene-root-relative) so you can name what you see. Works with every framing. 2D scenes return marks_unsupported. Default false.'),
+            .describe('target:"scene" only, 3D scenes. Draw a Set-of-Mark overlay: numbered tags + box outlines over the largest visible VisualInstance3D nodes (lights excluded), ranked by projected screen area. The caption lists label -> node path (scene-root-relative) so you can name what you see, and an occlusion test (centre + 4 bounds points from the rendered camera) notes "(hidden behind <path>)" on labels whose node is hidden: ignore those. Works with every framing. 2D scenes return marks_unsupported. Default false.'),
         max_marks: z
             .number()
             .int()
@@ -178,10 +181,36 @@ Static frame only — one moment, not motion. For a SEQUENCE of frames over time
             .max(MAX_MARKS_CAP)
             .optional()
             .describe(`marks:true only. Cap on numbered labels (engine default 32, at most ${MAX_MARKS_CAP}). The caption says when the cap truncated the list.`),
-    }, async ({ target, scenePath, framing, bookmark_name, size, nodePath, camera_path, camera_position, camera_look_at, fov, marks, max_marks, }) => {
+        compare_previous: z
+            .boolean()
+            .optional()
+            .describe('framing:"bookmark" only. Return ONE image of [previous render | now | difference map] for the bookmark, with the share of changed pixels (summer_shot_sheet compare_previous with this one bookmark); this render then replaces the bookmark\'s previous image in res://.summer/shots/<bookmark>.jpg. A plain bookmark render (no marks, at most 1024 px) only creates that image when it is missing and never overwrites the compare baseline.'),
+        update_previous: z
+            .boolean()
+            .optional()
+            .describe('framing:"bookmark" only. Replace the bookmark\'s previous image (its compare baseline) with this clean render. Default false: an existing baseline is kept.'),
+    }, async ({ target, scenePath, framing, bookmark_name, size, nodePath, camera_path, camera_position, camera_look_at, fov, marks, max_marks, compare_previous, update_previous, }) => {
+        if (compare_previous) {
+            // Same implementation as summer_shot_sheet: one bookmark row of
+            // [previous | now | difference].
+            return withEngine(async (client) => {
+                if (target !== "scene" || !bookmark_name || (framing !== undefined && framing !== "bookmark")) {
+                    throw new ToolInputError('compare_previous needs target:"scene" with framing:"bookmark" and bookmark_name. Nothing was sent.');
+                }
+                const result = await shotSheet(client, {
+                    scenePath,
+                    shots: [{ bookmark_name, ...(fov !== undefined ? { fov } : {}) }],
+                    compare_previous: true,
+                    max_size: 1536,
+                });
+                return { seeing: result, ...(result.ok ? {} : { failure_reason: result.failure_reason }) };
+            }, { onResult: (wrapped) => seeingContent(wrapped.seeing) });
+        }
         // Resolved inside the engine closure so a contradictory framing is a
         // classified invalid_input (nothing sent), never a transport failure.
         let preview;
+        let slotNotes = [];
+        let markOcclusion;
         return withEngine(async (client) => {
             if (target === "game")
                 return captureGame(client);
@@ -199,7 +228,27 @@ Static frame only — one moment, not motion. For a SEQUENCE of frames over time
                     marks,
                     max_marks,
                 });
-                return teachPreviewFailure(await captureScene(client, preview));
+                const snap = teachPreviewFailure(await captureScene(client, preview));
+                // One before/after slot per bookmark: a clean render creates it
+                // when missing; only update_previous replaces an existing one.
+                const bookmark = preview.framing?.startsWith("bookmark:") ? preview.framing.slice("bookmark:".length) : undefined;
+                if (snap.ok && snap.base64 && bookmark && snap.framing === preview.framing) {
+                    slotNotes = await rememberBookmarkRender(typeof client.getProjectRoot === "function" ? client.getProjectRoot() : undefined, bookmark, { base64: snap.base64, width: snap.width, height: snap.height }, preview.marks === true, slotPolicy({ updatePrevious: update_previous === true }));
+                }
+                // Labels on hidden nodes: test each labelled node from the
+                // rendered camera (centre + 4 bounds points).
+                const meta = snap.metadata;
+                const marked = snap.ok && preview.marks ? readSceneMarks(meta) : null;
+                const camera = readCameraPose(meta)?.position;
+                if (marked?.marks.length && camera) {
+                    try {
+                        markOcclusion = await checkMarkOcclusion(client, scenePath, parseVector3(camera, "camera_pose.position"), marked.marks);
+                    }
+                    catch (err) {
+                        markOcclusion = { occlusion: new Map(), note: `NOTE: the mark occlusion check could not run (${err instanceof Error ? err.message : String(err)}).` };
+                    }
+                }
+                return snap;
             }
             return captureViewport(client);
         }, {
@@ -367,11 +416,14 @@ Static frame only — one moment, not motion. For a SEQUENCE of frames over time
                             details.push(`camera pose: ${parts.join(", ")}`);
                     }
                     const marksSummary = readSceneMarks(meta);
-                    if (marksSummary)
-                        marksBlock = formatSceneMarks(marksSummary);
+                    if (marksSummary) {
+                        marksBlock = markOcclusion ? formatMarksWithOcclusion(marksSummary, markOcclusion.occlusion) : formatSceneMarks(marksSummary);
+                        if (markOcclusion?.note)
+                            marksBlock.push(markOcclusion.note);
+                    }
                 }
                 const detailNote = details.length ? `; ${details.join(", ")}` : "";
-                const trailer = [...warnings, ...notes];
+                const trailer = [...warnings, ...notes, ...slotNotes];
                 const caption = `${label} (${dims}${detailNote}). Saved to ${snap.localPath ?? "n/a"}.${frameCheck} Describe only what is visibly in the image above.` +
                     (marksBlock.length ? `\n\n${marksBlock.join("\n")}` : "") +
                     (trailer.length ? `\n\n${trailer.join("\n")}` : "");

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "_generated": "GENERATED from integrations/gemini — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Agent tooling for Summer Engine: MCP bridge, context primer, and game-dev skills. Use with the npm CLI for skill files on disk.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
@@ -27,6 +27,7 @@
     "./library/skills/3d-lighting/",
     "./library/skills/adaptive-music/",
     "./library/skills/agent-playtesting/",
+    "./library/skills/ai-characters-in-games/",
     "./library/skills/ambient-bed/",
     "./library/skills/animated-loop/",
     "./library/skills/animation-tree/",
@@ -37,11 +38,14 @@
     "./library/skills/brainstorm-game/",
     "./library/skills/brainstorming/",
     "./library/skills/browse-templates/",
+    "./library/skills/camera-rigs/",
     "./library/skills/celeste-momentum-platforming/",
     "./library/skills/character-animation-wiring/",
     "./library/skills/character-model/",
+    "./library/skills/character-movement/",
     "./library/skills/character-portrait/",
     "./library/skills/cinematic-cutscene/",
+    "./library/skills/combat-basics/",
     "./library/skills/concept-art/",
     "./library/skills/create-asset-sheet/",
     "./library/skills/debug/",
@@ -63,16 +67,21 @@
     "./library/skills/generate-motion/",
     "./library/skills/godogen-visual-proof-game-generation/",
     "./library/skills/headless-scripting/",
-    "./library/skills/host-authoritative-state/",
+    "./library/skills/in-game-purchases/",
     "./library/skills/instantiate-asset-pack/",
     "./library/skills/investigating-bugs/",
     "./library/skills/lumera-single-image-scene-reconstruction/",
     "./library/skills/make-game/",
+    "./library/skills/multiplayer/",
+    "./library/skills/multiplayer-movement/",
+    "./library/skills/multiplayer-project/",
+    "./library/skills/multiplayer-publish/",
+    "./library/skills/multiplayer-state/",
+    "./library/skills/multiplayer-testing/",
     "./library/skills/music-track/",
     "./library/skills/navigate-summer/",
     "./library/skills/new-project/",
     "./library/skills/organic-model/",
-    "./library/skills/peer-to-peer-multiplayer/",
     "./library/skills/pixel-art/",
     "./library/skills/play/",
     "./library/skills/playtesting-a-feature/",
@@ -83,11 +92,11 @@
     "./library/skills/remote-deploy/",
     "./library/skills/retarget/",
     "./library/skills/running-in-the-cloud/",
+    "./library/skills/save-load/",
     "./library/skills/scene-composition/",
     "./library/skills/scene-hierarchy-design/",
     "./library/skills/scene-scripting/",
     "./library/skills/scene-to-level/",
-    "./library/skills/setup-multiplayer/",
     "./library/skills/skill-create/",
     "./library/skills/skill-improve/",
     "./library/skills/skill-test/",
@@ -96,6 +105,17 @@
     "./library/skills/sound-effect/",
     "./library/skills/spatial-placement/",
     "./library/skills/sprite-sheet/",
+    "./library/skills/summer-analytics/",
+    "./library/skills/summer-friends/",
+    "./library/skills/summer-leaderboards/",
+    "./library/skills/summer-match-results/",
+    "./library/skills/summer-matchmaking/",
+    "./library/skills/summer-parties/",
+    "./library/skills/summer-player-data/",
+    "./library/skills/summer-store/",
+    "./library/skills/summer-world-chat/",
+    "./library/skills/summer-world-saves/",
+    "./library/skills/text-to-motion/",
     "./library/skills/tileable-texture/",
     "./library/skills/trailer-shot/",
     "./library/skills/tune-performance/",
@@ -115,6 +135,8 @@
     "./library/skills/vfx-smoke/",
     "./library/skills/vfx-water-ripple/",
     "./library/skills/voice-line/",
+    "./library/skills/web-and-touch-input/",
+    "./library/skills/web-compatibility-look/",
     "./library/skills/world-building-3d/",
     "./library/skills/writing-plans/",
     "./library/skills/writing-skills/"