witbitz-code 1.2.0__tar.gz

witbitz_code-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Witbitz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

witbitz_code-1.2.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: witbitz-code
+Version: 1.2.0
+Summary: Reach OpenCode on this computer from the Witbitz Spaces Code section, through an end-to-end sealed relay.
+Author: Witbitz
+License-Expression: MIT
+Project-URL: Documentation, https://witbitz.chat/docs/opencode.md
+Project-URL: Repository, https://github.com/witbitzchat/witbitz-code
+Keywords: witbitz,opencode,relay,e2ee
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41
+Requires-Dist: websockets>=13
+Requires-Dist: httpx>=0.25
+Requires-Dist: segno>=1.5
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# witbitz-code
+
+Use the **Code** section of Witbitz Spaces, on any device you're signed in on, to reach
+[OpenCode](https://opencode.ai) running on your computer. It's end-to-end encrypted, needs no open port, and doesn't need
+Tailscale.
+
+This is the Python build of the `witbitz-code` tool. It speaks the same wire protocol, uses the same pairing file and the
+same account registry as the single-file Node download (`node witbitz-code.mjs`), so either one can pair a computer and
+the other can serve or unpair it.
+
+## Install
+
+```sh
+pipx install witbitz-code          # or: pip install witbitz-code
+```
+
+Python 3.10 or newer. Dependencies: `cryptography`, `websockets`, `httpx`, `segno`.
+
+You also need OpenCode itself: `npm install -g opencode-ai` or `curl -fsSL https://opencode.ai/install | bash`.
+
+## Use
+
+```sh
+witbitz-code pair                 # shows a QR code: scan it in Spaces → Settings → Back up & recovery → Add a device
+witbitz-code serve                # starts OpenCode on 127.0.0.1:4096 (unless it is running) and the connector
+```
+
+Then open Code in Spaces. Leave `serve` running (Ctrl-C stops it).
+
+| command | what it does |
+|---|---|
+| `pair [--name <name>] [--port <n> \| --opencode-url <url>]` | Show the QR code. The account that scans it gets this computer. `--name` sets the label your devices show (default: the hostname). |
+| `serve [--port <n>] [--no-opencode]` | Start OpenCode on `127.0.0.1:<n>` (default 4096) if nothing is listening there, then connect the pairings whose OpenCode is on that port. One OpenCode per port, one `serve` per OpenCode. |
+| `status` | List this computer's pairings: name, account, OpenCode address and relay. Secrets are never printed. |
+| `rotate [--account <email>]` | Replace the pairing secret(s) without scanning again, then restart `serve`. Devices pick up the new secret on their next sync. |
+| `unpair [--account <email>]` | Remove this computer from an account. Every device drops it on its next sync. |
+| `version`, `--help` | |
+
+`pair`, `rotate` and `unpair` also accept `--dry-run`.
+
+**More than one account.** Each account that scans the QR code gets its own pairing, with its own secret and relay
+channel. OpenCode has no users, so every paired account reaches the same sessions, files and shell. That's fine when
+all the accounts are yours. If a second account belongs to **another person**, run a separate OpenCode for them
+(another port, ideally another OS user) and pair that account with `--port`.
+
+## How it works
+
+```
+ phone / desktop (Code page)                               this computer
+ seal ▸ frames ◂ open  ── wss ─▶ code-relay.witbitz.chat ◀─ wss ──  witbitz-code serve ──▶ opencode (127.0.0.1)
+```
+
+- **Both ends dial out** to `wss://code-relay.witbitz.chat`. Nothing listens on your network, and OpenCode never leaves
+  `127.0.0.1`.
+- **Pairing** uses a device link: the QR code holds only an ephemeral public key. Your signed-in device seals the account
+  pointer to that key. The computer then mints a random 32-byte **secret** for this pairing and does two things with it:
+  - stores it in `~/.witbitz/code/pairings.json` (mode 0600);
+  - publishes it into the account's sealed `computers` registry, which every signed-in device reads.
+- **Keys:** the relay channel id and two direction keys (page→computer and computer→page, AES-256-GCM) are derived from
+  the secret with HKDF-SHA256. A frame reflected back at its sender doesn't decrypt.
+- **Every frame is sealed.** The relay forwards ciphertext it can't read, and the clear header (sender id, sequence
+  number) is authenticated. Receivers drop replays. Large bodies are split into parts below the relay's message size cap.
+- **Replays across restarts:** each time the connector's socket opens, it announces a fresh random nonce inside its
+  sealed hello. Every request and subscription must carry that nonce, so a request recorded before a restart or
+  reconnect is refused (409) and never reaches OpenCode.
+- **The connector only forwards what the Code page itself calls:** list and read sessions, send a message, abort, answer
+  a permission prompt, rename and delete. Every other request gets a 403 without touching OpenCode. OpenCode can run shell
+  commands, so a leaked secret must not unlock more than the page can do. The live event stream is forwarded only while
+  a device is watching.
+- **The OpenCode password** lives in `~/.opencode-server.env` (created 0600 on first pair). The connector adds it to local
+  calls, and it never leaves the computer.
+
+**Auto mode** (Manual · Accept edits · Plan · **Auto** in the Code composer's mode chip, per session) lets this computer answer OpenCode's permission
+prompts while you are away:
+- **Refused at once:** what is never safe, like `rm -rf ~`, `mkfs` or `dd` onto a disk. The agent is told why.
+- **Allowed at once:** read-only commands that stay inside the project, and edits to ordinary files in it.
+- **Everything else** goes to the session's own model, in a throw-away session that can use no tools. Only a clear,
+  low-severity allow runs. A refusal, "ask", an unclear answer or a timeout leaves the prompt for you.
+- **Never "always":** each answer covers that one call.
+
+Each decision is logged to `~/.witbitz/code/auto-log.jsonl` as a digest, never the command. The rules are shared with the
+Node connector and tested against the same cases, so both decide alike.
+
+**What is encrypted, and what isn't.** Requests, responses and events travel end to end. The relay operator sees a
+pseudonymous channel id, IP addresses, connection times, and frame sizes and timing. That's the same class of metadata
+the Spaces room store sees. Anyone holding a pairing secret can drive OpenCode within the allowlist until you run
+`rotate`.
+
+Design: `docs/opencode-relay.md` in the Witbitz repository.
+
+## Files and environment
+
+| | default | override |
+|---|---|---|
+| pairings | `~/.witbitz/code/pairings.json` | `WITBITZ_CODE_PAIRINGS` |
+| OpenCode password | `~/.opencode-server.env` (`OPENCODE_SERVER_PASSWORD=`) | `OPENCODE_ENV_FILE` |
+| pairing QR, as SVG | `~/.witbitz-rc.link.svg` | |
+| Auto mode state + decision log | `~/.witbitz/code/auto-<computer>.json`, `auto-log.jsonl` | `WITBITZ_CODE_AUTO_DIR` |
+| account API | `https://api.witbitz.chat/v1/space` | `RC_BASE`, `RC_ORIGIN` |
+| device-link origins | `https://spaces.witbitz.chat,https://witbitz-spaces.pages.dev` | `RC_LINK_ORIGIN` |
+
+## Development
+
+```sh
+pip install -e '.[test]'
+python -m pytest tests -q
+```
+
+The tests hold this package to the JavaScript reference implementation. They run the modules in `spaces/public/` and
+`tools/` under `node` (22 or newer), and they cover:
+
+- the pinned HKDF vectors;
+- frames sealed on either side opening on the other;
+- chunking through surrogate pairs;
+- the device-link reply and the backup keys;
+- the registry merge rules, compared byte for byte;
+- the pairing file in both directions;
+- the gzip wrap of account docs;
+- a connector of each language driven by a client of the other, through a local fake relay and a fake OpenCode.
+
+Without the repository checkout (`WITBITZ_REPO`) or `node`, the cross-implementation tests are skipped.

witbitz_code-1.2.0/README.md

@@ -0,0 +1,121 @@
+# witbitz-code
+
+Use the **Code** section of Witbitz Spaces, on any device you're signed in on, to reach
+[OpenCode](https://opencode.ai) running on your computer. It's end-to-end encrypted, needs no open port, and doesn't need
+Tailscale.
+
+This is the Python build of the `witbitz-code` tool. It speaks the same wire protocol, uses the same pairing file and the
+same account registry as the single-file Node download (`node witbitz-code.mjs`), so either one can pair a computer and
+the other can serve or unpair it.
+
+## Install
+
+```sh
+pipx install witbitz-code          # or: pip install witbitz-code
+```
+
+Python 3.10 or newer. Dependencies: `cryptography`, `websockets`, `httpx`, `segno`.
+
+You also need OpenCode itself: `npm install -g opencode-ai` or `curl -fsSL https://opencode.ai/install | bash`.
+
+## Use
+
+```sh
+witbitz-code pair                 # shows a QR code: scan it in Spaces → Settings → Back up & recovery → Add a device
+witbitz-code serve                # starts OpenCode on 127.0.0.1:4096 (unless it is running) and the connector
+```
+
+Then open Code in Spaces. Leave `serve` running (Ctrl-C stops it).
+
+| command | what it does |
+|---|---|
+| `pair [--name <name>] [--port <n> \| --opencode-url <url>]` | Show the QR code. The account that scans it gets this computer. `--name` sets the label your devices show (default: the hostname). |
+| `serve [--port <n>] [--no-opencode]` | Start OpenCode on `127.0.0.1:<n>` (default 4096) if nothing is listening there, then connect the pairings whose OpenCode is on that port. One OpenCode per port, one `serve` per OpenCode. |
+| `status` | List this computer's pairings: name, account, OpenCode address and relay. Secrets are never printed. |
+| `rotate [--account <email>]` | Replace the pairing secret(s) without scanning again, then restart `serve`. Devices pick up the new secret on their next sync. |
+| `unpair [--account <email>]` | Remove this computer from an account. Every device drops it on its next sync. |
+| `version`, `--help` | |
+
+`pair`, `rotate` and `unpair` also accept `--dry-run`.
+
+**More than one account.** Each account that scans the QR code gets its own pairing, with its own secret and relay
+channel. OpenCode has no users, so every paired account reaches the same sessions, files and shell. That's fine when
+all the accounts are yours. If a second account belongs to **another person**, run a separate OpenCode for them
+(another port, ideally another OS user) and pair that account with `--port`.
+
+## How it works
+
+```
+ phone / desktop (Code page)                               this computer
+ seal ▸ frames ◂ open  ── wss ─▶ code-relay.witbitz.chat ◀─ wss ──  witbitz-code serve ──▶ opencode (127.0.0.1)
+```
+
+- **Both ends dial out** to `wss://code-relay.witbitz.chat`. Nothing listens on your network, and OpenCode never leaves
+  `127.0.0.1`.
+- **Pairing** uses a device link: the QR code holds only an ephemeral public key. Your signed-in device seals the account
+  pointer to that key. The computer then mints a random 32-byte **secret** for this pairing and does two things with it:
+  - stores it in `~/.witbitz/code/pairings.json` (mode 0600);
+  - publishes it into the account's sealed `computers` registry, which every signed-in device reads.
+- **Keys:** the relay channel id and two direction keys (page→computer and computer→page, AES-256-GCM) are derived from
+  the secret with HKDF-SHA256. A frame reflected back at its sender doesn't decrypt.
+- **Every frame is sealed.** The relay forwards ciphertext it can't read, and the clear header (sender id, sequence
+  number) is authenticated. Receivers drop replays. Large bodies are split into parts below the relay's message size cap.
+- **Replays across restarts:** each time the connector's socket opens, it announces a fresh random nonce inside its
+  sealed hello. Every request and subscription must carry that nonce, so a request recorded before a restart or
+  reconnect is refused (409) and never reaches OpenCode.
+- **The connector only forwards what the Code page itself calls:** list and read sessions, send a message, abort, answer
+  a permission prompt, rename and delete. Every other request gets a 403 without touching OpenCode. OpenCode can run shell
+  commands, so a leaked secret must not unlock more than the page can do. The live event stream is forwarded only while
+  a device is watching.
+- **The OpenCode password** lives in `~/.opencode-server.env` (created 0600 on first pair). The connector adds it to local
+  calls, and it never leaves the computer.
+
+**Auto mode** (Manual · Accept edits · Plan · **Auto** in the Code composer's mode chip, per session) lets this computer answer OpenCode's permission
+prompts while you are away:
+- **Refused at once:** what is never safe, like `rm -rf ~`, `mkfs` or `dd` onto a disk. The agent is told why.
+- **Allowed at once:** read-only commands that stay inside the project, and edits to ordinary files in it.
+- **Everything else** goes to the session's own model, in a throw-away session that can use no tools. Only a clear,
+  low-severity allow runs. A refusal, "ask", an unclear answer or a timeout leaves the prompt for you.
+- **Never "always":** each answer covers that one call.
+
+Each decision is logged to `~/.witbitz/code/auto-log.jsonl` as a digest, never the command. The rules are shared with the
+Node connector and tested against the same cases, so both decide alike.
+
+**What is encrypted, and what isn't.** Requests, responses and events travel end to end. The relay operator sees a
+pseudonymous channel id, IP addresses, connection times, and frame sizes and timing. That's the same class of metadata
+the Spaces room store sees. Anyone holding a pairing secret can drive OpenCode within the allowlist until you run
+`rotate`.
+
+Design: `docs/opencode-relay.md` in the Witbitz repository.
+
+## Files and environment
+
+| | default | override |
+|---|---|---|
+| pairings | `~/.witbitz/code/pairings.json` | `WITBITZ_CODE_PAIRINGS` |
+| OpenCode password | `~/.opencode-server.env` (`OPENCODE_SERVER_PASSWORD=`) | `OPENCODE_ENV_FILE` |
+| pairing QR, as SVG | `~/.witbitz-rc.link.svg` | |
+| Auto mode state + decision log | `~/.witbitz/code/auto-<computer>.json`, `auto-log.jsonl` | `WITBITZ_CODE_AUTO_DIR` |
+| account API | `https://api.witbitz.chat/v1/space` | `RC_BASE`, `RC_ORIGIN` |
+| device-link origins | `https://spaces.witbitz.chat,https://witbitz-spaces.pages.dev` | `RC_LINK_ORIGIN` |
+
+## Development
+
+```sh
+pip install -e '.[test]'
+python -m pytest tests -q
+```
+
+The tests hold this package to the JavaScript reference implementation. They run the modules in `spaces/public/` and
+`tools/` under `node` (22 or newer), and they cover:
+
+- the pinned HKDF vectors;
+- frames sealed on either side opening on the other;
+- chunking through surrogate pairs;
+- the device-link reply and the backup keys;
+- the registry merge rules, compared byte for byte;
+- the pairing file in both directions;
+- the gzip wrap of account docs;
+- a connector of each language driven by a client of the other, through a local fake relay and a fake OpenCode.
+
+Without the repository checkout (`WITBITZ_REPO`) or `node`, the cross-implementation tests are skipped.

witbitz_code-1.2.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "witbitz-code"
+version = "1.2.0"
+description = "Reach OpenCode on this computer from the Witbitz Spaces Code section, through an end-to-end sealed relay."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Witbitz" }]
+keywords = ["witbitz", "opencode", "relay", "e2ee"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Environment :: Console",
+  "Topic :: Software Development",
+]
+dependencies = [
+  "cryptography>=41",
+  "websockets>=13",
+  "httpx>=0.25",
+  "segno>=1.5",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Documentation = "https://witbitz.chat/docs/opencode.md"
+Repository = "https://github.com/witbitzchat/witbitz-code"
+
+[project.scripts]
+witbitz-code = "witbitz_code.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Our OpenCode plugins, installed by `serve` (plugins.py) — copies of tools/opencode-plugins, kept current by embed.mjs
+[tool.setuptools.package-data]
+witbitz_code = ["opencode_plugins/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

witbitz_code-1.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

witbitz_code-1.2.0/src/witbitz_code/__init__.py

@@ -0,0 +1,7 @@
+"""witbitz-code: reach OpenCode on this computer from the Spaces Code section, end-to-end encrypted.
+
+The Python implementation of tools/witbitz-code.mjs (docs/opencode-relay.md phase 5b), held to the JS one by shared test
+vectors and cross-implementation tests.
+"""
+
+__version__ = "1.2.0"

witbitz_code-1.2.0/src/witbitz_code/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

witbitz_code-1.2.0/src/witbitz_code/_js.py

@@ -0,0 +1,312 @@
+"""JavaScript semantics this port has to reproduce, in one place.
+
+The JS tools are the reference implementation and the page runs them, so wherever the wire or a shared file depends on
+a JS rule, Python follows the rule rather than its own idiom:
+
+- JSON.stringify: compact, integral floats print as integers (1000, not 1000.0), lone UTF-16 surrogates are escaped,
+  integer-like object keys come first. Byte-identical output keeps the pairings file and the gzip-size threshold equal.
+- String lengths and slices count UTF-16 code units (chunking at 192 KiB, `name.slice(0, 80)`, `id.slice(0, 64)`). A
+  slice may split a surrogate pair exactly as JS does; joining the halves back recombines it.
+- Truthiness, unary `+`, `String(x)`, `Number.isInteger`: the registry and payload readers lean on all of them.
+- atob's "forgiving base64": what the page accepts, Python accepts, and nothing more.
+"""
+
+from __future__ import annotations
+
+import base64
+import decimal
+import json
+import math
+import re
+from typing import Any
+
+MAX_SAFE_INTEGER = 2**53 - 1
+
+
+class _Undefined:
+    """A property that is absent (JS `undefined`), as opposed to JSON null (None)."""
+
+    _inst = None
+
+    def __new__(cls):
+        if cls._inst is None:
+            cls._inst = super().__new__(cls)
+        return cls._inst
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __repr__(self) -> str:
+        return "undefined"
+
+
+UNDEFINED = _Undefined()
+
+# ECMAScript WhiteSpace + LineTerminator — what `\s` and String.prototype.trim() mean in JS (Python's differ: no U+FEFF).
+WS = "\t\n\x0b\x0c\r \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff"
+# JS `.` stops at these; Python's `.` stops only at \n.
+NOT_LT = "[^\n\r\u2028\u2029]"
+_TRIM = re.compile(f"\\A[{WS}]+|[{WS}]+\\Z")
+
+
+def is_num(v: Any) -> bool:
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def truthy(v: Any) -> bool:
+    if v is None or v is False or v is UNDEFINED:
+        return False
+    if is_num(v):
+        return v == v and v != 0
+    if isinstance(v, str):
+        return v != ""
+    return True  # objects and arrays, even empty ones
+
+
+def is_integer(v: Any) -> bool:
+    """Number.isInteger — 42.0 from JSON counts, exactly as JSON.parse("42.0") === 42 in JS."""
+    if not is_num(v):
+        return False
+    return isinstance(v, int) or (math.isfinite(v) and float(v).is_integer())
+
+
+def is_safe_integer(v: Any) -> bool:
+    return is_integer(v) and abs(v) <= MAX_SAFE_INTEGER
+
+
+def strict_eq(a: Any, b: Any) -> bool:
+    """`===` for JSON values: same kind and equal; objects by identity."""
+    if is_num(a) and is_num(b):
+        return a == b
+    if isinstance(a, str) and isinstance(b, str):
+        return a == b
+    if isinstance(a, bool) and isinstance(b, bool):
+        return a == b
+    return a is b
+
+
+def trim(s: str) -> str:
+    return _TRIM.sub("", s)
+
+
+# ── numbers ───────────────────────────────────────────────────────────────────────────────────────────────────────────
+_DEC = re.compile(r"[+-]?(?:Infinity|(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)")
+
+
+def _string_to_number(s: str) -> float:
+    t = trim(s)
+    if t == "":
+        return 0
+    if _DEC.fullmatch(t):
+        return float(t.replace("Infinity", "inf"))
+    for prefix, base, digits in (("0x", 16, "[0-9a-fA-F]"), ("0o", 8, "[0-7]"), ("0b", 2, "[01]")):
+        if re.fullmatch(f"0[{prefix[1]}{prefix[1].upper()}]{digits}+", t):
+            return float(int(t[2:], base))
+    return math.nan
+
+
+def to_number(v: Any) -> float:
+    """Unary `+v`."""
+    if v is UNDEFINED:
+        return math.nan
+    if v is None or v is False:
+        return 0
+    if v is True:
+        return 1
+    if is_num(v):
+        return v
+    if isinstance(v, str):
+        return _string_to_number(v)
+    if isinstance(v, (list, tuple)):
+        return _string_to_number(js_string(v))
+    return math.nan
+
+
+def number_str(x: float) -> str:
+    """Number.prototype.toString() — shortest round-trip digits, JS exponent rules."""
+    if isinstance(x, int) and abs(x) <= MAX_SAFE_INTEGER:
+        return str(x)
+    x = float(x)
+    if x != x:
+        return "NaN"
+    if math.isinf(x):
+        return "Infinity" if x > 0 else "-Infinity"
+    if x == 0:
+        return "0"
+    sign = "-" if x < 0 else ""
+    d = decimal.Decimal(repr(abs(x))).normalize()
+    _, digits, exp = d.as_tuple()
+    s = "".join(map(str, digits))
+    k, n = len(s), len(s) + exp
+    if k <= n <= 21:
+        return sign + s + "0" * (n - k)
+    if 0 < n <= 21:
+        return sign + s[:n] + "." + s[n:]
+    if -6 < n <= 0:
+        return sign + "0." + "0" * (-n) + s
+    e = n - 1
+    mant = s if k == 1 else s[0] + "." + s[1:]
+    return f"{sign}{mant}e{'+' if e >= 0 else '-'}{abs(e)}"
+
+
+def js_string(v: Any) -> str:
+    """String(v)."""
+    if v is UNDEFINED:
+        return "undefined"
+    if v is None:
+        return "null"
+    if v is True:
+        return "true"
+    if v is False:
+        return "false"
+    if is_num(v):
+        return number_str(v)
+    if isinstance(v, str):
+        return v
+    if isinstance(v, (list, tuple)):
+        return ",".join("" if e is None or e is UNDEFINED else js_string(e) for e in v)
+    return "[object Object]"
+
+
+def clean_number(v: float) -> float:
+    """A computed number as JS would hold it for JSON: integral floats become ints (so they print as 5, not 5.0)."""
+    if isinstance(v, float) and math.isfinite(v) and v.is_integer() and abs(v) <= MAX_SAFE_INTEGER:
+        return int(v)
+    return v
+
+
+# ── UTF-16 ────────────────────────────────────────────────────────────────────────────────────────────────────────────
+def utf16_len(s: str) -> int:
+    return len(s.encode("utf-16-le", "surrogatepass")) // 2
+
+
+def utf16_slice(s: str, start: int, end: int | None = None) -> str:
+    b = s.encode("utf-16-le", "surrogatepass")
+    return b[2 * start : None if end is None else 2 * end].decode("utf-16-le", "surrogatepass")
+
+
+def utf16_join(parts) -> str:
+    """''.join, then fuse surrogate halves that a UTF-16 slice split — JS strings do this implicitly."""
+    s = "".join(parts)
+    if not _SURROGATE.search(s):
+        return s
+    return s.encode("utf-16-le", "surrogatepass").decode("utf-16-le", "surrogatepass")
+
+
+_SURROGATE = re.compile("[\ud800-\udfff]")
+
+
+def utf8(s: str) -> bytes:
+    """A JS string as UTF-8 the way fetch/TextEncoder send it: pairs fused, a lone surrogate becomes U+FFFD."""
+    return _SURROGATE.sub("\ufffd", utf16_join([s])).encode("utf-8")
+
+# ── JSON ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
+_ESCAPES = {'"': '\\"', "\\": "\\\\", "\b": "\\b", "\f": "\\f", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+_NEEDS_ESCAPE = re.compile('["\\\\\x00-\x1f\ud800-\udfff]')
+_INDEX_KEY = re.compile(r"0|[1-9]\d*")
+
+
+def _quote(s: str) -> str:
+    if _SURROGATE.search(s):
+        s = utf16_join([s])  # a pair held as two code points is one character to JS
+    return '"' + _NEEDS_ESCAPE.sub(lambda m: _ESCAPES.get(m.group(0)) or "\\u%04x" % ord(m.group(0)), s) + '"'
+
+
+def _ordered_keys(d: dict) -> list:
+    keys = [k if isinstance(k, str) else js_string(k) for k in d]
+    idx = sorted((k for k in keys if _INDEX_KEY.fullmatch(k) and int(k) < 2**32 - 1), key=int)
+    idx_set = set(idx)
+    return idx + [k for k in keys if k not in idx_set]
+
+
+def stringify(v: Any, indent: int | None = None) -> str:
+    """JSON.stringify(v, null, indent) for JSON-shaped values."""
+    gap = " " * indent if indent else ""
+
+    def ser(x: Any, cur: str) -> str | None:
+        if x is None:
+            return "null"
+        if x is True:
+            return "true"
+        if x is False:
+            return "false"
+        if x is UNDEFINED:
+            return None
+        if is_num(x):
+            return number_str(x) if math.isfinite(x) else "null"
+        if isinstance(x, str):
+            return _quote(x)
+        inner = cur + gap
+        if isinstance(x, (list, tuple)):
+            items = [ser(e, inner) or "null" for e in x]
+            if not items:
+                return "[]"
+            if not gap:
+                return "[" + ",".join(items) + "]"
+            return "[\n" + inner + (",\n" + inner).join(items) + "\n" + cur + "]"
+        if isinstance(x, dict):
+            src = {(k if isinstance(k, str) else js_string(k)): val for k, val in x.items()}
+            members = []
+            for k in _ordered_keys(src):
+                sv = ser(src[k], inner)
+                if sv is not None:
+                    members.append(_quote(k) + (": " if gap else ":") + sv)
+            if not members:
+                return "{}"
+            if not gap:
+                return "{" + ",".join(members) + "}"
+            return "{\n" + inner + (",\n" + inner).join(members) + "\n" + cur + "}"
+        raise TypeError(f"not JSON-serializable: {type(x).__name__}")
+
+    out = ser(v, "")
+    if out is None:
+        raise TypeError("undefined is not JSON")
+    return out
+
+
+def _no_constants(name: str):
+    raise ValueError(f"{name} is not JSON")
+
+
+def parse(text: str) -> Any:
+    """JSON.parse — refuses NaN/Infinity, which Python's json would otherwise accept."""
+    return json.loads(text, parse_constant=_no_constants)
+
+
+def json_bytes(v: Any) -> float:
+    """UTF-8 size of JSON.stringify(v ?? null) — Infinity when it cannot be serialized (compress.js _jsonBytes)."""
+    try:
+        return len(stringify(None if v is UNDEFINED else v).encode("utf-8"))
+    except (TypeError, ValueError, RecursionError):
+        return math.inf
+
+
+# ── base64 ────────────────────────────────────────────────────────────────────────────────────────────────────────────
+_B64_BAD = re.compile(r"[^A-Za-z0-9+/]")
+
+
+def atob(s: str) -> bytes:
+    """WHATWG forgiving-base64 decode (what `atob` accepts). Raises ValueError where atob throws."""
+    t = re.sub(r"[\t\n\x0c\r ]", "", s)
+    if len(t) % 4 == 0:
+        if t.endswith("=="):
+            t = t[:-2]
+        elif t.endswith("="):
+            t = t[:-1]
+    if len(t) % 4 == 1 or _B64_BAD.search(t):
+        raise ValueError("invalid base64")
+    return base64.b64decode(t + "=" * (-len(t) % 4))
+
+
+def btoa(b: bytes) -> str:
+    return base64.b64encode(b).decode("ascii")
+
+
+def b64u(b: bytes) -> str:
+    """base64url, unpadded (every B64/b64u/b64url helper on the JS side)."""
+    return base64.urlsafe_b64encode(b).rstrip(b"=").decode("ascii")
+
+
+def unb64u_loose(s: Any) -> bytes:
+    """deviceLink UNB64 / recovery fromB64url: url alphabet mapped back, then atob (no padding added)."""
+    return atob(js_string(s).replace("-", "+").replace("_", "/"))