breakpoint-mcp 1.83.0 → 1.84.0

package/dist/tools/tabletop.js

@@ -1411,6 +1411,96 @@ export function registerTabletopTools(server, bridge, config) {
     function replacedField(existed) {
         return existed ? { replaced: true } : {};
     }
+    /**
+     * Which scene the editor is editing AFTER this call — 298.
+     *
+     * 🔴 FOUR TOOLS MOVED THE EDITOR AND NONE OF THEM SAID SO, AND THE FACT WAS
+     * ALREADY WRITTEN DOWN TWICE IN THIS REPOSITORY. `guardWriteTarget`'s own
+     * comment forty lines up says the addon's `scene.new` "calls
+     * `EditorInterface.open_scene_from_path(path)`"; `tabletop-plane.integration.mjs`
+     * opens its live family with *every `*_create` decomposes onto scene.new → …
+     * → scene.save, which SWITCHES the edited scene, so the four disk writers run
+     * first and the in-scene work follows one scene_open*. Both are correct. Both
+     * are in files a CALLER never opens, and the tool surface said nothing — no
+     * description, no field, nothing in `TOOL_CATALOG.md`.
+     *
+     * 🔴 MEASURED AT 298 ON A LIVE GODOT 4.7, ON THE DEFAULT SURFACE. Compose a
+     * table, call `card_template_create`, then `card_instance` with `parent: "."`
+     * exactly as its own description invites: the card is created, `bound` lists
+     * the slot, `isError` is false — and the card is in the CARD TEMPLATE. The
+     * user's table is untouched. Every call in that sequence answers success.
+     *
+     * 🔵 IT IS READ, NOT ASSUMED. `spec.path` is what the compose ASKED for; this
+     * is what the editor ANSWERS, which is the difference between an echo and a
+     * measurement (155 §2) — and the two can differ, because `clearStaleTab` may
+     * have moved the editor before the write and a failed open would leave it
+     * somewhere else again.
+     *
+     * 🔵 AND IT IS SPREAD, NOT RESTATED, FOR `wroteDestination`'s REASON (284): a
+     * fifth composite that decomposes onto `scene.new` cannot be added with the
+     * reporting half missing. `contract_check` check 36 holds that population.
+     *
+     * 🆕 299 — AND THE ANSWER TO 298's FINDING IS NOW THE ONE 298 DECLINED TO
+     * TAKE IN-SESSION. 298 filed `tabletop-creators-leave-the-caller-elsewhere`
+     * as a `user` row rather than deciding it: whether the four should RESTORE
+     * the caller's scene is a change to what a shipped tool does to the editor,
+     * and this project steers those before it builds them. Steered at 299 —
+     * restore — with the argument that decided it recorded here, because the
+     * next person to read this block will want to know why the behaviour flipped
+     * one session after it was documented: **298's description never reached a
+     * user.** The merge sat untagged behind a release backlog, so both the
+     * warning label and its removal ship in the same cut and no caller ever saw
+     * the surface promise a move it no longer makes.
+     */
+    /** Which scene the editor is editing right now, or `null` for none open. */
+    async function currentEditedScene() {
+        const open = await emit("scene.list_open", {});
+        return typeof open?.current === "string" ? open.current : null;
+    }
+    /**
+     * Put the caller back on the scene they were editing when the call arrived.
+     *
+     * 🔴 BEST EFFORT, AND DELIBERATELY NOT A FAILURE PATH. The file is written
+     * and saved by the time this runs. Throwing here would report a create that
+     * SUCCEEDED as an error, and the caller's correct response to an error —
+     * retry — would write it a second time. So a reopen that cannot happen
+     * leaves the editor where the decomposition left it, and the caller learns
+     * that from `edited_scene`, which is READ afterwards and therefore cannot
+     * agree with a restore that did not occur. The honest report replaces the
+     * exception; it does not merely soften it.
+     *
+     * 🔵 THREE NO-OPS, EACH FOR ITS OWN REASON. `null` means the editor held no
+     * scene, so there is nothing to go back TO and the created scene stays open
+     * — inventing a close would be a second unasked-for movement. Already
+     * current means the decomposition did not move us, or `clearStaleTab`
+     * already put us back. And a `before` whose file is gone cannot be reopened:
+     * `scene.open` would answer *Scene not found* and turn a successful create
+     * into a refusal, which is the failure path this function exists to avoid.
+     */
+    async function restoreEditedScene(before) {
+        if (before === null)
+            return;
+        if (await currentEditedScene() === before)
+            return;
+        if (!fs.existsSync(resolveInsideProject(before, config.projectPath, "path")))
+            return;
+        try {
+            await emit("scene.open", { path: before });
+        }
+        catch {
+            // Swallowed on purpose — see the comment above. `edited_scene` reports
+            // where the editor actually is, so a failed restore is visible, not lost.
+        }
+    }
+    /**
+     * Restore, then REPORT — in that order, and the order is the claim. Reading
+     * first and restoring after would answer with a path the editor had already
+     * left, which is 155 §2's echo wearing a measurement's clothes one more time.
+     */
+    async function editedSceneField(before) {
+        await restoreEditedScene(before);
+        return { edited_scene: await currentEditedScene() };
+    }
     /**
      * The second half, run only AFTER the confirmation gate has been cleared —
      * closing a scene tab is a visible side effect and must not happen on a call
@@ -1477,7 +1567,7 @@ export function registerTabletopTools(server, bridge, config) {
         title: "Create card template",
         description: "Build a reusable card scene (a PackedScene) from a slot spec, with a generated script-backed set_data() / set_face(). " +
             "Named slots (label / rich_text / texture / panel / badge) become the card's regions; card_instance and card_deck_from_table " +
-            "bind data to them by slot name. Optional inline theme and a two-sided card back. DESTRUCTIVE (writes a scene + script) — gated by confirmation.",
+            "bind data to them by slot name. Optional inline theme and a two-sided card back. DESTRUCTIVE (writes a scene + script) — gated by confirmation. Puts the editor back on the scene you had open; `edited_scene` names where it landed.",
         inputSchema: {
             path: z.string().describe("Where to save the template scene, e.g. res://ui/cards/Card.tscn"),
             size: z.object({ width: z.number().int().positive(), height: z.number().int().positive() }).describe("Card dimensions in px"),
@@ -1535,8 +1625,13 @@ export function registerTabletopTools(server, bridge, config) {
         if (blocked)
             return blocked;
         try {
+            // 🆕 299 — READ BEFORE THE FIRST THING THAT CAN MOVE THE EDITOR, which is
+            // `clearStaleTab` and not `scene.new`: on an overwrite the stale-tab close
+            // has already changed `current` by the time the decomposition runs, so a
+            // capture taken any later restores the caller to the wrong scene.
+            const before = await currentEditedScene();
             await clearStaleTab(a.path);
-            return ok({ ...await emitCardTemplate(emit, a), ...replacedField(existed) });
+            return ok({ ...await emitCardTemplate(emit, a), ...replacedField(existed), ...(await editedSceneField(before)) });
         }
         catch (err) {
             return fail(err);
@@ -1575,7 +1670,7 @@ export function registerTabletopTools(server, bridge, config) {
     server.registerTool("card_hand_layout", {
         title: "Lay out a hand of cards",
         description: "Instance N cards under a container and arrange them as a row, fan, stack, or grid. Undoable node authoring. Each card carries its own " +
-            "data (bound via the template's set_data) and face state; spacing / overlap / fan_angle / columns / align / origin tune the arrangement.",
+            "data (bound via the template's set_data) and face state.",
         inputSchema: {
             template_path: z.string().describe("Card template scene, e.g. res://ui/cards/Card.tscn"),
             parent: z.string().describe("Container node path the cards are instanced under; \".\" for the root"),
@@ -1700,7 +1795,7 @@ export function registerTabletopTools(server, bridge, config) {
         title: "Create board scene",
         description: "Build a board scene whose children are addressable cells (each a cell_<id> node in the board_cells group) from a ring, grid, or explicit-cells layout. " +
             "Cells are Marker2D (or Control) anchors positioned by pure layout math; an optional background (color or res:// art) sits behind them. " +
-            "General-purpose — cells carry only caller-supplied ids. DESTRUCTIVE (writes a scene) — gated by confirmation. Returns the cell_id → node_path + position map.",
+            "General-purpose — cells carry only caller-supplied ids. DESTRUCTIVE (writes a scene) — gated by confirmation. Puts the editor back on the scene you had open; `edited_scene` names where it landed.",
         inputSchema: {
             path: z.string().describe("Where to save the board scene, e.g. res://ui/board/Board.tscn"),
             layout: boardLayout.describe("ring{cells[]} | grid{rows,cols} | cells{cells[{id,x,y}]}"),
@@ -1733,8 +1828,13 @@ export function registerTabletopTools(server, bridge, config) {
         if (blocked)
             return blocked;
         try {
+            // 🆕 299 — READ BEFORE THE FIRST THING THAT CAN MOVE THE EDITOR, which is
+            // `clearStaleTab` and not `scene.new`: on an overwrite the stale-tab close
+            // has already changed `current` by the time the decomposition runs, so a
+            // capture taken any later restores the caller to the wrong scene.
+            const before = await currentEditedScene();
             await clearStaleTab(a.path);
-            return ok({ ...await emitBoardCreate(emit, a), ...replacedField(existed) });
+            return ok({ ...await emitBoardCreate(emit, a), ...replacedField(existed), ...(await editedSceneField(before)) });
         }
         catch (err) {
             return fail(err);
@@ -1765,7 +1865,7 @@ export function registerTabletopTools(server, bridge, config) {
         title: "Create tile-backed board",
         description: "Build a tile-backed board scene: a TileMapLayer grid whose cells are addressable by integer [x, y] tile coordinates (cols wide × rows tall). " +
             "The layer binds a TileSet — a supplied `tileset` .tres, or a fresh empty one created at <scene>_tiles.tres — so it has a real tile_size (the coordinate frame placement uses); `paint` optionally fills the whole grid with one tile from the bound tileset. " +
-            "General-purpose — cells carry only coordinates. Adds no addon method — decomposes onto scene.new → tileset.create → tilemaplayer.create → tilemap.set_cells_rect → scene.save. DESTRUCTIVE (writes a scene, and a TileSet .tres unless `tileset` is supplied) — gated by confirmation. Returns the layer path + grid dimensions + tile size.",
+            "General-purpose — cells carry only coordinates. DESTRUCTIVE (writes a scene, and a TileSet .tres unless `tileset` is supplied) — gated by confirmation. Puts the editor back on the scene you had open; `edited_scene` names where it landed.",
         inputSchema: {
             path: z.string().describe("Where to save the board scene, e.g. res://ui/board/TileBoard.tscn"),
             rows: z.number().int().positive().describe("Grid row count (cell y ranges 0..rows-1)"),
@@ -1801,8 +1901,13 @@ export function registerTabletopTools(server, bridge, config) {
         if (blocked)
             return blocked;
         try {
+            // 🆕 299 — READ BEFORE THE FIRST THING THAT CAN MOVE THE EDITOR, which is
+            // `clearStaleTab` and not `scene.new`: on an overwrite the stale-tab close
+            // has already changed `current` by the time the decomposition runs, so a
+            // capture taken any later restores the caller to the wrong scene.
+            const before = await currentEditedScene();
             await clearStaleTab(a.path);
-            return ok({ ...await emitBoardTileCreate(emit, a), ...replacedField(existed) });
+            return ok({ ...await emitBoardTileCreate(emit, a), ...replacedField(existed), ...(await editedSceneField(before)) });
         }
         catch (err) {
             return fail(err);
@@ -1812,7 +1917,7 @@ export function registerTabletopTools(server, bridge, config) {
     server.registerTool("board_tile_place", {
         title: "Place a node on a tile coordinate",
         description: "Snap an existing node (a card or piece instance) onto a TileMapLayer cell by integer [x, y] tile coordinate. Undoable node authoring. " +
-            "The cell's local position is computed from `tile_size` — centre `(coord + 0.5) × tile_size` (default) or corner `coord × tile_size` — matching Godot's TileMapLayer.map_to_local, plus an optional `align` offset. With `reparent` (default true) the node is moved under the layer so the coordinate is layer-local. Decomposes onto node.reparent + node.set_property. Returns the node's new path and local position.",
+            "The cell's local position is computed from `tile_size` — centre `(coord + 0.5) × tile_size` (default) or corner `coord × tile_size` — matching Godot's TileMapLayer.map_to_local, plus an optional `align` offset. Decomposes onto node.reparent + node.set_property. Returns the node's new path and local position.",
         inputSchema: {
             layer: z.string().describe("TileMapLayer node path in the open scene"),
             node: z.string().describe("Node path of the node to place (a card / piece already in the scene)"),
@@ -1835,7 +1940,7 @@ export function registerTabletopTools(server, bridge, config) {
     server.registerTool("piece_template_create", {
         title: "Create piece template",
         description: "Build a reusable piece (token) scene from a spec: an Art node (Sprite2D under a Node2D root, TextureRect under a Control root), an optional Label, an optional hit area (Area2D + CollisionShape2D), and an optional two-sided Back, plus a generated script-backed set_data() / set_face(). set_data binds art / color / label; set_face flips face/back visibility. " +
-            "Decomposes onto scene.new → node.add → node.set_property → resource.create → scene.save. DESTRUCTIVE (writes a scene + script) — gated by confirmation. Returns the scene path + the created-node map.",
+            "DESTRUCTIVE (writes a scene + script) — gated by confirmation. Puts the editor back on the scene you had open; `edited_scene` names where it landed.",
         inputSchema: {
             path: z.string().describe("Where to save the template scene, e.g. res://ui/pieces/Piece.tscn"),
             size: z.object({ width: z.number().int().positive(), height: z.number().int().positive() }).describe("Token size in px (drives the hit-area extents and, for a Control root, the Art size)"),
@@ -1881,8 +1986,13 @@ export function registerTabletopTools(server, bridge, config) {
         if (blocked)
             return blocked;
         try {
+            // 🆕 299 — READ BEFORE THE FIRST THING THAT CAN MOVE THE EDITOR, which is
+            // `clearStaleTab` and not `scene.new`: on an overwrite the stale-tab close
+            // has already changed `current` by the time the decomposition runs, so a
+            // capture taken any later restores the caller to the wrong scene.
+            const before = await currentEditedScene();
             await clearStaleTab(a.path);
-            return ok({ ...await emitPieceTemplate(emit, a), ...replacedField(existed) });
+            return ok({ ...await emitPieceTemplate(emit, a), ...replacedField(existed), ...(await editedSceneField(before)) });
         }
         catch (err) {
             return fail(err);