runitx commited on
Commit
3e3dca4
·
unverified ·
1 Parent(s): 1426b5e

docs: expand nekohash specification with binary framing, arcade rpc, and opcodes

Browse files
Files changed (3) hide show
  1. README.md +7 -6
  2. docs/NEKOHASH.md +219 -113
  3. protocol.py +203 -62
README.md CHANGED
@@ -9,7 +9,7 @@ tags:
9
 
10
  # awoo.cf WebSocket Client
11
 
12
- Python client implementing the full awoo.cf WebSocket handshake, authentication, and live streaming connection flow.
13
 
14
  ## Architecture & Handshake Details
15
 
@@ -23,10 +23,9 @@ Python client implementing the full awoo.cf WebSocket handshake, authentication,
23
  - Upon connection, the server sends an integer challenge `t` (`100000 <= t <= 1999999`).
24
  - The client replies with `t + 1`.
25
  - After 6 rounds of ping-pong challenges, the server sends the confirmed token string (`v2.<base64>`).
26
- 5. **Synchronization (`44`):**
27
- - Client sends message type `44` with JSON payload `{"board": "all", "thread": null, "protocolVersion": 1, ...}`.
28
- - Valid boards include: `all`, `g`, `complaints`, `crime`, `d`, etc.
29
- - Server streams full board state (`50`, `56`, `55`, `44`).
30
  6. **Keepalive:**
31
  - Message type `48` serves as periodic NOOP ping.
32
 
@@ -34,8 +33,10 @@ Python client implementing the full awoo.cf WebSocket handshake, authentication,
34
 
35
  - ✅ Full end-to-end handshake and authentication
36
  - ✅ Multi-instance connection support: **30 simultaneous WebSocket instances** held open and synchronized
37
- - ✅ Live thread and post streaming
38
  - ✅ Complete reverse-engineered protocol documentation: see [docs/NEKOHASH.md](docs/NEKOHASH.md) and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
 
 
39
 
40
  ## Usage
41
 
 
9
 
10
  # awoo.cf WebSocket Client
11
 
12
+ Python client and reverse-engineered protocol toolkit for the `awoo.cf` / `nekohash` real-time imageboard engine.
13
 
14
  ## Architecture & Handshake Details
15
 
 
23
  - Upon connection, the server sends an integer challenge `t` (`100000 <= t <= 1999999`).
24
  - The client replies with `t + 1`.
25
  - After 6 rounds of ping-pong challenges, the server sends the confirmed token string (`v2.<base64>`).
26
+ 5. **Dual-Mode Protocol Framing:**
27
+ - **ASCII/JSON Control Framing:** `<2-digit-opcode><JSON payload>` for synchronization (`44`), presence (`49`), NekoTV (`54`), and Arcade (`80`).
28
+ - **Little-Endian Binary Framing:** `<8-byte float64 post_id><payload><1-byte opcode>` for real-time keystroke streaming (`02`, `03`, `04`) and live AI token generation (Claude Thinking `81`, Claude `11-13`, Imagen `14-16`, Video `17-34`, Venice `64-66`, Atlas `67-69`, BytePlus `82-84`).
 
29
  6. **Keepalive:**
30
  - Message type `48` serves as periodic NOOP ping.
31
 
 
33
 
34
  - ✅ Full end-to-end handshake and authentication
35
  - ✅ Multi-instance connection support: **30 simultaneous WebSocket instances** held open and synchronized
36
+ - ✅ Live thread and post streaming with binary frame decoding
37
  - ✅ Complete reverse-engineered protocol documentation: see [docs/NEKOHASH.md](docs/NEKOHASH.md) and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
38
+ - ✅ Arcade multiplayer protocol (19+ in-thread games) and NekoTV watch-party specification
39
+ - ✅ Instant client-side SHA-1 media deduplication pipeline (`/api/upload-hash`)
40
 
41
  ## Usage
42
 
docs/NEKOHASH.md CHANGED
@@ -13,7 +13,9 @@
13
  - An in-thread multiplayer board-and-puzzle game arcade.
14
  - Synchronized video watch parties (NekoTV).
15
  - In-thread WebRTC mesh voice channels and screen audio sharing.
16
- - Multi-layer anti-bot defenses including WebAssembly hardware fingerprint sealing and multi-round challenge-response WebSocket authentication.
 
 
17
 
18
  ---
19
 
@@ -29,130 +31,234 @@ The client is bundled with **esbuild**, featuring dynamic chunk splitting loaded
29
  | `chunk-XMMHRB6S.js` | 83 KB | NekoTV | Synchronized video player, shared playlist manager, and voting queue |
30
  | `chunk-JTTGKNWN.js` | 80 KB | WebRTC | In-thread voice channels, peer mesh signaling, and microphone audio |
31
  | `chunk-HPSHJMW7.js` | 114 KB | Anti-Bot | Bundled ALTCHA PoW solver, hCaptcha, and Cloudflare Turnstile widgets |
 
32
  | `chunk-LTTJLTTF.js` | ~150 KB | FLV Streamer | MSE live video streaming player (`flv.js`) |
33
- | `chunk-7WFO3EBS.js`+ | ~600 KB | 3D Engine | Three.js GLTF/GLB interactive 3D model viewer and room environment |
34
 
35
  ---
36
 
37
- ## 3. Real-Time Generative AI Integration
38
-
39
- `nekohash` integrates generative AI models into live imageboard drafts via special command prefixes parsed by `chunk-NRU3NIKF.js`:
40
-
41
- ### A. Live LLM Streaming (`@grok` / `claude_state`)
42
- - When a user includes `@grok [prompt]` in a post draft:
43
- - The backend streams the AI's response tokens in real-time over the WebSocket.
44
- - The frontend dynamically updates a dedicated blockquote container:
45
- ```html
46
- <div class="claude-container">
47
- <div class="blockquote-divider"></div>
48
- <blockquote class="claude-response">...streamed tokens...</blockquote>
49
- </div>
50
- ```
51
- - Managed by post states: `claude_state.status` (`"generating"`, `"waiting"`, `"error"`, `"done"`).
52
-
53
- ### B. Multi-Modal Generative Commands
54
- - **`.imagen [prompt]`**: Text-to-image generation and image editing (`imagen_state`).
55
- - **`.say [text]`**: Text-to-speech audio synthesis (`say_state`).
56
- - **`.music [prompt]`**: AI music generation (`music_state`).
57
- - **`.atlas`, `.venice`, `.byteplus [prompt]`**: Multi-pipeline text-to-video and image-to-video generation (supporting Atlas, Venice AI, and ByteDance BytePlus pipelines).
58
- - **`.3d [prompt]`**: Interactive 3D asset generation, rendered inline in posts using Three.js.
59
 
60
- ---
 
 
 
 
 
 
 
 
 
 
 
 
 
 
61
 
62
- ## 4. Subsystems
63
-
64
- ### A. The Arcade (Multiplayer In-Thread Games)
65
- Operates over WebSocket message type **`80`** (`ARCADE_EVENT`):
66
- - **Features:** Matchmaking, turn timers (`arcade-clock`), player ratings and leaderboards (`arcade-lb`), spectator monitoring (`arcade-watchers`), and floating in-game emotes (`arcade-emotes`).
67
- - **Implemented Games:**
68
- 1. Chess
69
- 2. Checkers
70
- 3. Go (with territory scoring)
71
- 4. Reversi / Othello
72
- 5. Battleship
73
- 6. Mancala
74
- 7. Wordle
75
- 8. Liar's Dice
76
- 9. Ultimate Tic-Tac-Toe & Notakto
77
- 10. Quoridor
78
- 11. Mastermind
79
- 12. Nim
80
- 13. Rock-Paper-Scissors
81
- 14. Nine Men's Morris
82
- 15. Game of the Amazons
83
- 16. Chomp
84
- 17. Memory Card Matching
85
- 18. Minesweeper
86
- 19. Dominoes
87
-
88
- ### B. NekoTV (Synchronized Watch Party)
89
- - **Features:** In-thread theater mode (`nekotv-theater`) with synced playback timestamps.
90
- - **Queue Control:** Collaborative playlist management with events (`AddVideoEvent`, `RemoveVideoEvent`, `SkipVideoEvent`, `ClearPlaylistEvent`).
91
- - **Democratic Controls:** Real-time skip and lock voting (`nekotv-vote`).
92
- - **Audience Counter:** Header stats tracked via message `49` (`{"active": N, "total": M, "nekotv": K}`).
93
-
94
- ### C. In-Thread WebRTC Voice Channels
95
- - Operates over message type **`63`** (`banner-voicechat`).
96
- - Full peer-to-peer signaling mesh: `peer-joined`, `peer-left`, `peer-ping`, `peer-updated`.
97
- - Displays animated voice activity rings around user avatars (`rtc-speak-av`).
98
- - Supports screen audio streaming and user-level volume controls.
99
 
100
  ---
101
 
102
- ## 5. WebSocket Protocol Specification
103
-
104
- All frames follow the `<2-digit type><payload>` structure:
105
-
106
- | Type | Name | Direction | Payload Structure & Purpose |
107
- | :---: | :--- | :---: | :--- |
108
- | `00` | `ERROR` | S $\to$ C | Numerical error code (e.g. `004` = invalid input, `001` = rate limit) |
109
- | `01` | `INSERT_POST` | S $\to$ C | Broadcasts a newly submitted post in the current thread |
110
- | `02` | `APPEND` | Both | Live keystroke streaming: sends single characters as typed |
111
- | `03` | `BACKSPACE` | Both | Removes the last character in the live draft |
112
- | `04` | `SPLICE` | Both | Substring replacement in draft post body: `[start, delete, text]` |
113
- | `05` | `CLOSE_POST` | Both | Finalizes and submits the draft post |
114
- | `06` | `INSERT_IMAGE` | Both | Attaches an uploaded media file to the active draft |
115
- | `44` | `SYNCHRONISE` | Both | **Board / Thread Sync:** Client sends `{"board": "...", "thread": N, "seal": "noWASM", "fp": "..."}`. Server responds with full state. |
116
- | `47` | `BATCH_EVENTS` | S $\to$ C | Encapsulated array of real-time post events |
117
- | `48` | `NOOP_PING` | C $\to$ S | Keepalive ping (must be sent every 15–20s to prevent idle disconnect) |
118
- | `49` | `PRESENCE` | S $\to$ C | Active viewer counts: `{"active": int, "total": int, "nekotv": int}` |
119
- | `50` | `SERVER_TIME` | S $\to$ C | Server synchronization epoch timestamp (milliseconds) |
120
- | `55` | `BOARD_CONFIG`| S $\to$ C | Dynamic board capabilities (`NSFW`, `games`, `webRTC`, `cortisolMeter`) |
121
- | `56` | `SESSION_CFG` | S $\to$ C | Dynamic session & captcha session keys |
122
- | `57` | `SESSION_KEY` | S $\to$ C | 16-byte session key rotation |
123
- | `59` | `POLL_UPDATE` | S $\to$ C | In-thread poll definition and options |
124
- | `60` | `POLL_VOTE` | Both | Cast or receive vote count updates on polls |
125
- | `63` | `WEBRTC_SIG` | Both | WebRTC peer discovery, SDP offers/answers, and ICE candidates |
126
- | `75` | `REACTIONS` | Both | Emoji reaction events: `{"t": "react", "p": postId, "e": emojiId}` |
127
- | `76` | `FP_TOKEN` | C $\to$ S | Post-handshake fingerprint token delivery |
128
- | `80` | `ARCADE_EVENT`| Both | Multiplayer board game actions, moves, and clock updates |
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
129
 
130
  ---
131
 
132
- ## 6. Authentication & Handshake Lifecycle
 
 
 
 
 
 
 
 
133
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
134
  ```
135
- Client Server (p.awoo.cf)
136
- | |
137
- |--- HTTP POST /v1/token {"binding": "<32-byte-id>"} -------->|
138
- |<-- {"token": "v2.<initial-binding>"} -----------------------|
139
- | |
140
- |--- WebSocket Upgrade GET /api/socket?binding=<id> ---------->|
141
- |<-- HTTP/1.1 101 Switching Protocols ------------------------|
142
- | |
143
- |<-- Challenge Round 1: "378178" -----------------------------|
144
- |--- Response: "378179" (t + 1) ----------------------------->|
145
- | ... |
146
- |<-- Challenge Round 6: "378183" -----------------------------|
147
- |--- Response: "378184" (t + 1) ----------------------------->|
148
- | |
149
- |<-- Confirmed Token: "v2.<confirmed-token>" -----------------|
150
- | |
151
- |=== CONNECTION AUTHENTICATED ================================|
152
- | |
153
- |--- Send Type 44: {"board": "all", "thread": null, ...} ---->|
154
- |<-- Type 50 (Server Time), 56 (Session), 55 (Config), 44 ----|
155
- | |
156
- |<-- Continuous Event Stream (01, 02, 47, 80...) -------------|
157
- |--- Periodic Type 48 (NOOP Ping every 20s) ----------------->|
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
158
  ```
 
 
13
  - An in-thread multiplayer board-and-puzzle game arcade.
14
  - Synchronized video watch parties (NekoTV).
15
  - In-thread WebRTC mesh voice channels and screen audio sharing.
16
+ - Dual-mode WebSocket framing: ASCII/JSON for control messages and high-efficiency Little-Endian Binary framing for high-throughput streaming events.
17
+ - Client-side SHA-1 media deduplication and 80 MB chunked upload engine.
18
+ - Bandwidth-optimized delta polling (`/json/thread-updates`) and RFC 9110 Shared Zstandard Dictionary compression.
19
 
20
  ---
21
 
 
31
  | `chunk-XMMHRB6S.js` | 83 KB | NekoTV | Synchronized video player, shared playlist manager, and voting queue |
32
  | `chunk-JTTGKNWN.js` | 80 KB | WebRTC | In-thread voice channels, peer mesh signaling, and microphone audio |
33
  | `chunk-HPSHJMW7.js` | 114 KB | Anti-Bot | Bundled ALTCHA PoW solver, hCaptcha, and Cloudflare Turnstile widgets |
34
+ | `chunk-PVG4O4YS.js` | 32 KB | Schema | Post validation schemas, country flags, and file extensions |
35
  | `chunk-LTTJLTTF.js` | ~150 KB | FLV Streamer | MSE live video streaming player (`flv.js`) |
36
+ | `chunk-7WFO3EBS.js` | ~600 KB | 3D Engine | Three.js GLTF/GLB interactive 3D model viewer and room environment |
37
 
38
  ---
39
 
40
+ ## 3. Dual-Mode WebSocket Framing Specification
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
41
 
42
+ Nekohash optimizes socket throughput by splitting traffic into two framing modes:
43
+
44
+ ### A. ASCII / JSON Control Framing
45
+ Used for connection negotiation, state synchronization, presence, and control commands:
46
+ $$\text{Frame} = \text{Opcode}_{2\text{ bytes (ASCII)}} + \text{Payload}_{\text{JSON or String}}$$
47
+
48
+ Example:
49
+ - `44{"board":"all","thread":null,...}`: Synchronization
50
+ - `48`: Keepalive NOOP ping
51
+ - `80{"t":"catalog"}`: Arcade catalog query
52
+
53
+ ### B. Little-Endian Binary Streaming Framing
54
+ Used for high-frequency operations: live keystrokes, character splices, and real-time generative AI token streaming. Handled by client functions `W(e)` and `G(e)`:
55
+
56
+ $$\text{Standard Binary Frame} = \text{PostID}_{8\text{ bytes (Float64 LE)}} + \text{Payload}_{\text{UTF-8 Text}} + \text{Opcode}_{1\text{ byte}}$$
57
 
58
+ $$\text{Splice Binary Frame (Opcode 0x04)} = \text{PostID}_{8\text{ bytes (Float64 LE)}} + \text{Start}_{2\text{ bytes (Uint16 LE)}} + \text{Len}_{2\text{ bytes (Uint16 LE)}} + \text{Text}_{\text{UTF-8}} + \text{0x04}$$
59
+
60
+ $$\text{Backspace Binary Frame (Opcode 0x03)} = \text{PostID}_{8\text{ bytes (Float64 LE)}} + \text{0x03}$$
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
61
 
62
  ---
63
 
64
+ ## 4. Complete WebSocket Opcode Map
65
+
66
+ | Opcode | Format | Name | Direction | Payload & Purpose |
67
+ | :---: | :---: | :--- | :---: | :--- |
68
+ | `00` | Text | `ERROR` | S $\to$ C | Numerical error code (`0` = unknown, `1` = rate limit, `2` = banned) |
69
+ | `01` | Text | `INSERT_POST` | S $\to$ C | Broadcasts a newly submitted post in the current thread |
70
+ | `02` | Binary | `APPEND` | Both | Live keystroke streaming: sends single characters as typed |
71
+ | `03` | Binary | `BACKSPACE` | Both | Removes the last character in the active draft |
72
+ | `04` | Binary | `SPLICE` | Both | Substring replacement: `[post_id, start, delete_len, text]` |
73
+ | `05` | Text | `CLOSE_POST` | Both | Finalizes and commits the draft post |
74
+ | `06` | Text | `INSERT_IMAGE` | Both | Attaches an uploaded media token to active post |
75
+ | `07` | Text | `SPOILER_IMAGE` | Both | Toggles spoiler flag on an image attachment |
76
+ | `08` | Text | `APPLY_MODERATION` | S $\to$ C | Moderation action update (post deletion, ban, capcode) |
77
+ | `09` | Text | `REMOVE_IMAGE` | Both | Removes an attached image |
78
+ | `10` | Text | `REPLACE_IMAGE` | Both | Replaces an attached image |
79
+ | `11` | Binary | `CLAUDE_APPEND` | S $\to$ C | Streamed Claude / LLM text token chunk |
80
+ | `12` | Binary | `CLAUDE_DONE` | S $\to$ C | Claude generation complete |
81
+ | `13` | Binary | `CLAUDE_ERROR` | S $\to$ C | Claude generation failed |
82
+ | `14` | Binary | `IMAGEN_APPEND` | S $\to$ C | Streamed Imagen image generation status |
83
+ | `15` | Binary | `IMAGEN_DONE` | S $\to$ C | Imagen image generation complete |
84
+ | `16` | Binary | `IMAGEN_ERROR` | S $\to$ C | Imagen image generation failed |
85
+ | `17` | Binary | `VIDEOGEN_APPEND` | S $\to$ C | Video generation progress |
86
+ | `18` | Binary | `VIDEOGEN_DONE` | S $\to$ C | Video generation complete |
87
+ | `19` | Binary | `VIDEOGEN_ERROR` | S $\to$ C | Video generation failed |
88
+ | `20` | Binary | `EDITGEN_APPEND` | S $\to$ C | AI image edit progress |
89
+ | `21` | Binary | `EDITGEN_DONE` | S $\to$ C | AI image edit complete |
90
+ | `22` | Binary | `EDITGEN_ERROR` | S $\to$ C | AI image edit failed |
91
+ | `23` | Binary | `IMGTOVID_APPEND` | S $\to$ C | Image-to-video pipeline progress |
92
+ | `24` | Binary | `IMGTOVID_DONE` | S $\to$ C | Image-to-video complete |
93
+ | `25` | Binary | `IMGTOVID_ERROR` | S $\to$ C | Image-to-video failed |
94
+ | `26` | Binary | `IMG2VEO_APPEND` | S $\to$ C | Google Veo video pipeline progress |
95
+ | `27` | Binary | `IMG2VEO_DONE` | S $\to$ C | Google Veo complete |
96
+ | `28` | Binary | `IMG2VEO_ERROR` | S $\to$ C | Google Veo failed |
97
+ | `29` | Binary | `GROKVID_APPEND` | S $\to$ C | xAI Grok video pipeline progress |
98
+ | `30` | Binary | `GROKVID_DONE` | S $\to$ C | xAI Grok video complete |
99
+ | `31` | Binary | `GROKVID_ERROR` | S $\to$ C | xAI Grok video failed |
100
+ | `36` | Text | `TIKTOK_PENDING` | S $\to$ C | Pending TikTok video embed state |
101
+ | `43` | Binary | `FP_TOKEN_RECEIVE` | S $\to$ C | Fingerprint challenge token payload |
102
+ | `44` | Text | `SYNCHRONISE` | Both | Board/Thread sync: `{"board":str,"thread":int,"seal":"noWASM",...}` |
103
+ | `45` | Text | `POST_PASSWORD` | Both | Draft reclamation via post password |
104
+ | `46` | Text | `RECEIVE_ID` | S $\to$ C | Assigned post ID for drafting |
105
+ | `47` | Text | `BATCH_EVENTS` | S $\to$ C | Batched array of real-time socket events |
106
+ | `48` | Text | `NOOP_PING` | C $\to$ S | Keepalive ping (sent every 15-20s) |
107
+ | `49` | Text | `PRESENCE` | S $\to$ C | Viewer metrics: `{"active": int, "total": int, "nekotv": int}` |
108
+ | `50` | Text | `SERVER_TIME` | S $\to$ C | Server timestamp in milliseconds |
109
+ | `51` | Text | `REDIRECT` | S $\to$ C | Browser redirection instruction |
110
+ | `52` | Text | `NOTIFICATION` | S $\to$ C | Browser desktop notification trigger |
111
+ | `53` | Text | `CAPTCHA_TRIGGER`| S $\to$ C | Requires captcha completion before posting |
112
+ | `54` | Text | `NEKO_TV_SYNC` | Both | NekoTV shared watch-party sync and playlist state |
113
+ | `55` | Text | `BOARD_CONFIG` | S $\to$ C | Board feature capabilities (`games`, `webRTC`, `NSFW`, etc.) |
114
+ | `56` | Text | `SESSION_CONFIG`| S $\to$ C | Session config key-value updates |
115
+ | `57` | Binary | `SESSION_KEY` | S $\to$ C | Dynamic 16-byte session key rotation |
116
+ | `58` | Text | `SYNC_COUNT` | S $\to$ C | Active synchronized client count |
117
+ | `59` | Text | `POLL_UPDATE` | S $\to$ C | In-thread poll creation / option list |
118
+ | `60` | Text | `POLL_VOTE` | Both | Cast poll vote or receive live vote tallies |
119
+ | `62` | Text | `THREAD_CREATED`| S $\to$ C | New thread broadcast notification |
120
+ | `63` | Text | `WEBRTC_SIGNAL` | Both | WebRTC peer discovery, SDP offers/answers, and ICE signaling |
121
+ | `64` | Binary | `VENICEVID_APPEND`| S $\to$ C | Venice AI video progress |
122
+ | `65` | Binary | `VENICEVID_DONE` | S $\to$ C | Venice AI video complete |
123
+ | `66` | Binary | `VENICEVID_ERROR`| S $\to$ C | Venice AI video failed |
124
+ | `67` | Binary | `ATLASVID_APPEND` | S $\to$ C | ByteDance Atlas video progress |
125
+ | `68` | Binary | `ATLASVID_DONE` | S $\to$ C | ByteDance Atlas video complete |
126
+ | `69` | Binary | `ATLASVID_ERROR` | S $\to$ C | ByteDance Atlas video failed |
127
+ | `70` | Text | `AUDIO_ALERT` | S $\to$ C | Play sound notification |
128
+ | `71` | Binary | `THREED_APPEND` | S $\to$ C | Streamed Three.js 3D GLTF asset progress |
129
+ | `72` | Binary | `THREED_DONE` | S $\to$ C | 3D model generation complete |
130
+ | `73` | Binary | `THREED_ERROR` | S $\to$ C | 3D model generation failed |
131
+ | `74` | Text | `REPORT_EVENT` | S $\to$ C | Thread/post report notification |
132
+ | `75` | Text | `REACTIONS` | Both | Emoji reactions: `{"t":"react","p":postId,"e":emojiId}` |
133
+ | `76` | Text | `FP_TOKEN_DELIVERY`| C $\to$ S | Post-handshake fingerprint token delivery |
134
+ | `77` | Text | `APPEAL_EVENT` | S $\to$ C | Ban appeal status event |
135
+ | `78` | Text | `CLOSED_EDIT` | S $\to$ C | Post edit applied after submission |
136
+ | `80` | Text | `ARCADE_EVENT` | Both | Multiplayer board game actions, moves, and clock updates |
137
+ | `81` | Binary | `CLAUDE_THINKING`| S $\to$ C | Streamed Claude / LLM internal reasoning tokens |
138
+ | `82` | Binary | `BYTEPLUS_APPEND`| S $\to$ C | ByteDance BytePlus video progress |
139
+ | `83` | Binary | `BYTEPLUS_DONE` | S $\to$ C | ByteDance BytePlus video complete |
140
+ | `84` | Binary | `BYTEPLUS_ERROR`| S $\to$ C | ByteDance BytePlus video failed |
141
+ | `85` | Text | `X_EMBED` | S $\to$ C | Twitter / X embed card metadata |
142
 
143
  ---
144
 
145
+ ## 5. The Arcade Subprotocol (Opcode `80`)
146
+
147
+ Operates entirely within `chunk-XX362ZFD.js` and provides 19+ in-thread games:
148
+ Chess, Checkers, Go, Reversi, Battleship, Mancala, Wordle, Liar's Dice, Ultimate Tic-Tac-Toe, Quoridor, Mastermind, Nim, Rock-Paper-Scissors, Nine Men's Morris, Game of the Amazons, Chomp, Memory, Minesweeper, Dominoes.
149
+
150
+ ### A. Client Action RPCs (`T({...})`)
151
+ ```json
152
+ // Query game catalog and available rules
153
+ 80{"t": "catalog"}
154
 
155
+ // Query active games and challenges in current thread
156
+ 80{"t": "list"}
157
+
158
+ // Spectate an ongoing match
159
+ 80{"t": "watch", "id": "<game_id>"}
160
+
161
+ // Stop spectating
162
+ 80{"t": "unwatch"}
163
+
164
+ // Accept or decline incoming challenges
165
+ 80{"t": "accept", "id": "<challenge_id>"}
166
+ 80{"t": "decline", "id": "<challenge_id>"}
167
+ 80{"t": "cancel", "id": "<challenge_id>"}
168
+
169
+ // Submit move in an active game
170
+ 80{"t": "move", "id": "<game_id>", "m": {"from": 12, "to": 28, "promo": "q"}}
171
+ 80{"t": "move", "id": "<game_id>", "m": {"c": 3}}
172
+ 80{"t": "move", "id": "<game_id>", "m": {"fleet": [...]}}
173
+
174
+ // Resign, rematch, or send in-game floating emote
175
+ 80{"t": "resign", "id": "<game_id>"}
176
+ 80{"t": "rematch", "id": "<game_id>"}
177
+ 80{"t": "emote", "id": "<game_id>", "e": 4}
178
  ```
179
+
180
+ ### B. Server Broadcasts (`switch(a.t)`)
181
+ - **`catalog`**: Lists supported games, player counts, and emoji palettes.
182
+ - **`snapshot`**: Complete state dump of live games, challenges, leaderboard rankings (`Ae`), personal ELO rating (`G`), and today's game count.
183
+ - **`match`**: Game state update containing board array, legal moves, current turn (`pending`), player timers, and move history.
184
+ - **`watchers`**: Live spectator count updates (`{"t": "watchers", "id": "...", "n": count}`).
185
+ - **`emote`**: In-game reaction bubble (`{"t": "emote", "id": "...", "e": emoteId, "from": playerIdx, "name": str}`).
186
+ - **`rated`**: Elo score updates post-match (`{"t": "rated", "id": "...", "ratings": [...], "rated": true}`).
187
+
188
+ ---
189
+
190
+ ## 6. NekoTV Synchronized Watch Parties (Opcode `54`)
191
+
192
+ Operates in `chunk-XMMHRB6S.js` with MSE streaming support in `chunk-LTTJLTTF.js`:
193
+ - **Supported Media Backends:** YouTube (`youtube-player`), Twitch (`twitchplayer`), TikTok (`tiktok-player`), and direct video streams (`raw-player`, `iframe-player`).
194
+ - **Synchronization Request:** Client sends `54` with no payload.
195
+ - **Server Response:**
196
+ ```json
197
+ 54{"elapsed": 142.5, "playlist": [...], "current": {...}}
198
+ ```
199
+ The client computes drift offset: $\Delta = (T_{\text{server}} - \text{elapsed})$ to ensure sub-second playback synchronization across all viewers.
200
+ - **Collaborative Queue Events:** `AddVideoEvent`, `RemoveVideoEvent`, `SkipVideoEvent`, `ClearPlaylistEvent`, `TogglePlaylistLockEvent`.
201
+ - **Democratic Voting:** `nekotv-vote` coordinates live skip votes (`yes_votes`, `no_votes`, `VoteSkip`, `VOTE_PASSED`, `VOTE_FAILED`).
202
+
203
+ ---
204
+
205
+ ## 7. In-Thread WebRTC Voice & Screen Channels (Opcode `63`)
206
+
207
+ Operates in `chunk-JTTGKNWN.js`:
208
+ - **Signaling via WebSocket:** Peer discovery and ICE candidate exchange occur over message type `63`:
209
+ - `peer-joined`, `peer-left`, `peer-ping`, `peer-updated`
210
+ - `makeOffer`, `offer`, `answer`, `iceCandidate`
211
+ - **TURN Credentials:** Ephemeral TURN credentials fetched via `GET /api/turn-credentials`.
212
+ - **Audio Processing Features:** Voice-activity detection (animated avatar rings `rtc-speak-av`), software gain control, WebRTC denoise/suppression, push-to-talk (`rtc-ptt-key`), and stage audio moderation (`rtc-stage-mute`).
213
+
214
+ ---
215
+
216
+ ## 8. Media Upload & Deduplication Pipeline
217
+
218
+ Operates in `chunk-NRU3NIKF.js`:
219
+ 1. **Client-Side SHA-1 Deduplication:**
220
+ - Before uploading any file, the client computes its SHA-1 digest using `crypto.subtle.digest("SHA-1", buffer)`.
221
+ - Sends: `POST /api/upload-hash` with the SHA-1 digest hex string.
222
+ - If the file was already uploaded to the server by anyone, the server immediately responds with `HTTP 200` and the file token `d`. The upload is instant with zero media bytes transferred!
223
+ 2. **Chunked Upload Fallback:**
224
+ - If the hash is not present, the client uploads the file in chunks via `POST /api/upload-chunk` or `POST /api/upload`.
225
+ - Max file size: 80 MB (`io = 80 * 1024 * 1024`).
226
+ - Supported extensions (`chunk-PVG4O4YS.js`): `png`, `jpg`, `gif`, `webp`, `avif`, `mp4`, `webm`, `mp3`, `ogg`, `flac`, `wav`, `pdf`, `txt`, `zip`, `rar`, `cbz`, `cbr`, `torrent`, `swf`, `glb` (3D).
227
+
228
+ ---
229
+
230
+ ## 9. HTTP Delta Polling Fallback (`/json/thread-updates`)
231
+
232
+ For clients operating in background or low-power modes without an open WebSocket connection, Nekohash provides a high-efficiency batch thread checker:
233
+ - **Request:**
234
+ ```http
235
+ POST /json/thread-updates HTTP/1.1
236
+ Content-Type: application/json
237
+
238
+ {
239
+ "1256858": 45,
240
+ "1256800": 12,
241
+ "1256750": 108
242
+ }
243
+ ```
244
+ - **Response:**
245
+ ```json
246
+ {
247
+ "changed": {
248
+ "1256858": 48
249
+ },
250
+ "deleted": [1256750]
251
+ }
252
+ ```
253
+ Allows monitoring hundreds of threads in a single HTTP request with near-zero overhead.
254
+ Individual posts can be retrieved atomically via `GET /json/post/{postId}`.
255
+
256
+ ---
257
+
258
+ ## 10. Shared Zstandard Dictionaries (RFC 9110)
259
+
260
+ The engine serves HTML compressed using per-board trained Zstandard dictionaries advertised via:
261
+ ```html
262
+ <link rel="dictionary" href="/assets/dictionaries/g/html-c04241c04b24b38323c3dd00da338d495e3dff0c1c2b3218e3ccb98d8b8180dd.dict">
263
  ```
264
+ Using the standard HTTP `Use-As-Dictionary` header and `dcb` / `dcz` content-encoding, repeated HTML structures (board navigation, post container boilerplate, SVG icons) achieve $>85\%$ compression ratios compared to generic gzip.
protocol.py CHANGED
@@ -1,69 +1,131 @@
1
  """
2
  WebSocket protocol for nekohash imageboard engine (awoo.cf).
3
 
4
- Reverse-engineered from client bundles (app-AGKBSCUS.js, chunk-NRU3NIKF.js, chunk-XX362ZFD.js)
 
5
  and network captures on November 16, 2026.
6
  """
7
 
8
  import json
 
9
  from enum import IntEnum
10
  from dataclasses import dataclass
11
- from typing import Any, Optional
12
 
13
 
14
  class MessageType(IntEnum):
15
- """WebSocket message types (client-to-server and server-to-client)."""
 
 
 
 
16
 
17
- # 0-29: Modify post model state & streaming edits
18
  ERROR = 0
19
  INSERT_POST = 1
20
- APPEND = 2
21
- BACKSPACE = 3
22
- SPLICE = 4
23
  CLOSE_POST = 5
24
  INSERT_IMAGE = 6
25
- SPOILER = 7
26
- MODERATE_POST = 8
27
- STOLE_IMAGE_FROM = 9
28
- STOLE_IMAGE_TO = 10
29
- CLAUDE_APPEND = 11
30
- CLAUDE_DONE = 12
31
- CLAUDE_ERROR = 13
32
- ATTACH_TIKTOK = 14
33
- TIKTOK_STATE = 15
34
- NEKO_TV = 16
35
-
36
- # 30-43: Legacy / control commands
37
- LEGACY_SYNCHRONISE = 30
38
- RECLAIM = 31
39
- POST_ID = 32
40
- CONCAT = 33
41
- LEGACY_NOOP = 34
42
- SYNC_COUNT = 35
43
- LEGACY_SERVER_TIME = 36
44
- REDIRECT = 37
45
- NOTIFICATION = 38
46
- MEGU_TV = 39
47
- CAPTCHA = 40
48
- CONFIGS = 41
49
- SET_COOKIE = 42
50
-
51
- # 44+: Nekohash custom protocol extensions
52
- SYNCHRONISE = 44 # Board / Thread state sync
53
- POST_PASSWORD = 45 # Reclaim draft with password
54
- BATCH_EVENTS = 47 # Batched streaming events
55
- NOOP_PING = 48 # Periodic keepalive ping
56
- PRESENCE = 49 # Active site/thread/NekoTV viewer counts
57
- SERVER_TIME = 50 # Millisecond server timestamp
58
- BOARD_CONFIG = 55 # Dynamic board feature flags (NSFW, games, webRTC)
59
- SESSION_CONFIG = 56 # Captcha session and token updates
60
- SESSION_KEY = 57 # 16-byte session key rotation
61
- POLL_UPDATE = 59 # Poll creation / state
62
- POLL_VOTE = 60 # Poll vote update
63
- WEBRTC_SIGNAL = 63 # WebRTC peer discovery, SDP, and ICE signaling
64
- REACTIONS = 75 # Post emoji reaction events
65
- FP_TOKEN_DELIVERY = 76 # Post-handshake fingerprint token delivery
66
- ARCADE_EVENT = 80 # Real-time multiplayer board game actions & clock
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
67
 
68
 
69
  @dataclass
@@ -79,29 +141,34 @@ class NekohashSyncRequest:
79
 
80
 
81
  @dataclass
82
- class AppendRequest:
83
- """Append character to post body."""
84
- char: str
 
 
85
 
86
 
87
  @dataclass
88
- class SpliceRequest:
89
- """Splice text in post body."""
 
90
  start: int
91
- delete: int
92
  text: str
93
 
94
 
95
  @dataclass
96
- class ReactionRequest:
97
- """Send emoji reaction to a post (type 75)."""
98
- post_id: int
99
- emoji_id: int
 
 
100
 
101
 
102
  def encode_message(msg_type: MessageType | int, payload: Any = None) -> str:
103
  """
104
- Encode a message for sending over WebSocket.
105
  Format: "<2-digit-type><payload>" (or "<type>" if payload is None).
106
  """
107
  type_val = msg_type.value if isinstance(msg_type, MessageType) else int(msg_type)
@@ -113,11 +180,57 @@ def encode_message(msg_type: MessageType | int, payload: Any = None) -> str:
113
  return type_str + json.dumps(payload, separators=(",", ":"))
114
 
115
 
116
- def decode_message(data: str) -> tuple[int, Any]:
117
  """
118
- Decode a message received from WebSocket.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
119
  Returns: (type_code, parsed_payload)
120
  """
 
 
 
121
  if len(data) < 2:
122
  raise ValueError(f"Message too short: {data}")
123
 
@@ -126,6 +239,19 @@ def decode_message(data: str) -> tuple[int, Any]:
126
  return type_code, None
127
 
128
  payload_str = data[2:]
 
 
 
 
 
 
 
 
 
 
 
 
 
129
  try:
130
  payload = json.loads(payload_str)
131
  except json.JSONDecodeError:
@@ -148,3 +274,18 @@ def build_synchronise(board: str = "all", thread: Optional[int] = None, fp_token
148
  def build_noop() -> str:
149
  """Build type 48 NOOP keepalive ping."""
150
  return encode_message(MessageType.NOOP_PING)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  """
2
  WebSocket protocol for nekohash imageboard engine (awoo.cf).
3
 
4
+ Reverse-engineered from client bundles (app-AGKBSCUS.js, chunk-NRU3NIKF.js,
5
+ chunk-XX362ZFD.js, chunk-XMMHRB6S.js, chunk-JTTGKNWN.js, chunk-PVG4O4YS.js)
6
  and network captures on November 16, 2026.
7
  """
8
 
9
  import json
10
+ import struct
11
  from enum import IntEnum
12
  from dataclasses import dataclass
13
+ from typing import Any, Optional, Union
14
 
15
 
16
  class MessageType(IntEnum):
17
+ """
18
+ WebSocket message types (client-to-server and server-to-client).
19
+ Text messages: <2-digit-type><payload>
20
+ Binary messages: <8-byte float64 post_id><payload><1-byte type>
21
+ """
22
 
23
+ # Post state & Keystroke streaming
24
  ERROR = 0
25
  INSERT_POST = 1
26
+ APPEND = 2 # Binary: [post_id (8B), utf-8 text, 0x02]
27
+ BACKSPACE = 3 # Binary: [post_id (8B), 0x03]
28
+ SPLICE = 4 # Binary: [post_id (8B), start (2B), len (2B), utf-8 text, 0x04]
29
  CLOSE_POST = 5
30
  INSERT_IMAGE = 6
31
+ SPOILER_IMAGE = 7
32
+ APPLY_MODERATION = 8
33
+ REMOVE_IMAGE = 9
34
+ REPLACE_IMAGE = 10
35
+
36
+ # Generative AI Streaming: Claude / LLM
37
+ CLAUDE_APPEND = 11 # Binary: Claude streamed text
38
+ CLAUDE_DONE = 12 # Binary
39
+ CLAUDE_ERROR = 13 # Binary
40
+
41
+ # Generative AI: Imagen (Text-to-Image)
42
+ IMAGEN_APPEND = 14 # Binary
43
+ IMAGEN_DONE = 15 # Binary
44
+ IMAGEN_ERROR = 16 # Binary
45
+
46
+ # Generative AI: Videogen
47
+ VIDEOGEN_APPEND = 17 # Binary
48
+ VIDEOGEN_DONE = 18 # Binary
49
+ VIDEOGEN_ERROR = 19 # Binary
50
+
51
+ # Generative AI: Editgen (Image Editing)
52
+ EDITGEN_APPEND = 20 # Binary
53
+ EDITGEN_DONE = 21 # Binary
54
+ EDITGEN_ERROR = 22 # Binary
55
+
56
+ # Generative AI: Imgtovid (Image-to-Video)
57
+ IMGTOVID_APPEND = 23 # Binary
58
+ IMGTOVID_DONE = 24 # Binary
59
+ IMGTOVID_ERROR = 25 # Binary
60
+
61
+ # Generative AI: Img2veo (Google Veo Video)
62
+ IMG2VEO_APPEND = 26 # Binary
63
+ IMG2VEO_DONE = 27 # Binary
64
+ IMG2VEO_ERROR = 28 # Binary
65
+
66
+ # Generative AI: Grok Video (xAI Grok)
67
+ GROKVID_APPEND = 29 # Binary
68
+ GROKVID_DONE = 30 # Binary
69
+ GROKVID_ERROR = 31 # Binary
70
+ GROKVID_APPEND_ALT = 32 # Binary
71
+ GROKVID_DONE_ALT = 33 # Binary
72
+ GROKVID_ERROR_ALT = 34 # Binary
73
+
74
+ # Embeds
75
+ TIKTOK_PENDING = 36 # TikTok embed state
76
+
77
+ # Session / Crypto / Control
78
+ FP_TOKEN_RECEIVE = 43 # Binary
79
+ SYNCHRONISE = 44 # Board / Thread state sync
80
+ POST_PASSWORD = 45 # Reclaim draft with password
81
+ RECEIVE_ID = 46 # Allocation post ID assignment
82
+ BATCH_EVENTS = 47 # Batched streaming events
83
+ NOOP_PING = 48 # Periodic keepalive ping
84
+ PRESENCE = 49 # Active site/thread/NekoTV viewer counts
85
+ SERVER_TIME = 50 # Millisecond server timestamp
86
+ REDIRECT = 51 # URL redirect command
87
+ NOTIFICATION = 52 # Browser notification trigger
88
+ CAPTCHA_TRIGGER = 53 # Trigger captcha challenge
89
+ NEKO_TV_SYNC = 54 # NekoTV shared watch-party sync
90
+ BOARD_CONFIG = 55 # Dynamic board feature flags (NSFW, games, webRTC)
91
+ SESSION_CONFIG = 56 # Captcha session and token updates
92
+ SESSION_KEY = 57 # 16-byte session key rotation (Binary)
93
+ SYNC_COUNT = 58 # Synced client counter
94
+ POLL_UPDATE = 59 # In-thread poll definition
95
+ POLL_VOTE = 60 # Poll vote cast/counts
96
+ THREAD_CREATED = 62 # New thread created broadcast
97
+ WEBRTC_SIGNAL = 63 # WebRTC peer discovery, SDP, and ICE signaling
98
+
99
+ # Generative AI: Venice Video (Venice AI)
100
+ VENICEVID_APPEND = 64 # Binary
101
+ VENICEVID_DONE = 65 # Binary
102
+ VENICEVID_ERROR = 66 # Binary
103
+
104
+ # Generative AI: Atlas Video (ByteDance Atlas)
105
+ ATLASVID_APPEND = 67 # Binary
106
+ ATLASVID_DONE = 68 # Binary
107
+ ATLASVID_ERROR = 69 # Binary
108
+
109
+ # Audio & 3D Assets
110
+ AUDIO_ALERT = 70 # Ding / audio notification
111
+ THREED_APPEND = 71 # Binary: Three.js 3D GLTF asset streaming
112
+ THREED_DONE = 72 # Binary
113
+ THREED_ERROR = 73 # Binary
114
+
115
+ # Reports, Reactions, Appeals, Edits
116
+ REPORT_EVENT = 74 # Meguca report event
117
+ REACTIONS = 75 # Post emoji reaction events
118
+ FP_TOKEN_DELIVERY = 76 # Post-handshake fingerprint token delivery
119
+ APPEAL_EVENT = 77 # Meguca appeal event
120
+ CLOSED_EDIT = 78 # Post editing after submission
121
+
122
+ # The Arcade & Extended Pipelines
123
+ ARCADE_EVENT = 80 # In-thread multiplayer games & clock updates
124
+ CLAUDE_THINKING = 81 # Binary: Claude / LLM internal reasoning stream
125
+ BYTEPLUSVID_APPEND = 82 # Binary: ByteDance BytePlus video streaming
126
+ BYTEPLUSVID_DONE = 83 # Binary
127
+ BYTEPLUSVID_ERROR = 84 # Binary
128
+ X_EMBED = 85 # Twitter / X embed card
129
 
130
 
131
  @dataclass
 
141
 
142
 
143
  @dataclass
144
+ class BinaryStreamChunk:
145
+ """Decoded binary stream chunk (keystroke append, AI streaming, etc.)."""
146
+ post_id: float
147
+ text: str
148
+ msg_type: MessageType
149
 
150
 
151
  @dataclass
152
+ class SpliceEvent:
153
+ """Decoded binary splice event (type 04)."""
154
+ post_id: float
155
  start: int
156
+ length: int
157
  text: str
158
 
159
 
160
  @dataclass
161
+ class ArcadeAction:
162
+ """Arcade client-to-server action (type 80)."""
163
+ t: str
164
+ id: Optional[str] = None
165
+ m: Optional[dict] = None
166
+ e: Optional[int] = None
167
 
168
 
169
  def encode_message(msg_type: MessageType | int, payload: Any = None) -> str:
170
  """
171
+ Encode a text message for sending over WebSocket.
172
  Format: "<2-digit-type><payload>" (or "<type>" if payload is None).
173
  """
174
  type_val = msg_type.value if isinstance(msg_type, MessageType) else int(msg_type)
 
180
  return type_str + json.dumps(payload, separators=(",", ":"))
181
 
182
 
183
+ def decode_binary_message(data: bytes | bytearray) -> tuple[int, Any]:
184
  """
185
+ Decode a binary message frame from WebSocket.
186
+ Structure:
187
+ - Last byte (len-1): opcode uint8
188
+ - Byte 0..7: post ID (double / float64 little-endian)
189
+ - Byte 8..len-2: payload
190
+ """
191
+ if len(data) == 0:
192
+ raise ValueError("Empty binary frame")
193
+
194
+ opcode = data[-1]
195
+
196
+ # Type 3: BACKSPACE -> [post_id (8B), 0x03]
197
+ if opcode == MessageType.BACKSPACE:
198
+ if len(data) < 9:
199
+ return opcode, None
200
+ post_id = struct.unpack("<d", data[:8])[0]
201
+ return opcode, {"post_id": post_id}
202
+
203
+ # Type 4: SPLICE -> [post_id (8B), start (2B), len (2B), text, 0x04]
204
+ if opcode == MessageType.SPLICE:
205
+ if len(data) < 13:
206
+ return opcode, None
207
+ post_id = struct.unpack("<d", data[:8])[0]
208
+ start, splice_len = struct.unpack("<HH", data[8:12])
209
+ text = data[12:-1].decode("utf-8", errors="replace")
210
+ return opcode, SpliceEvent(post_id=post_id, start=start, length=splice_len, text=text)
211
+
212
+ # Standard Binary Stream: [post_id (8B), text (variable), opcode (1B)]
213
+ if len(data) >= 9:
214
+ post_id = struct.unpack("<d", data[:8])[0]
215
+ text_bytes = data[8:-1]
216
+ text = text_bytes.decode("utf-8", errors="replace")
217
+ try:
218
+ enum_type = MessageType(opcode)
219
+ except ValueError:
220
+ enum_type = opcode
221
+ return opcode, BinaryStreamChunk(post_id=post_id, text=text, msg_type=enum_type)
222
+
223
+ return opcode, data[:-1]
224
+
225
+
226
+ def decode_message(data: Union[str, bytes, bytearray]) -> tuple[int, Any]:
227
+ """
228
+ Decode a message received from WebSocket (supports both text and binary frames).
229
  Returns: (type_code, parsed_payload)
230
  """
231
+ if isinstance(data, (bytes, bytearray)):
232
+ return decode_binary_message(data)
233
+
234
  if len(data) < 2:
235
  raise ValueError(f"Message too short: {data}")
236
 
 
239
  return type_code, None
240
 
241
  payload_str = data[2:]
242
+
243
+ # Handle batched events (type 47)
244
+ if type_code == MessageType.BATCH_EVENTS:
245
+ try:
246
+ batch = json.loads(payload_str)
247
+ parsed_batch = []
248
+ for item in batch:
249
+ if isinstance(item, str):
250
+ parsed_batch.append(decode_message(item))
251
+ return type_code, parsed_batch
252
+ except json.JSONDecodeError:
253
+ return type_code, payload_str
254
+
255
  try:
256
  payload = json.loads(payload_str)
257
  except json.JSONDecodeError:
 
274
  def build_noop() -> str:
275
  """Build type 48 NOOP keepalive ping."""
276
  return encode_message(MessageType.NOOP_PING)
277
+
278
+
279
+ def build_arcade_action(action: str, game_id: Optional[str] = None, move_data: Optional[dict] = None) -> str:
280
+ """Build type 80 Arcade action message."""
281
+ payload = {"t": action}
282
+ if game_id:
283
+ payload["id"] = game_id
284
+ if move_data:
285
+ payload["m"] = move_data
286
+ return encode_message(MessageType.ARCADE_EVENT, payload)
287
+
288
+
289
+ def build_nekotv_sync() -> str:
290
+ """Build type 54 NekoTV synchronization request."""
291
+ return encode_message(MessageType.NEKO_TV_SYNC, None)