WIP: feat(panel): a playtest panel in the browser, with a live saved-flags editor, on the modding API #2190

Draft
BeanSeller wants to merge 4 commits from BeanSeller/Longshot:feat/playtest-panel into main
First-time contributor

Summary

Depends on #1958 (the modding API). As HumanBean suggested, the panel's game side is now a small mod on the modding
API, and the PR changes no host code: the bridge commands it carried before (warp, give, spawn, enemies,
edit, flags and the rest) are gone. Its mod builds on mod_eval and the API of #1958, so it is work in progress
until #1958 is merged.

Testing a mod or a change by hand means switching between the game and a terminal to teleport, hand out items, or
check what the game just did. This PR adds a playtest panel: a page in the browser beside the game (or on a phone
on the same network) that walks a tester through a list of steps with pass and fail buttons, goes to places, hands out
items, saves notes with Link's position and a screenshot, records short clips, and shows the saved flags live,
flipping a checkbox by itself when the game changes a flag, highlighting what just changed, and writing a flag when the
tester ticks it. Steps can carry their own set-up buttons and one-click notes. Everything is written to a session
folder as it happens (notes, screenshots, finished clips, flag changes, the current status, an access log), and a
messages file is shown at the top of the page, so a person or a program following a session can see it live and answer
the tester; the panel assumes no one in particular is watching. Project-specific cards are the user's own HTML files in
an extras folder, kept outside the repository.

Three parts, all in scripts/playtest_panel/:

  • mod/, the mod local/playtest-panel: exports the panel calls (state, readFlags, setFlag, destinations,
    travel, moveTo, give, heal, rupees, spawn, enemies) on game.flags, player, world, items.grant
    and actors, and does nothing on its own. Flags are read by name, 400 a frame, so thousands stay inside a callback's
    budget; a flag is written through game.flags.set (the game's own setter), which also settles the "a write in
    place may not be saved" limit the earlier version had.
  • server.py: standard library Python on 127.0.0.1. It calls the mod's exports through the bridge's mod_eval (the
    game started with longshot mod run --eval), and uses main's own bridge commands for the rest: status,
    teleport, shot, press, and subscribe (oot with changes) for every flag the game changes while the flags
    card is open. --game <folder> finds the running game's socket with longshot mod attach --json.
  • index.html: the page. Extra panels get panel.call(export, ...args) beside panel.bridge(cmd, args).

The game keeps only the flag names' MurMur3 hashes, so names come from files the user gives (--flag-names), and the
page can learn a name typed in its search box. A flag without a name shows by its hash when it changes, and is read
only: the API writes flags by name.

Read first: scripts/playtest_panel/mod/src/main.ts, scripts/playtest_panel/server.py (Game.call, Flags),
docs/dev/reference/playtest-panel.md.

Testing

Tested: Windows 11, RTX 4070 Ti SUPER, driver 610.88.

  • The mod, against #1958's head (66984acf): longshot-mod check passes (the manifest, oxc compile and link, tsc --noEmit with TypeScript 7.0.2: no errors); longshot-mod lint: no problems (the permissions the code uses are the ones declared); longshot-mod test in the fake game: 1 passed, 7 skipped (the 7 call the mod's exports and are the real game's: the fake game runs tests in Node, where a module importing the API cannot load).
  • In the game: #1958's head built as a game folder with nx2/make_game.py and the TypeScript compiler (scripts/longshot_ts.py build); in its test mode (--mod-tests) the mod started (script runtime: started local/playtest-panel 0.1.0 (18.1 ms, 489 KB ...)), with no fault.
  • The panel: python -I -B tests/test_playtest_panel.py passes (10: MurMur3 against known values, the names files, the mod_eval request a call sends and its error, flags read by name and the changes subscribe reports, a dropped-changes more reading the flags again, learning a name, writing a flag by name, going to a place (a move the game drops is asked again), buttons with calls and bridge requests, /call, step actions, the messages file, extras, the page-only header, the LAN access key, the session files and the access log). python -I -B tests/run_all.py --changed: 11 passed, 3 failed, 1 skipped; the 3 (test_dev_build, test_dev_packs, test_mise_build) fail the same way on this PC on the branch's previous tree, which shares main's files they read.
  • The earlier version of the panel (the one with host commands) was played in the game on 22 Nov, as this PR's first comment says; the page, the session files and the LAN access are the same code.

Not run in the game yet, and why: on this PC, #1958's head does not reach play from a save. With no mod at all (mods/ left out), the title skip loads a save and the game stays on the loading screen (control: state menu -> loading, an nn.npln.Worker mutex waiting); main at a2dc538 loads the same save. Building it on Windows with llvm-mingw also needed two local fixes, not in this PR (near is a macro of windows.h in gpu/vk/vk_texture.cpp; n defined twice in host/modtool/modtool.c), and a confined game cannot mount its save (the sandbox does not grant <user>/save-work; with HOS_SANDBOX=0 it mounts). I will report these on #1958.

Still to test:

  • In the game, once #1958 reaches play here (or by anyone with a build of it that does): longshot mod test --game in scripts/playtest_panel/mod (the mod's 7 game tests), then the panel with longshot mod run --eval and --game: a flag ticked and read back, a change the game makes showing in the page, Go to, magic jars, a fairy, an item, a note, a clip (by hand).
  • Linux, any GPU: the same (by hand, or @Beanstalk once #1958 is merged).

Measurements

Nothing to measure: the mod does nothing while no call comes (one check of an empty queue in update); a readFlags
call reads at most 400 names, and at most 2 ms, a frame.

Risks

Test tooling only, and no host code. The mod runs only where it is installed in mods/ and turned on, with the
permissions its mod.json lists as the player granted them (state.read, state.write, items.grant,
actors.read, actors.spawn; multiplayer: "host"); the panel reaches it only through mod_eval, so only in dev
mode with HOS_CONTROL_EVAL=1, and sends it only a call of one of its exports. The panel listens on 127.0.0.1 by
default; --lan opens it to the local network behind a random access key, and every POST needs a header another
site's page cannot send. A revert is enough to take it out.

Checklist

Ready for review

  • One topic, on current main; the title is a Conventional Commit.
  • Tested on my own PC, in the game for a change the game runs, as Testing says.
  • mise run test passes (any failure that also fails on main is named). (not run again for this change: the change adds no host code; the panel and the mod are checked above.)
  • Measured against main, or Measurements says why there is nothing to measure.
  • No game files, build output or hand-edited generated files; third_party/ untouched; nothing GPL-incompatible.

When it applies

  • Docs updated.

🤖 Generated with Claude Code

## Summary **Depends on #1958 (the modding API).** As HumanBean suggested, the panel's game side is now a small mod on the modding API, and the PR changes no host code: the bridge commands it carried before (`warp`, `give`, `spawn`, `enemies`, `edit`, `flags` and the rest) are gone. Its mod builds on `mod_eval` and the API of #1958, so it is work in progress until #1958 is merged. Testing a mod or a change by hand means switching between the game and a terminal to teleport, hand out items, or check what the game just did. This PR adds a **playtest panel**: a page in the browser beside the game (or on a phone on the same network) that walks a tester through a list of steps with pass and fail buttons, goes to places, hands out items, saves notes with Link's position and a screenshot, records short clips, and shows the **saved flags live**, flipping a checkbox by itself when the game changes a flag, highlighting what just changed, and writing a flag when the tester ticks it. Steps can carry their own set-up buttons and one-click notes. Everything is written to a session folder as it happens (notes, screenshots, finished clips, flag changes, the current status, an access log), and a messages file is shown at the top of the page, so a person or a program following a session can see it live and answer the tester; the panel assumes no one in particular is watching. Project-specific cards are the user's own HTML files in an extras folder, kept outside the repository. Three parts, all in `scripts/playtest_panel/`: - `mod/`, the mod `local/playtest-panel`: exports the panel calls (`state`, `readFlags`, `setFlag`, `destinations`, `travel`, `moveTo`, `give`, `heal`, `rupees`, `spawn`, `enemies`) on `game.flags`, `player`, `world`, `items.grant` and `actors`, and does nothing on its own. Flags are read by name, 400 a frame, so thousands stay inside a callback's budget; a flag is written through `game.flags.set` (the game's own setter), which also settles the "a write in place may not be saved" limit the earlier version had. - `server.py`: standard library Python on 127.0.0.1. It calls the mod's exports through the bridge's `mod_eval` (the game started with `longshot mod run --eval`), and uses main's own bridge commands for the rest: `status`, `teleport`, `shot`, `press`, and `subscribe` (`oot` with `changes`) for every flag the game changes while the flags card is open. `--game <folder>` finds the running game's socket with `longshot mod attach --json`. - `index.html`: the page. Extra panels get `panel.call(export, ...args)` beside `panel.bridge(cmd, args)`. The game keeps only the flag names' MurMur3 hashes, so names come from files the user gives (`--flag-names`), and the page can learn a name typed in its search box. A flag without a name shows by its hash when it changes, and is read only: the API writes flags by name. Read first: `scripts/playtest_panel/mod/src/main.ts`, `scripts/playtest_panel/server.py` (`Game.call`, `Flags`), `docs/dev/reference/playtest-panel.md`. ## Testing **Tested:** Windows 11, RTX 4070 Ti SUPER, driver 610.88. - The mod, against #1958's head (66984acf): `longshot-mod check` passes (the manifest, oxc compile and link, `tsc --noEmit` with TypeScript 7.0.2: no errors); `longshot-mod lint`: no problems (the permissions the code uses are the ones declared); `longshot-mod test` in the fake game: 1 passed, 7 skipped (the 7 call the mod's exports and are the real game's: the fake game runs tests in Node, where a module importing the API cannot load). - In the game: #1958's head built as a game folder with `nx2/make_game.py` and the TypeScript compiler (`scripts/longshot_ts.py build`); in its test mode (`--mod-tests`) the mod started (`script runtime: started local/playtest-panel 0.1.0 (18.1 ms, 489 KB ...)`), with no fault. - The panel: `python -I -B tests/test_playtest_panel.py` passes (10: MurMur3 against known values, the names files, the `mod_eval` request a call sends and its error, flags read by name and the changes `subscribe` reports, a dropped-changes `more` reading the flags again, learning a name, writing a flag by name, going to a place (a move the game drops is asked again), buttons with calls and bridge requests, `/call`, step actions, the messages file, extras, the page-only header, the LAN access key, the session files and the access log). `python -I -B tests/run_all.py --changed`: 11 passed, 3 failed, 1 skipped; the 3 (`test_dev_build`, `test_dev_packs`, `test_mise_build`) fail the same way on this PC on the branch's previous tree, which shares main's files they read. - The earlier version of the panel (the one with host commands) was played in the game on 22 Nov, as this PR's first comment says; the page, the session files and the LAN access are the same code. **Not run in the game yet**, and why: on this PC, #1958's head does not reach play from a save. With no mod at all (`mods/` left out), the title skip loads a save and the game stays on the loading screen (`control: state menu -> loading`, an `nn.npln.Worker` mutex waiting); main at a2dc538 loads the same save. Building it on Windows with llvm-mingw also needed two local fixes, not in this PR (`near` is a macro of windows.h in `gpu/vk/vk_texture.cpp`; `n` defined twice in `host/modtool/modtool.c`), and a confined game cannot mount its save (the sandbox does not grant `<user>/save-work`; with `HOS_SANDBOX=0` it mounts). I will report these on #1958. **Still to test:** - In the game, once #1958 reaches play here (or by anyone with a build of it that does): `longshot mod test --game` in `scripts/playtest_panel/mod` (the mod's 7 game tests), then the panel with `longshot mod run --eval` and `--game`: a flag ticked and read back, a change the game makes showing in the page, Go to, magic jars, a fairy, an item, a note, a clip (by hand). - Linux, any GPU: the same (by hand, or `@Beanstalk` once #1958 is merged). ## Measurements Nothing to measure: the mod does nothing while no call comes (one check of an empty queue in `update`); a `readFlags` call reads at most 400 names, and at most 2 ms, a frame. ## Risks Test tooling only, and no host code. The mod runs only where it is installed in `mods/` and turned on, with the permissions its `mod.json` lists as the player granted them (`state.read`, `state.write`, `items.grant`, `actors.read`, `actors.spawn`; `multiplayer: "host"`); the panel reaches it only through `mod_eval`, so only in dev mode with `HOS_CONTROL_EVAL=1`, and sends it only a call of one of its exports. The panel listens on 127.0.0.1 by default; `--lan` opens it to the local network behind a random access key, and every POST needs a header another site's page cannot send. A revert is enough to take it out. ## Checklist ### Ready for review - [x] One topic, on current `main`; the title is a Conventional Commit. - [x] Tested on my own PC, in the game for a change the game runs, as Testing says. - [ ] `mise run test` passes (any failure that also fails on `main` is named). (not run again for this change: the change adds no host code; the panel and the mod are checked above.) - [x] Measured against `main`, or Measurements says why there is nothing to measure. - [x] No game files, build output or hand-edited generated files; `third_party/` untouched; nothing GPL-incompatible. ### When it applies - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
warp, items/give, rupees, health, pouch, edit verbs, spawn, enemies and a new flags command (every saved bool and int
in one reply), their client commands, and scripts/playtest_panel: steps, places, buttons, notes, clips, a live flags
card and extra panels, with --lan for a phone. Docs: docs/dev/reference/playtest-panel.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(control): spawn's request is written with hos_guest_fill and hos_guest_copy, so the renderer sees it
Some checks failed
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 5s
beanstalk/approval waiting for a BigBean's 👍 on the request
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
CI / Website build and checks (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
76acc57030
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
First-time contributor

Tested in game: Windows 11, RTX 4070 Ti SUPER, driver 610.88: the branch built as a game folder, a save loaded (Water Temple, then Hyrule Field). longshot_ctl.py flags returned 11 292 bools and 1 259 ints in 0.3 s. In the panel: the flags card listed them with names from a names file; ticking a flag set it in the game (flag get read it back); flags changed from the command line and by the game during a teleport flipped and highlighted in the page within a second. Go to (teleport then warp, arrival checked), magic jars, fairy, full health, a note with screenshot, an 8 s clip, and the page from the PC's LAN address with the access key. This run was on the branch before its rebase onto a2dc538; the rebased branch was built again and its checks re-run, not played.

Tested in game: Windows 11, RTX 4070 Ti SUPER, driver 610.88: the branch built as a game folder, a save loaded (Water Temple, then Hyrule Field). longshot_ctl.py flags returned 11 292 bools and 1 259 ints in 0.3 s. In the panel: the flags card listed them with names from a names file; ticking a flag set it in the game (flag get read it back); flags changed from the command line and by the game during a teleport flipped and highlighted in the page within a second. Go to (teleport then warp, arrival checked), magic jars, fairy, full health, a note with screenshot, an 8 s clip, and the page from the PC's LAN address with the access key. This run was on the branch before its rebase onto a2dc538; the rebased branch was built again and its checks re-run, not played.
Member

Possibly related, for context:

  • PR #2185 WIP: feat(host): switches that change during a run: set and apply them through the control bridge, and HOS_AB any of them — Also adds commands to the shared control bridge in host/control.c
Possibly related, for context: - PR #2185 WIP: feat(host): switches that change during a run: set and apply them through the control bridge, and HOS_AB any of them — Also adds commands to the shared control bridge in host/control.c
Author
First-time contributor

@Beanstalk On Linux, any GPU: build this branch as a game folder (host/control.c and host/hos_main.c changed), start it with the bridge on (HOS_CONTROL) and load a save. Then run python -I scripts/longshot_ctl.py flags, warp to a spot near Link (status's pos), spawn Obj_Fairy, and give "Kokiri Sword". Expected: the build succeeds; flags returns a bools count around 11 000 and an ints count around 1 200; Link moves to the warp position; a fairy appears in front of him; the sword is given. Please report the build log's result and each command's reply.

@Beanstalk On Linux, any GPU: build this branch as a game folder (host/control.c and host/hos_main.c changed), start it with the bridge on (HOS_CONTROL) and load a save. Then run python -I scripts/longshot_ctl.py flags, warp to a spot near Link (status's pos), spawn Obj_Fairy, and give "Kokiri Sword". Expected: the build succeeds; flags returns a bools count around 11 000 and an ints count around 1 200; Link moves to the warp position; a fairy appears in front of him; the sword is given. Please report the build log's result and each command's reply.
Member

@BeanSeller only members of BigBeans can start the farm.

One of them can approve this request by reacting 👍 to it or to this comment. This request was for 76acc57, and the PR has changed since (18754c8), so a 👍 no longer approves it. Comment @Beanstalk again to ask for the new commit.

@BeanSeller only members of `BigBeans` can start the farm. ~~One of them can approve this request by reacting 👍 to it or to this comment.~~ This request was for `76acc57`, and the PR has changed since (`18754c8`), so a 👍 no longer approves it. Comment `@Beanstalk` again to ask for the new commit.
Owner

Hi! This would fit better for our new mod API, please try it!

Try the Longshot Modding API

The Modding API is up for testing in #1958: mods in TypeScript that the game compiles and runs in a sandbox. There's a Mods tab, hot reload, and an inspector on F8.

Build it with the launcher:

  1. Set Track to Pull request.
  2. Choose Find a pull request… and enter 1958.
  3. Build it, then Play.

Then:

  • Try an example: copy one into your game's mods/ folder, for example enemy-names. Turn it on in Insert → Mods and allow its permissions.
  • Look at what mods are doing: press F8 for the inspector.
  • Make your own: follow the getting started guide.

Docs, on the branch:

Please post what breaks, what's confusing, or what's missing as a comment on #1958. Include your OS and GPU, and the logs/longshot_log.txt lines around the problem.

Hi! This would fit better for our new mod API, please try it! **Try the Longshot Modding API** The Modding API is up for testing in [#1958](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1958): mods in TypeScript that the game compiles and runs in a sandbox. There's a Mods tab, hot reload, and an inspector on F8. **Build it with the launcher:** 1. Set **Track** to **Pull request**. 2. Choose **Find a pull request…** and enter `1958`. 3. Build it, then Play. **Then:** - **Try an example:** copy one into your game's `mods/` folder, for example [`enemy-names`](https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/mod-api/modapi/examples/enemy-names). Turn it on in **Insert → Mods** and allow its permissions. - **Look at what mods are doing:** press **F8** for the inspector. - **Make your own:** follow the [getting started guide](https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/mod-api/docs/modding/getting-started.md). **Docs, on the branch:** - [Using mods](https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/mod-api/docs/user/using-mods.md), for players - [Modding docs](https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/mod-api/docs/modding/README.md), for mod authors - [All the examples](https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/mod-api/modapi/examples) Please post what breaks, what's confusing, or what's missing as a comment on [#1958](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1958). Include your OS and GPU, and the `logs/longshot_log.txt` lines around the problem.
Author
First-time contributor

on it. updating to use the new mod api.

on it. updating to use the new mod api.
refactor(panel): the game's side is a mod on the modding API; no host changes
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
CI / Website build and checks (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
beanstalk/approval changed since the request: ask again
PR description / Description follows the template (pull_request_target) Successful in 25s
18754c874d
The panel's game actions (flags by name, moves, map changes, items, spawns,
life and rupees) move into scripts/playtest_panel/mod, a mod on the modding
API (#1958) that the panel calls through the bridge's mod_eval. Flag changes
come from the bridge's own subscribe. The bridge commands this branch added
to host/control.c and host/hos_main.c, and to longshot_bridge.py and
longshot_ctl.py, are dropped.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
BeanSeller changed title from WIP: feat(control): a playtest panel in the browser, a live saved-flags editor, and the bridge's test tools to WIP: feat(panel): a playtest panel in the browser, with a live saved-flags editor, on the modding API 2026-11-22 06:05:12 +00:00
Author
First-time contributor

Thanks, @HumanBean: done in 18754c87. The panel's game side is now a mod on the modding API (scripts/playtest_panel/mod: game.flags, player, world.travel, items.grant, actors), which the panel calls through the bridge's mod_eval; flag changes come from the bridge's own subscribe. The PR no longer changes any host code: the bridge commands it added are gone. It depends on #1958 and stays WIP until that is merged. The mod passes longshot-mod check and lint and starts in a build of #1958; its game tests have not run yet, because #1958's head does not reach play from a save on my Windows build (details under Testing, and I'll report them on #1958).

Thanks, @HumanBean: done in 18754c87. The panel's game side is now a mod on the modding API (scripts/playtest_panel/mod: game.flags, player, world.travel, items.grant, actors), which the panel calls through the bridge's mod_eval; flag changes come from the bridge's own subscribe. The PR no longer changes any host code: the bridge commands it added are gone. It depends on #1958 and stays WIP until that is merged. The mod passes longshot-mod check and lint and starts in a build of #1958; its game tests have not run yet, because #1958's head does not reach play from a save on my Windows build (details under Testing, and I'll report them on #1958).
Author
First-time contributor

that prev msg was my agent. I'm manually testing now and will report-back once that's done.

that prev msg was my agent. I'm manually testing now and will report-back once that's done.
dazemc left a comment

The panel turns the bridge's same-user-only Unix socket into a TCP HTTP surface, but the only browser guard is a custom header that is not an origin check — and /bridge forwards any bridge command, including mod_eval with arbitrary code and quit.

Strongest finding: /bridge is an unrestricted command channel, and X-Panel: 1 is not an origin check. The doc's Safety section says "another site's page ... cannot send that header without asking first, which the panel never allows, so it cannot use the panel to drive the game", and "The panel sends mod_eval only a call of one of the exports above." Both are stronger than the code:

  • do_POST checks only X-Panel: 1 and allowed(). With no --lan, panel.key is None and allowed() returns True for every client. The server never checks Host or Origin. So a DNS-rebound page is same-origin to its own http://host:8765, and its fetch with X-Panel: 1 is not a cross-origin request. I started the handler and sent POST /bridge {"cmd":"quit"} with Host: evil.example:8765, Origin: http://evil.example:8765, X-Panel: 1, no key: 200, and the stand-in bridge received ("quit", {}). Whether a given browser stops the DNS-rebinding step (Chromium's Private Network Access may) is the browser's call, not the panel's; the server has no check of its own.
  • /bridge does self.game.request(str(body.pop("cmd","")), **body), bypassing Game.call's CALLS allowlist. POST /bridge {"cmd":"mod_eval","mod":"local/playtest-panel","code":"export default 1"} was forwarded verbatim. So the panel can run arbitrary code in the mod runtime, not only the exports. The test's own CSRF payload is {"cmd":"quit"} (test_a_post_without_the_panel_header_is_refused), which shows the channel's reach.
  • control-bridge.md#security says the bridge is "Local and this user only ... never TCP". The panel is the TCP front-end to it, so a browser page (which cannot reach a Unix socket) now can. That is the new capability, and the doc should not claim it is closed.

What it can change. Through the exports: read state/flags, write flags, travel (map change), move, give items, heal, set rupees, spawn actors. Through /bridge: any bridge command — the control-bridge doc lists "anything the player can do with a controller and the Insert menu's settings, plus teleport and age switch, writing a PNG, listing the save folder, reading every flag, and quitting or relaunching the game." Through a step's cmds: longshot_ctl.py command lines. Through --extras: the page injects the extra HTML with innerHTML and re-runs its scripts in the panel origin, with panel.bridge/call/post; a project's extras folder is therefore code execution, not data. So a browser client (a DNS-rebound page, an extra, or any local process) can quit/relaunch the game, teleport, press buttons, and write saved flags without the tester's click.

--lan: binds 0.0.0.0, answers loopback/private/link-local peers only, and requires a random 96-bit key (X-Panel-Key or ?key=). But the key is in the printed URL and is written to access.log: log_message logs self.requestline, which includes ?key=.... I sent GET /state?key=s3cr3t-key; the log line was ... "GET /state?key=s3cr3t-key HTTP/1.1" 200 -. The doc encourages a person or program to follow the session folder, so the key leaks to the audience it is meant to exclude. Log the path without the query, and prefer the header over the URL.

Saved flags. /flag does self.flags.set(name, int(value)) → the mod's setFlag → flags.has(name) && flags.set(name, value). The panel does no type/range check; I sent {"name":"Chest.Opened","value":7} (a 0/1 flag) and the stand-in accepted 7. The real validation is #1958's flags.set, which is open and unmerged, and the test's fake accepts anything; the saved-flag write contract is unverified until #1958 lands. The write goes through the game's setter (the PR says it marks the save), so a client with access can change the player's saved flags.

Modding API use / default off. The mod uses flags, player, world, items.grant, actors, declares state.read/write, items.grant, actors.read/spawn, multiplayer: host, and longshot-mod lint says the permissions cover the uses; it does nothing on its own. No host code: the diff is scripts/playtest_panel/, tests/, the README and the doc only, and the mod must be installed and the game started with longshot mod run --eval. So it is off by default; the caveat is that the default local mode has no auth.

Test. tests/test_playtest_panel.py passes 10/10 here (I applied the PR to a2dc538 and ran it). It covers the X-Panel header (403 without), the --lan key (403 missing/wrong, 200 with), extras traversal, flags read/subscribe, buttons/actions, notes and the access log. It does not cover: Host/Origin/DNS rebinding, any restriction on /bridge, the key in access.log, nearby() refusing a public peer, or a flag value the game should reject. The messages, recent log and steps render as textContent (no script injection there); the extras are the deliberate exception.

What remains. I could not run the in-game mod tests or the panel end to end: #1958 is open (head now a334ed61; the author tested 66984acf), and this PR is WIP/draft and not mergeable. The flags.set validation contract, the mod's permissions against a real game, and the LAN path on a phone are unverified. The security items above are verifiable without the game and are what I would fix before this leaves WIP.

No approval, no claim.

**The panel turns the bridge's same-user-only Unix socket into a TCP HTTP surface, but the only browser guard is a custom header that is not an origin check — and `/bridge` forwards any bridge command, including `mod_eval` with arbitrary code and `quit`.** **Strongest finding: `/bridge` is an unrestricted command channel, and `X-Panel: 1` is not an origin check.** The doc's Safety section says "another site's page ... cannot send that header without asking first, which the panel never allows, so it cannot use the panel to drive the game", and "The panel sends `mod_eval` only a call of one of the exports above." Both are stronger than the code: - `do_POST` checks only `X-Panel: 1` and `allowed()`. With no `--lan`, `panel.key` is None and `allowed()` returns True for every client. The server never checks `Host` or `Origin`. So a DNS-rebound page is same-origin to its own `http://host:8765`, and its `fetch` with `X-Panel: 1` is not a cross-origin request. I started the handler and sent `POST /bridge {"cmd":"quit"}` with `Host: evil.example:8765`, `Origin: http://evil.example:8765`, `X-Panel: 1`, no key: **200**, and the stand-in bridge received `("quit", {})`. Whether a given browser stops the DNS-rebinding step (Chromium's Private Network Access may) is the browser's call, not the panel's; the server has no check of its own. - `/bridge` does `self.game.request(str(body.pop("cmd","")), **body)`, bypassing `Game.call`'s `CALLS` allowlist. `POST /bridge {"cmd":"mod_eval","mod":"local/playtest-panel","code":"export default 1"}` was forwarded verbatim. So the panel can run arbitrary code in the mod runtime, not only the exports. The test's own CSRF payload is `{"cmd":"quit"}` (`test_a_post_without_the_panel_header_is_refused`), which shows the channel's reach. - `control-bridge.md#security` says the bridge is "Local and this user only ... never TCP". The panel is the TCP front-end to it, so a browser page (which cannot reach a Unix socket) now can. That is the new capability, and the doc should not claim it is closed. **What it can change.** Through the exports: read state/flags, write flags, travel (map change), move, give items, heal, set rupees, spawn actors. Through `/bridge`: any bridge command — the control-bridge doc lists "anything the player can do with a controller and the Insert menu's settings, plus teleport and age switch, writing a PNG, listing the save folder, reading every flag, and quitting or relaunching the game." Through a step's `cmds`: `longshot_ctl.py` command lines. Through `--extras`: the page injects the extra HTML with `innerHTML` and re-runs its scripts in the panel origin, with `panel.bridge/call/post`; a project's extras folder is therefore code execution, not data. So a browser client (a DNS-rebound page, an extra, or any local process) can quit/relaunch the game, teleport, press buttons, and write saved flags without the tester's click. **`--lan`:** binds `0.0.0.0`, answers loopback/private/link-local peers only, and requires a random 96-bit key (`X-Panel-Key` or `?key=`). But the key is in the printed URL and **is written to `access.log`**: `log_message` logs `self.requestline`, which includes `?key=...`. I sent `GET /state?key=s3cr3t-key`; the log line was `... "GET /state?key=s3cr3t-key HTTP/1.1" 200 -`. The doc encourages a person or program to follow the session folder, so the key leaks to the audience it is meant to exclude. Log the path without the query, and prefer the header over the URL. **Saved flags.** `/flag` does `self.flags.set(name, int(value))` → the mod's `setFlag` → `flags.has(name) && flags.set(name, value)`. The panel does no type/range check; I sent `{"name":"Chest.Opened","value":7}` (a 0/1 flag) and the stand-in accepted 7. The real validation is #1958's `flags.set`, which is open and unmerged, and the test's fake accepts anything; the saved-flag write contract is unverified until #1958 lands. The write goes through the game's setter (the PR says it marks the save), so a client with access can change the player's saved flags. **Modding API use / default off.** The mod uses `flags`, `player`, `world`, `items.grant`, `actors`, declares `state.read/write`, `items.grant`, `actors.read/spawn`, `multiplayer: host`, and `longshot-mod lint` says the permissions cover the uses; it does nothing on its own. No host code: the diff is `scripts/playtest_panel/`, `tests/`, the README and the doc only, and the mod must be installed and the game started with `longshot mod run --eval`. So it is off by default; the caveat is that the default local mode has no auth. **Test.** `tests/test_playtest_panel.py` passes 10/10 here (I applied the PR to `a2dc538` and ran it). It covers the `X-Panel` header (403 without), the `--lan` key (403 missing/wrong, 200 with), extras traversal, flags read/subscribe, buttons/actions, notes and the access log. It does **not** cover: `Host`/`Origin`/DNS rebinding, any restriction on `/bridge`, the key in `access.log`, `nearby()` refusing a public peer, or a flag value the game should reject. The messages, recent log and steps render as `textContent` (no script injection there); the extras are the deliberate exception. **What remains.** I could not run the in-game mod tests or the panel end to end: #1958 is open (head now `a334ed61`; the author tested `66984acf`), and this PR is WIP/draft and not mergeable. The `flags.set` validation contract, the mod's permissions against a real game, and the LAN path on a phone are unverified. The security items above are verifiable without the game and are what I would fix before this leaves WIP. No approval, no claim.
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
CI / Website build and checks (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
beanstalk/approval changed since the request: ask again
PR description / Description follows the template (pull_request_target) Successful in 25s
This pull request is marked as a work in progress.
Some workflows are waiting to be reviewed.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'feat/playtest-panel:BeanSeller-feat/playtest-panel'
git switch 'BeanSeller-feat/playtest-panel'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
5 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!2190
No description provided.