feat(bridge): deliver app-built blueprints to the game cursor

New cmd.blueprint message (protocol v7): the app sends a blueprint
string, the mod imports it onto the player's cursor as a TEMPORARY
stack — clearing it destroys it instead of stuffing the inventory,
since these are regenerable artifacts. Refuses politely when the
cursor is already holding something.

Author: ApocDev

app/src/server/bridge/fns.ts

@@ -35,6 +35,16 @@ export const bridgeLocateFn = createServerFn({ method: "POST" })
     };
   });
 
+/** Put a blueprint string on the connected player's cursor (cmd.blueprint) —
+ * e.g. the sushi planner's set-point combinator. Fire-and-forget; returns
+ * whether a peer was reachable. */
+export const bridgeBlueprintFn = createServerFn({ method: "POST" })
+  .validator((d: { bp: string }) => d)
+  .handler(async ({ data }) => {
+    b.ensureBridge();
+    return { sent: b.sendToPeer({ type: "cmd.blueprint", payload: { bp: data.bp } }) };
+  });
+
 /** Run a user-APPROVED Lua snippet in the game (#15) — the apply half of the
  * assistant's gameEval propose-then-approve gate. Only the chat card's Run
  * button calls this; the agent tool itself never executes. The mod refuses when

app/src/server/bridge/protocol.ts

@@ -10,7 +10,7 @@
 // The bridge wire contract. Bump on BOTH sides (here and the mod's PROTOCOL_VERSION
 // in control.lua) whenever the message shapes change — each side warns when the
 // other reports a different version.
-export const PROTOCOL_VERSION = 6;
+export const PROTOCOL_VERSION = 7;
 
 /** A request from the mod. `type` selects the handler; `payload` is type-specific. */
 export type BridgeRequest = {

docs/bridge.md

@@ -26,10 +26,12 @@ on any page. The same tab hosts the companion-mod installer (see below).
   per ore), and item production stats — pushed on connect and on relevant in-game
   events, always as the full authoritative set (no delta merging on the app side).
 - **Commands → game:** show a production-block panel in-game (`cmd.show_block`)
-  and close it again (`cmd.hide_block`), and locate producers/consumers/storage
+  and close it again (`cmd.hide_block`), locate producers/consumers/storage
   (`cmd.locate`, relayed to the
   [Factory Search](https://mods.factorio.com/mod/FactorySearch) mod's remote
-  interface).
+  interface), and put an app-built blueprint string on the player's cursor
+  (`cmd.blueprint` — e.g. the sushi planner's set-point combinator; the mod
+  refuses politely if the cursor is holding something).
 - **Task panel:** the in-game panel's **Tasks** tab pulls the project's
   tasks with `task.list` (the app replies with the full set — title, status,
   priority, body, steps, and links resolved to Factorio sprite paths) and renders

mod/control.lua

@@ -18,7 +18,7 @@ local BUTTON_NAME = "pyops_button"
 local SHORTCUT_NAME = "pyops-toggle-panel"
 -- Bridge wire contract. Keep in lockstep with PROTOCOL_VERSION in the app's
 -- src/server/bridge/protocol.ts — each side warns if the other reports a different one.
-local PROTOCOL_VERSION = 6
+local PROTOCOL_VERSION = 7
 
 local function get_player(event)
   if not event.player_index then
@@ -404,6 +404,33 @@ local function locate_good(player, payload)
   end
 end
 
+-- Put an app-sent blueprint string on the player's cursor (cmd.blueprint) —
+-- the same import_stack delivery the request-combinator generator uses. Refuses
+-- politely when the cursor is holding something so nothing gets clobbered.
+local function deliver_blueprint(player, payload)
+  local bp = payload and payload.bp
+  if type(bp) ~= "string" or bp == "" then
+    return
+  end
+  local cursor = player.cursor_stack
+  if not cursor then
+    return
+  end
+  if cursor.valid_for_read then
+    player.print({ "", "PyOps: clear your cursor first — a blueprint is waiting." })
+    return
+  end
+  cursor.set_stack({ name = "blueprint" })
+  if cursor.import_stack(bp) < 0 then
+    cursor.clear()
+    player.print({ "", "PyOps: failed to import the blueprint from the app." })
+    return
+  end
+  -- temporary: the print vanishes when the cursor is cleared (Q) instead of
+  -- landing in the inventory — these are regenerable artifacts, not keepsakes
+  player.cursor_stack_temporary = true
+end
+
 -- ── Read-only game-world inspection (app → mod cmd.* → reply) ──────────────────
 -- All bounded and structured: the app's assistant tools call these to ground a
 -- task in live evidence. No whole-map dumps.
@@ -652,6 +679,10 @@ local function handle_bridge_response(player, response)
   elseif response.type == "cmd.locate" then
     -- the app asked us to find a good in the world (web "locate in game" button)
     locate_good(player, response.payload)
+  elseif response.type == "cmd.blueprint" then
+    -- the app sent a blueprint string (e.g. the sushi set-point combinator) —
+    -- put it on the cursor, same delivery as the request-combinator generator
+    deliver_blueprint(player, response.payload)
   elseif response.type == "cmd.show_block" then
     -- the app pushed a solved block to render as an in-game build sheet
     Summary.show(player, response.payload)