[shinkuan]

Closes #288.

What

A third capture mode, ingest, for playing the web clients (Mahjong Soul, Tenhou) in the user's own browser, with their real profile and login, Firefox included. No system proxy, no CA, and no browser launched by Akagi.

game page ── userscript (wraps window.WebSocket, read-only)
                 │  JSON envelopes over ws://127.0.0.1:23411/ingest
                 ▼
          IngestBackend ──→ FlowBridges ──→ Bridge::parse ──→ MjaiBus

Backend: src/capture/ingest/

• An axum loopback server with three routes:
  • GET /ingest: the WebSocket a source pushes frames into.
  • GET /akagi.user.js: the userscript, rendered with this address. Userscript managers offer to install from it.
  • GET /ping: answers pong.
• Frames go through FlowBridges into the platform bridge, exactly like the Chromium backend. The Inspector ws_frame recording is now shared between the two backends (capture/frame.rs).
• Wire protocol, v1: hello / open / frame / close. Text frames are sent verbatim and binary frames as base64. Both directions are sent, because Mahjong Soul pairs responses with requests.
• New config section [capture.ingest] addr, default 127.0.0.1:23411, plus a supervisor arm and an ingest_userscript IPC command for the "copy script" button.

Safety

• Loopback only. The backend refuses to start on any other address.
• Origin check at the handshake. A game site from GAME_SITES is accepted. Any other page gets 403, so an arbitrary website cannot feed Akagi fake frames. A connection with no Origin (a local program) is accepted. The same list renders the userscript's @match lines, so the two cannot drift apart.
• Wrong platform or protocol version. The page is closed with 1008 and a toast. The script then stays quiet until the page reloads.

Userscript (akagi.user.js)

• Strictly read-only. Every frame reaches the game unchanged. Forwarding is fire-and-forget, and nothing it does can throw into the page.
• Hooking. It uses a Proxy over the native constructor and keeps instanceof, subclassing and ws.constructor intact. It uses the native addEventListener and url getter, so a page subclass that overrides them is still captured.
• Ordering. Messages from one socket keep their order, Blob reads included. An up frame is forwarded only after the native send succeeded, from a copy of the buffer.
• While Akagi is unreachable:
  • It holds only the last minute of frames, capped by count and by size.
  • It drops held frames from sockets that have since closed, so a finished game is never replayed as live.
  • It goes dormant once the reconnect backoff reaches its ceiling, and resumes when a connection succeeds.

Frontend

• A third mode card in Setup and a Settings option, with an install / copy panel. The mode label is now three-way in Setup, Overview and the capture tile.
• Bug fix: Settings rebuilt capture as {mode, chromium}, which dropped capture.http; the backend then reset it to its defaults on the next save. Capture edits now go through lib/captureConfig.ts, which spreads the existing section. Regression test: captureConfig.test.ts.

Out of scope

Autoplay in this mode (there is no page handle to drive), a packaged browser extension, and changes to the Chromium backend.

Tests

• tests/capture_ingest.rs. It starts the real server and checks, over real sockets:
  • /ping and the rendered userscript are served;
  • a foreign origin gets 403;
  • a wrong-platform page is closed with 1008;
  • Tenhou frames pushed by a game page produce start_game / start_kyoku on the bus and ws_frame rows on the Inspector timeline;
  • shutdown closes the source and ends the backend cleanly.
• Unit tests for origin matching (lookalike hosts, http, null), envelope parsing, payload decoding, loopback validation, userscript rendering, and config serde and back-compat.
• frontend/src/lib/userscript.test.ts runs the committed script against a fake page (15 cases). It covers forwarding and ordering, page shape, the subclass override, failure isolation, buffer snapshots, a refused send, the hold caps and window, forgetting closed sockets, policy refusal, dormancy, reconnect, and single install.
• cargo fmt --check, cargo clippy --all-targets -D warnings, cargo test, tsc -b and eslint all pass.

Manual check still needed

Install the userscript in Chrome and Firefox and play a Tenhou game and a Mahjong Soul game. Two things to watch for:

• whether Chrome shows a local-network-access prompt for the page's connection to 127.0.0.1;
• whether either site's CSP blocks that connection.