feat(mod): in-game sushi-loop tracer (ALT+B)

Hover a belt and press ALT+B: the mod flood-fills the loop (belts,
undergrounds, splitters; balancers as graphs), prunes feed-on/feed-off
spurs so only the circulating core counts, sets one "read entire belt
(hold)" reader per game segment, clusters the readers at the junctions
where segments meet, and stitches them with a minimum spanning tree of
short player-legal wires (reach from the prototypes; unbridgeable gaps
get GPS-linked power-pole suggestions instead of script-cheated spans).
SHIFT+ALT+B removes exactly what the last trace added; a pyops-sushi
remote interface exposes trace/untrace for tooling and future UI.

Segment rules were derived empirically with isolated-reader probes, not
guessed: segments end at splitters and sideload merges (positional —
the input directly behind a belt continues its line; curves keep their
segment), undergrounds CONTINUE the segment with the buried span
readable, and tier-weaved undergrounds never cross lines because
pairing comes from the engine. Verified against exact item censuses on
a scripted torture loop (5 splitters, bypass arms rejoining by sideload
and by splitter, mixed tiers, a T2 line weaved through a T3 span):
reader counts at the theoretical minimum, one network, all wire spans
player-legal, and wire-vs-physical reconciling up to the documented
limits (splitter internals are circuit-invisible; reads bleed into
adjacent feeder branches).

The measurement (sushi.trace, protocol v8) lands in the app: the sushi
planner shows a one-click "measured N tiles" chip for its loop length.
Trace hotkeys register on the next full game restart (data-stage
prototypes); the control-side registration is guarded so reload_mods
on an older data stage doesn't crash.

Author: ApocDev

app/src/components/block/sushi-planner.tsx

@@ -5,7 +5,7 @@ import { planSushi, type ResolvedLogistics, type SushiFlow } from "../../lib/log
 import { constantCombinatorBlueprint, encodeBlueprint } from "../../lib/blueprint";
 import { fmtSpoilTime, Icon, useSpoilables } from "../../lib/icons";
 import { toast } from "../../lib/toast-store";
-import { bridgeBlueprintFn, bridgeStatusFn } from "../../server/bridge/fns";
+import { bridgeBlueprintFn, bridgeStatusFn, sushiTraceInfoFn } from "../../server/bridge/fns";
 import { fmtCount } from "./format.ts";
 import { Button } from "#/components/ui/button.tsx";
 import { Callout } from "#/components/ui/callout.tsx";
@@ -135,6 +135,14 @@ export function SushiPlanner({
   });
   const peer = bridge.data?.lastPeer ?? null;
   const connected = peer != null && Date.now() - peer.lastSeenMs < FRESH_MS;
+  // the mod's ALT+B loop tracer pushes its measurement here — offer, don't overwrite
+  const measured = useQuery({
+    queryKey: ["sushiTrace"],
+    queryFn: () => sushiTraceInfoFn(),
+    enabled: open,
+    refetchInterval: 3000,
+  });
+  const trace = measured.data ?? null;
   const buildBlueprint = () => {
     if (!plan) return null;
     const section = (role: SushiPlannerFlow["role"], active: boolean) => ({
@@ -208,13 +216,23 @@ export function SushiPlanner({
               <b className="text-foreground">Loop length</b> — sets lap time, and with it the pass
               frequency ("seen every") and how long items dwell on the loop. Longer loops buffer
               more but cycle slower: trace items get sparse and spoilables rot in transit (flagged
-              when riding the loop eats over a quarter of an item's spoil time).
+              when riding the loop eats over a quarter of an item's spoil time). With the game
+              linked, hover any belt of the built loop and press ALT+B — the mod traces it, wires
+              every segment onto one red network for reading, and the measured length appears here
+              as a one-click "measured" chip (SHIFT+ALT+B undoes the last trace).
             </p>
             <p>
               The planner covers capacity and composition only — it can't verify the control side.
               Without filtered or circuit-limited insertion a single item will eventually flood any
               sushi loop.
             </p>
+            <p>
+              <b className="text-foreground">Read accuracy</b> — the wire runs a little under the
+              true stock: items inside splitters are invisible to circuits (nothing any wiring can
+              fix), and reads can include items on feeder branches next to the loop. On a healthy
+              circulating loop the error is a handful of items; treat set-points as self-correcting
+              approximations, not exact counts.
+            </p>
             <p>
               <b className="text-foreground">Getting the constants in game</b> — "to cursor in game"
               drops a ready-made constant combinator on your cursor via the live bridge (each item
@@ -249,6 +267,19 @@ export function SushiPlanner({
                   className="w-24"
                 />
                 <span className="text-sm text-muted-foreground">tiles</span>
+                {trace && trace.tiles !== tiles && (
+                  <Tooltip
+                    content={`traced in-game (ALT+B): ${trace.tiles} tiles, ${trace.segments} segment(s)${trace.closed ? "" : " — not a closed loop"} — click to use`}
+                  >
+                    <Button
+                      variant="outline"
+                      size="xs"
+                      onClick={() => setTilesPersisted(trace.tiles)}
+                    >
+                      <Gamepad2 className="size-3" /> measured {trace.tiles}
+                    </Button>
+                  </Tooltip>
+                )}
               </div>
             </div>
             {plan && (

app/src/server/bridge/fns.ts

@@ -8,6 +8,7 @@ import { createServerFn } from "@tanstack/react-start";
 import * as b from "./server.ts";
 import { requestFromMod } from "./inspect.ts";
 import { factorioLaunchInfo, launchFactorio } from "../factorio-launch.server.ts";
+import { lastSushiTrace } from "./handlers/sushi.ts";
 
 /** Ensure the bridge is listening and return its status. Calling this from the
  * UI (polled) is what starts the socket — idempotent and HMR-safe. */
@@ -35,6 +36,13 @@ export const bridgeLocateFn = createServerFn({ method: "POST" })
     };
   });
 
+/** The latest in-game sushi-loop trace (tiles measured by the mod's ALT+B
+ * tracer), if any arrived this app session — the planner offers it as the loop
+ * length. */
+export const sushiTraceInfoFn = createServerFn({ method: "GET" }).handler(async () => {
+  return lastSushiTrace();
+});
+
 /** 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. */

app/src/server/bridge/handlers.ts

@@ -9,6 +9,7 @@ import { handleResearch } from "./handlers/research.ts";
 import { handleTurd } from "./handlers/turd.ts";
 import { handleBuilt } from "./handlers/built.ts";
 import { handleStats } from "./handlers/stats.ts";
+import { handleSushiTrace } from "./handlers/sushi.ts";
 import { handleTaskCapture, handleTaskList } from "./handlers/tasks.ts";
 import { handleModResult } from "./inspect.ts";
 
@@ -32,6 +33,8 @@ const handlers: Record<string, BridgeHandler> = {
   "state.built": handleBuilt,
   // Live force state: production/consumption rates → production_stats (planned-vs-actual).
   "state.stats": handleStats,
+  // The in-game sushi tracer measured (and wired) a belt loop — hold the reading.
+  "sushi.trace": handleSushiTrace,
   // The in-game New-task dialog filed a task (title/description + best-effort anchors).
   "task.capture": handleTaskCapture,
   // The in-game panel pulls the project's tasks to render (list + detail).

app/src/server/bridge/handlers/sushi.ts

@@ -0,0 +1,38 @@
+/**
+ * sushi.trace — the mod's in-game loop tracer just measured (and wired) a belt
+ * loop; hold the latest measurement so the sushi planner can offer it as the
+ * loop length. In-memory only: a measurement is a point-in-time reading of the
+ * save, not project data.
+ */
+import type { BridgeRequest, BridgeResponse } from "../protocol.ts";
+
+export type SushiTrace = {
+  tiles: number;
+  belts: number;
+  segments: number;
+  readers: number;
+  skipped: number;
+  closed: boolean;
+  receivedAt: number;
+};
+
+let last: SushiTrace | null = null;
+
+export function handleSushiTrace(req: BridgeRequest): BridgeResponse | null {
+  const p = (req.payload ?? {}) as Partial<SushiTrace>;
+  if (typeof p.tiles !== "number" || !(p.tiles > 0)) return null;
+  last = {
+    tiles: Math.round(p.tiles),
+    belts: typeof p.belts === "number" ? p.belts : 0,
+    segments: typeof p.segments === "number" ? p.segments : 0,
+    readers: typeof p.readers === "number" ? p.readers : 0,
+    skipped: typeof p.skipped === "number" ? p.skipped : 0,
+    closed: p.closed === true,
+    receivedAt: Date.now(),
+  };
+  return null;
+}
+
+export function lastSushiTrace(): SushiTrace | null {
+  return last;
+}

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 = 7;
+export const PROTOCOL_VERSION = 8;
 
 /** A request from the mod. `type` selects the handler; `payload` is type-specific. */
 export type BridgeRequest = {

docs/bridge.md

@@ -32,6 +32,24 @@ on any page. The same tab hosts the companion-mod installer (see below).
   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).
+- **Sushi-loop tracer (`mod/sushi.lua`):** hover a belt and press ALT+B — the mod
+  flood-fills the belt loop (belts, undergrounds, splitters; lane balancers are
+  handled as graphs), prunes feed-on/feed-off spurs so only the circulating core
+  counts, sets one "read entire belt (hold)" reader per game segment (segments
+  end at splitters and sideload merges; undergrounds CONTINUE the segment,
+  buried span included — probed empirically with isolated readers), places the
+  readers at the junction cluster where segments meet, and connects them with a
+  minimum spanning tree of short player-legal wires (prototype reach; if a gap
+  can't be bridged belt-to-belt it prints GPS-linked power-pole suggestions
+  instead). Skip-and-warn on belts you already wired. The measured loop
+  (`sushi.trace`: tiles/segments/closed) lands in the app, where the sushi
+  planner offers it as a one-click loop length. SHIFT+ALT+B removes exactly what
+  the last trace added. A `pyops-sushi` remote interface exposes trace/untrace
+  for tooling. Read accuracy: splitter internals aren't circuit-readable (the
+  read undercounts by the in-splitter transit population) and "entire belt"
+  zones bleed into adjacent feeder branches — on a circulating loop the error
+  is a handful of items either way. Verified against exact item censuses on a
+  scripted torture loop (5 splitters, bypass arms, tier-weaved undergrounds).
 - **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

@@ -12,13 +12,14 @@ local mod_gui = require("__core__.lualib.mod-gui")
 local Summary = require("summary")
 local Combinator = require("combinator")
 local Tasks = require("tasks")
+local Sushi = require("sushi")
 
 local PANEL_NAME = "pyops_panel"
 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 = 7
+local PROTOCOL_VERSION = 8
 
 local function get_player(event)
   if not event.player_index then
@@ -148,6 +149,11 @@ Tasks.send = function(player, request_type, payload)
   send_request(player, request_type, payload)
 end
 
+-- Same hook for the sushi-loop tools (sushi.trace measurements → the planner).
+Sushi.send = function(player, request_type, payload)
+  send_request(player, request_type, payload)
+end
+
 -- Reply to an app→mod request (a `cmd.*` the app pushed with a request_id). We
 -- echo that request_id in a `bridge.result` so the app correlates it back to the
 -- awaiting caller (see server/bridge/inspect.ts).
@@ -869,6 +875,45 @@ script.on_event("pyops-toggle-panel", function(event)
   toggle_panel(get_player(event))
 end)
 
+-- pcall'd: after a control-only reload (game.reload_mods) the data stage hasn't
+-- run, so a freshly added custom-input prototype may not exist yet — skip the
+-- hotkeys then (the remote interface still works) instead of crashing the load.
+pcall(function()
+  script.on_event("pyops-trace-sushi", function(event)
+    local player = get_player(event)
+    if player then
+      Sushi.trace(player)
+    end
+  end)
+  script.on_event("pyops-untrace-sushi", function(event)
+    local player = get_player(event)
+    if player then
+      Sushi.untrace(player)
+    end
+  end)
+end)
+
+-- Tooling entry (dev/MCP + future UI surfaces): trace/untrace without a hotkey.
+remote.add_interface("pyops-sushi", {
+  trace_at = function(player_index, position)
+    local player = game.get_player(player_index)
+    if not player then
+      return false
+    end
+    local seed = player.surface.find_entities_filtered({
+      position = position,
+      radius = 2,
+      type = { "transport-belt", "underground-belt", "splitter" },
+      limit = 1,
+    })[1]
+    return Sushi.trace(player, seed)
+  end,
+  untrace = function(player_index)
+    local player = game.get_player(player_index)
+    return player and Sushi.untrace(player) or false
+  end,
+})
+
 script.on_event(defines.events.on_gui_click, function(event)
   local player = get_player(event)
   if not player or not event.element or not event.element.valid then

mod/data.lua

@@ -13,6 +13,21 @@ data:extend({
     consuming = "none",
     action = "lua"
   },
+  -- Sushi-loop tools: trace + wire the hovered belt's loop; undo the last trace.
+  {
+    type = "custom-input",
+    name = "pyops-trace-sushi",
+    key_sequence = "ALT + B",
+    consuming = "none",
+    action = "lua"
+  },
+  {
+    type = "custom-input",
+    name = "pyops-untrace-sushi",
+    key_sequence = "SHIFT + ALT + B",
+    consuming = "none",
+    action = "lua"
+  },
   -- Mirrors the smart-pipette (Q) key so the summary panel can pipette the good /
   -- building under the cursor. Linked (no own key) — it fires alongside the normal
   -- pipette, which still works everywhere else.

mod/locale/en/pyops.cfg

@@ -1,5 +1,7 @@
 [controls]
 pyops-toggle-panel=Toggle PyOps panel
+pyops-trace-sushi=PyOps: trace sushi loop (hovered belt)
+pyops-untrace-sushi=PyOps: undo last sushi trace
 
 [shortcut-name]
 pyops-toggle-panel=PyOps