ps-access 0.0.1

package/PROTOCOL.md

@@ -0,0 +1,210 @@
+# PlayStation Access Controller — profile protocol
+
+Protocol for reading and writing the Access Controller's on-device profiles over **USB-C**, with
+**no PS5**. Verified end-to-end against real hardware (read, write, round-trip, restore) on macOS
+via both node-hid and WebHID.
+
+Credit: this work builds on the prior art of Jacek Fedoryński's client-side web editor
+(<https://www.jfedor.org/ps-access/>), which first made PC-side profile editing possible. The
+byte offsets and behaviour documented here were confirmed against a live device, and this note
+records where this implementation differs (it preserves the UUID/timestamp/stick-tuning bytes on
+round-trip).
+
+## Device identity
+
+| | value |
+|---|---|
+| Vendor ID | `0x054C` (Sony Interactive Entertainment) |
+| Product ID | `0x0E5F` |
+| USB usage | Generic Desktop (`0x01`) / Game Pad (`0x05`) |
+| Product string | `Access Controller` |
+
+Note `0x0E5F` is absent from public USB-ID databases.
+
+## Transport: feature reports
+
+Two HID **feature reports** carry profile data, and are present **only over USB**:
+
+- `0x60` (96) — host → device command/data channel
+- `0x61` (97) — device → host data/status channel
+
+Each `0x60` packet is **63 payload bytes** (after the report id). Each `0x61` response is the
+full report with the **report id at byte 0**.
+
+**USB vs Bluetooth detection:** over USB the feature-report set includes `0x60` and `0x61`
+and does **not** include report `99` (`0x63`). Over Bluetooth, report `99` is present and the
+profile channel is not usable. So: *USB-ready ⇔ has `0x60` & `0x61` and not `99`.*
+
+A profile blob is **956 bytes** (`PROFILE_DATA_SIZE`). There are **3 profile slots** (1–3).
+
+### Reading profile N (1–3)
+
+1. Send feature report `0x60` with a 63-byte buffer where `buf[0] = 0x10 + (N-1)` (rest 0).
+2. Read feature report `0x61` **18 times**. In each response, payload bytes are at **offset 4**
+   (`[0]=0x61, [1]=cmd echo, [2]=remaining-count, [3]=?, [4..59]=56 payload bytes`).
+3. Concatenate `18 × 56 = 1008` bytes and keep the first **956**. Byte 0 must be `0x02`.
+
+### Writing profile N (1–3)
+
+1. Build 18 packets. Packet `i` (0–17), 63 bytes:
+   - `buf[0] = 0x08 + N`
+   - `buf[1] = i`
+   - `buf[2 + j] = profile[i*56 + j]` for `j` in 0..55 while `i*56+j < 956`
+2. On the **final** packet (`i == 17`), write `crc32(profile, 956)` as **little-endian u32** at
+   **offset 6** (the real profile data only occupies offsets 2–5 of the last packet, so there
+   is no overlap).
+3. Send all 18 packets via feature report `0x60`, in order.
+4. **Drain status:** read feature report `0x61` until byte `[2]` (remaining-count) is `0`
+   (cap the loop). Skipping this desyncs the next read command.
+
+### Setting the active profile (1–3)
+
+Switch which profile the controller has **active** — the same thing its on-device profile
+button does — with a single command:
+
+1. Send feature report `0x60` with a 63-byte buffer where `buf[0] = 0x05`, `buf[1] = N` (rest 0).
+
+No `0x61` response needs draining. The switch is immediate: input-report `byte 39` (see below)
+updates to `N` within a frame, and the controller applies that profile's mapping. Verified by
+sending `0x05 0x01/0x02/0x03` and watching `byte 39` track `1/2/3`; the stored slot contents are
+untouched. Reverse-engineered by probing command opcodes while watching `byte 39` — opcode `0x05`
+with `byte[1] = 0` set `byte 39` to `0` (no/default profile), which pinned the encoding. Implemented
+as `buildSetActiveCommand(N)`.
+
+### CRC
+
+Standard zlib/IEEE CRC-32 (poly `0xEDB88320`, init `0xFFFFFFFF`, final XOR `0xFFFFFFFF`),
+computed over the **956 profile bytes** and stored little-endian. Implemented in
+`lib/access-protocol.mjs` (`crc32`).
+
+## Profile blob layout (956 bytes)
+
+| offset | size | field |
+|---|---|---|
+| 0 | 1 | sentinel, always `0x02` |
+| 4 | 2×40 | profile name, UTF-16LE, NUL-terminated, ≤40 chars |
+| 84 | 16 | UUID (random; PS5/editor regenerate it each save) |
+| 100 | 10×5 | button table — see below |
+| 150 | 2 | toggle bitfield (u16 LE) — see below |
+| 152 | 5×45 | expansion-port records — see below |
+| 948 | 8 | timestamp, i64 LE (`Date.now()` ms) |
+
+### Buttons (offset 100, 10 entries × 5 bytes)
+
+Entry `b` (0–9) at `100 + b*5`:
+
+- byte 0 — primary action (`map1`)
+- byte 1 — secondary action (`map2`, for combos)
+- bytes 2–4 — unused/observed 0
+
+Action codes:
+
+```
+0 nothing   1 circle   2 cross   3 triangle  4 square
+5 up        6 down     7 left    8 right
+9 L1       10 R1      11 L2     12 R2       13 L3   14 R3
+15 options 16 create  17 PS     18 touchpad
+```
+
+### Toggle bitfield (offset 150, u16 LE)
+
+- bit `b` (0–9) → toggle enabled for button `b+1`
+- bit `9 + p` → toggle enabled for expansion port `p` configured as a button
+  (the built-in stick is port 0 and is normally a stick, so its bit is not used as a toggle)
+
+### Expansion ports (offset 152, 5 entries × 45 bytes)
+
+Port 0 = built-in stick; ports 1–4 = the four 3.5mm expansion ports. Entry `p` at
+`152 + p*45`, byte 0 = **type**:
+
+- `0x00` — disabled / nothing
+- `0x01` — **stick**
+  - byte 1: stick assignment (`1` = left stick, `2` = right stick)
+  - byte 2: orientation (`0` below, `1` right, `2` above, `3` left) — only the built-in
+    stick is affected, but every stick port carries the same value
+  - byte 5: sensitivity; bytes 8–13: deadzone/curve (3 pairs, X/Y).
+    **`0` means "firmware default"** — observed on a live, never-PS5-tuned device, all these
+    bytes are `0`. The PS5 only writes non-zero when you change them from default; jfedor's
+    editor writes `sensitivity=3` and deadzone `80 80 c4 c4 e1 e1` as its "default" preset.
+    The exact value→behaviour mapping is **not publicly documented** (set them experimentally).
+- `0x02` — **analog** button; `0x03` — **digital** button
+  - byte 2: primary action (`map1`); byte 3: secondary action (`map2`)
+
+A port’s stick assignment is encoded in the UI as `100 + code` (101 = left stick,
+102 = right stick) to share one dropdown with the button actions.
+
+## Input report — live button & stick state (report id `0x01`)
+
+The controller streams a DualSense-style **input report** (report id `1`, ~250 Hz, 64 bytes
+incl. report id / 63 bytes of data). The left stick is at the front and a sequence counter ticks
+at byte 6; the last 8 bytes (55–62) are a volatile per-frame trailer (see *Unexposed* below).
+Reverse-engineered with `web/hid-capture.html` (connect → idle baseline → press one button at a
+time, watch which bits flip).
+
+**Key finding:** the report exposes **raw physical button state — independent of the profile
+remapping.** Pressing a button lights a fixed physical bit even when that button is mapped to
+*Not assigned*. (The standard DualSense face/shoulder bits near bytes 7–8 instead carry the
+*mapped action*, so two buttons mapped to the same action are indistinguishable there.)
+
+Byte offsets below are in **`event.data` coordinates** (WebHID `inputreport`, which **excludes**
+the report id). For `node-hid`, whose buffer includes the id at `[0]`, add 1.
+
+| data byte | bits | meaning |
+|---|---|---|
+| 0–1 | — | left stick X / Y (≈`0x80` centered; byte 0 jitters) |
+| 6 | — | sequence counter (increments once per report) |
+| ~7–8 | — | standard mapped-action bits (reflect the *mapped* action, not the physical button) |
+| **15** | **0–7** | **the 8 perimeter buttons** — one bit each (physical) |
+| **16** | **0, 1, 3** | **center button** (bit 0), **stick-click** (bit 1), **profile-switch button** (bit 3, `0x08`) |
+| **39** | — | **active on-device profile** — `1`, `2`, or `3` (which profile the controller has selected) |
+
+Pinned via an ordered capture: **perimeter button _n_ (1–8) → `byte 15` bit _(n−1)_**
+(bit 0 = button 1 … bit 7 = button 8); **`byte 16` bit 0 = center button**; **`byte 16` bit 1 =
+stick-click**. So all 10 physical inputs are readable directly from `byte 15` (bits 0–7) and
+`byte 16` (bits 0–1).
+
+**Active profile.** `byte 39` holds the profile the controller currently has active (`1`–`3`),
+and `byte 16` bit 3 (`0x08`) pulses while the on-device **profile-switch button** is held. This
+lets a PC-side tool show, and react to, which profile the user has selected on the controller —
+without a PS5. Found by capturing the report while cycling the profile button: `byte 39` stepped
+`3 → 1 → 2 → 3` in lockstep with each press, while all other low-cardinality bytes stayed put.
+
+This enables physical-button features regardless of mapping — e.g. navigating a UI with the
+controller (perimeter = back, center/stick-click = confirm) and lighting only the button
+actually pressed. Note: WebHID `inputreport` and the browser **Gamepad API** can't both read the
+device reliably at once, and the Gamepad API only sees mapped actions — so physical-button work
+must go through the raw input report.
+
+### What the controller does *not* expose (verified)
+
+A round of probing (capture + correlation against the DualSense layout) ruled these out, which is
+useful to know before chasing them:
+
+- **No analog/pressure on the buttons.** The 8 perimeter buttons, center, and stick-click are
+  **digital only**. Holding a button harder changes nothing — the only bytes that react are the
+  physical bits (`byte 15`/`byte 16`) and the mapped-action bits (`bytes 7–8`), and all of those
+  are flat on/off. (The profile's "analog" button type `0x02` is for **expansion-port** inputs —
+  analog sticks/triggers in the 3.5 mm AUX jacks — not the built-in buttons.)
+- **No motion/IMU and no battery.** The gyro/accel region a DualSense fills with sensor noise is
+  constant/zero here (the device is meant to sit flat), and the DualSense battery byte reads `0`
+  (USB-powered, no battery to report).
+- **Bytes 55–62 are an opaque 8-byte trailer.** They randomize every frame even when the rest of
+  the payload is static, the values are not a forward timestamp, and they do **not** match a
+  standard DualSense CRC-32 (seed `0xA1` over the payload). Most likely a device timestamp and/or
+  signature over hidden internal state — not a decodable field.
+- **The profile light is firmware-controlled.** The device accepts output report `0x02` (31 data
+  bytes) without error but ignores it for lighting — the profile-button glow and its idle "wave"
+  animation are driven by firmware, not host-settable. (The standard DualSense player-LED/lightbar
+  bytes sit at offsets ~43–46, beyond this device's 31-byte output report, so the usual path
+  doesn't apply.)
+- **The profile blob has no hidden fields.** Every non-zero byte in the 956-byte profile falls
+  inside a documented field; the rest is reserved/zero.
+
+## Implementation notes
+
+- `buildProfile()` starts from the previously-read raw bytes when available, so fields this
+  tool doesn’t model (UUID, stick sensitivity/deadzone) survive a round trip. jfedor’s editor
+  instead rebuilds from scratch, randomizing the UUID and resetting stick tuning to defaults.
+- A naive read **immediately after** a write returns zeros — always drain `0x61` first.
+- `node-hid` `getFeatureReport(id, len)` and WebHID `receiveFeatureReport(id)` both return the
+  report id at byte 0, so the payload offset (4 on read) is identical across platforms.

package/README.md

@@ -0,0 +1,203 @@
+# ps-access
+
+Read and write **PlayStation Access Controller** profiles from a PC over **USB-C — no PS5
+required**. Includes a command-line tool and a multi-controller browser (WebHID) configurator,
+plus a documented protocol.
+
+The Access Controller normally can only be customized by plugging it into a PS5. This project
+talks the same on-device profile protocol directly, so you can read, edit, back up, restore,
+and clone the 3 on-device profiles (button remapping, the built-in stick, expansion ports)
+yourself.
+
+> Verified end-to-end against real hardware (read / write / round-trip / restore) on macOS.
+> See [PROTOCOL.md](PROTOCOL.md) for the protocol. This project builds on the prior art of
+> Jacek Fedoryński’s web editor (<https://www.jfedor.org/ps-access/>) — credit and thanks to him
+> for first making PC-side profile editing possible.
+
+## Requirements
+
+- The controller connected by **USB-C** (the profile channel isn’t available over Bluetooth).
+- CLI: Node.js (tested on v26) with `node-hid` (`npm install`).
+- Web tool: Chrome or Edge (desktop) for WebHID.
+- macOS may prompt for **Input Monitoring** permission for the terminal/Chrome on first use.
+
+## CLI
+
+```bash
+npm install
+
+node cli.mjs list                       # list connected controllers
+node cli.mjs dump                        # decode all 3 profiles
+node cli.mjs backup                      # save all 3 profiles to captures/
+node cli.mjs read-profile 1 --json       # decode one profile as JSON
+node cli.mjs set-active 2                 # switch the active profile (like the profile button)
+node cli.mjs set 1 button5=triangle      # remap button 5
+node cli.mjs set 1 port1=cross           # expansion port 1 -> cross
+node cli.mjs set 1 "port0=left stick"    # built-in stick assignment
+node cli.mjs set 1 orientation="stick on the right"
+node cli.mjs write-profile 2 captures/backup-....json
+node cli.mjs restore captures/backup-....json
+node cli.mjs apply profile.json 1        # apply a web-app export / share code / URL / preset id to a slot
+```
+
+`apply` is the bridge between the web tool and the CLI: feed it a **profile JSON exported from the
+web Library**, a **share link/code**, or a built-in **preset id** (`ps-access presets`), and it
+writes that mapping to a slot on the controller (reading the current profile first so uuid and
+unmodeled fields survive, then round-trip verifying).
+
+- `--device <index|path>` targets a specific controller when several are connected.
+- **Every write auto-backs-up first** to `captures/` and round-trip re-reads to verify.
+
+## Web tool (multiple controllers)
+
+```bash
+npm start            # serves the project at http://localhost:3000
+```
+
+Open **<http://localhost:3000/web/>** in Chrome/Edge.
+
+### XMB view (`index.html`)
+
+A full-screen XrossMediaBar-style interface: a horizontal ribbon of blades
+(`Controllers · Profile 1 · 2 · 3 · Save · Library · Key Bridge · Monitor`, each profile rendered
+as a live mini-controller), a vertical item list, and an enlarged "hero" render when you drill in.
+Edit button/stick/port mappings with horizontal value spinners, then save to the controller.
+
+The **Library** blade is for **sharing and presets** (all client-side, no account): apply a
+curated starting-point preset (one-handed, toggle-triggers, external-switch D-pad…), **export**
+a profile to a JSON file, **import** a file or a CLI backup, or **copy a share link** — a URL
+whose `#p=…` hash encodes the profile, auto-detected when someone opens it. After applying or
+importing, use **Save** to write it to the controller.
+
+The **Key Bridge** blade is a visual editor for the PC input bridge: assign **any keyboard key
+or chord** to each physical button and the stick by selecting a row, pressing Enter, then pressing
+the key you want (press the physical button to find its row — it lights up live). Pick a stick
+mode (keys / mouse / gamepad axis), then **Export** a `bridge.json` or **copy the run command**.
+The browser can author and preview the mapping, but it can't inject input into other apps — you
+run the exported config with the local bridge (`node bridge.mjs --config bridge.json`), which is
+what actually drives the PC. (Macros — multi-step sequences — are edited in the exported JSON.)
+
+**Accessibility:** the configurator is built to be used by the same people the controller is for.
+Every section/option/value change is announced to screen readers (a polite live region), it's
+fully keyboard- and controller-operable, **?** opens a controls reference, and it honors
+`prefers-reduced-motion` (no animated wave), `prefers-contrast`, and Windows High Contrast /
+`forced-colors`. A high-visibility focus ring on the selected item is available as an **opt-in
+toggle in Help (off by default**, so it doesn't fight the XMB look); OS high-contrast / forced-colors
+modes turn it on automatically.
+
+It's driven by the controller's **raw HID input report**, so it reads *physical* buttons
+regardless of remapping: tilt the **stick** to navigate, **center / stick-click = confirm**,
+**any perimeter button = back**, and pressing any physical button lights it up on every render.
+Keyboard works too (arrows / Enter / Backspace).
+
+Unplugging and replugging the controller **reconnects automatically** (no refresh). The
+**Controllers** blade also has a persistent **＋ Connect a controller…** action (activate it with
+Enter or a click) to grant or reconnect a controller on demand.
+
+Under the controller name in the top bar, the **active on-device profile** is shown live (e.g.
+`Profile 3 · stick on the right`) — it reflects whichever profile is selected on the controller
+itself and **updates the moment you press the device's profile button**, independent of the UI
+cursor (decoded from input-report `byte 39`; see [PROTOCOL.md](PROTOCOL.md)). You can also **switch
+it from the app**: each Profile blade has a **Set active on controller** item (the active one is
+marked `✓`), doing the same thing as the device's profile button — `set-active` on the CLI. The ambient
+background wave echoes it too: its three curves fade their leading lines as the active profile
+climbs (1 → all solid, 2 → first faded, 3 → first two faded), and fade out entirely when no
+controller is connected.
+
+The **Monitor** blade opens a full-screen live input view (big controller render + physical-button
+chips + stick crosshair + the raw input report with the physical-button bytes highlighted). Because
+the controller is purely *observed* here — navigation is suspended so every button and the stick can
+be tested freely — opening it first shows a **confirm gate** warning that you'll need the **keyboard
+(Esc)** or the **Done** button to leave (the controller can't exit on its own). The render follows
+the **active on-device profile**, matching its **orientation**, and re-renders if you switch
+profiles on the controller while watching. (Also available as a standalone page, `monitor.html`.)
+
+### Diagnostics (`hid-capture.html`)
+
+A developer tool that shows the live input report and logs which bits flip on each press —
+used to reverse-engineer the physical-button layout (see PROTOCOL.md).
+
+## PC input bridge (use the controller on any PC)
+
+Beyond editing PS5 profiles, you can use the Access Controller as a **general PC input device** —
+its stick and buttons driving keyboard/mouse or a virtual gamepad, so it controls *any* software,
+not just a PS5. The bridge reads the controller's live USB input and maps it through a small,
+platform-agnostic engine (`web/bridge-core.mjs`) to a pluggable output **sink**.
+
+```bash
+node bridge.mjs --sink dry-run               # print mapped events, inject nothing (try it first)
+node bridge.mjs --sink xdotool               # stick -> arrow keys, buttons -> keys (X11; needs xdotool)
+node bridge.mjs --sink uinput                # virtual gamepad/keyboard via /dev/uinput (Linux)
+node bridge.mjs --config my-map.json         # custom mapping (see DEFAULT_MAPPING in bridge-core)
+node bridge.mjs --simulate frames.json --sink dry-run   # replay recorded frames, no hardware
+```
+
+- **xdotool** sink (X11): no native deps; set `--display :0` if `$DISPLAY` isn't set.
+- **uinput** sink (Linux, lowest latency): a stdlib-only Python helper creates the virtual device.
+  It needs access to `/dev/uinput` — run as root, or add a udev rule, e.g.:
+  ```
+  # /etc/udev/rules.d/99-uinput.rules
+  KERNEL=="uinput", GROUP="input", MODE="0660"   # then: add your user to the `input` group
+  ```
+- Mapping config example (`my-map.json`):
+  ```json
+  { "buttons": {
+      "8": "space",
+      "0": "mouse1",
+      "1": "ctrl+s",
+      "2": ["ctrl+c", "ctrl+v"]
+    },
+    "stick": { "mode": "mouse" }, "mouse": { "speed": 22 } }
+  ```
+  `stick.mode` is `keys` (arrows/WASD), `mouse` (relative pointer), or `axis` (gamepad).
+- A button value can be:
+  - a single key — **held** while the button is held (`"space"`, `"a"`, `"mouse1"`);
+  - a **chord** — `"ctrl+s"` — fired once on press (modifiers held around the key);
+  - a **macro** — `["ctrl+c", "ctrl+v"]` or `["g", "i"]` — a sequence fired once on press.
+
+  Chords and macros make a single accessible switch trigger a complex action that would
+  otherwise need several simultaneous or sequential presses.
+
+### Building a mapping
+
+Author the config visually in the web **Key Bridge** blade, or from the terminal:
+
+```bash
+node bridge.mjs edit                         # interactive press-to-bind editor (TTY)
+node bridge.mjs edit --config my-map.json --out my-map.json
+node bridge.mjs set 0=ctrl+s 8=space 2=ctrl+c,ctrl+v stick.mode=mouse --out my-map.json
+node bridge.mjs show --config my-map.json    # print the resolved config
+```
+
+- **edit** is the CLI twin of the web editor: ↑/↓ to select a button/stick row, **Enter** to
+  bind (then press the key you want), **Del** to clear, **s** to save, **q** to quit.
+- **set** targets: `0`..`9` (buttons), `stick.mode`, `stick.up/down/left/right`, `mouse.speed`;
+  a comma-separated value (`2=ctrl+c,ctrl+v`) becomes a macro. These commands need no controller.
+
+> Verified with simulated input on Linux; on-hardware verification is pending a physical unit.
+
+## Layout
+
+```
+web/access-protocol.mjs   shared, I/O-free protocol (parse/build/CRC/enums) — used by both tools
+web/profile-library.mjs   shared, I/O-free profile sharing + preset library (used by the web tool)
+lib/hid-node.mjs          node-hid transport (Node CLI only)
+web/bridge-core.mjs       PC bridge: pure input->output mapping engine
+lib/bridge-sinks.mjs      PC bridge: output sinks (dry-run, xdotool, uinput)
+lib/uinput-helper.py      PC bridge: stdlib-only virtual device for the uinput sink
+cli.mjs                   command-line tool (profiles)
+bridge.mjs                command-line PC input bridge
+web/index.html + xmb.js   XMB-style configurator (the web UI) + Library + live Monitor, via hid-web.mjs
+web/controller-render.mjs shared controller SVG render + physical-input decode
+web/monitor.html + monitor.js  standalone XMB-styled live input monitor
+web/hid-capture.html      input-report diagnostics / RE tool
+captures/                 profile backups (created on backup/auto-backup)
+reference/                Jacek Fedoryński’s original web editor — third-party, see reference/NOTICE.md
+PROTOCOL.md               protocol documentation
+```
+
+## Safety
+
+Profiles live in 3 on-device slots and are fully recoverable: take a `backup` first, and note
+that writes auto-back-up. Connecting the controller to a PS5 will overwrite these profiles with
+the console’s copies.

package/bridge.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// ps-access bridge — use the PlayStation Access Controller as a PC input device.
+//
+// Reads the controller's live input over USB and maps it to keyboard/mouse (xdotool)
+// or a virtual gamepad (uinput) so it can drive ANY PC software, not just a PS5.
+//
+//   node bridge.mjs --sink xdotool                 # stick -> arrows, buttons -> keys (X11)
+//   node bridge.mjs --sink uinput                  # virtual gamepad (needs /dev/uinput)
+//   node bridge.mjs --sink dry-run                 # print events, inject nothing
+//   node bridge.mjs --config my-map.json           # custom mapping
+//   node bridge.mjs --simulate frames.json --sink dry-run   # replay (no hardware)
+//
+import { readFileSync, writeFileSync } from "node:fs";
+import readline from "node:readline";
+import { BridgeEngine, decodeInput, DEFAULT_MAPPING } from "./web/bridge-core.mjs";
+import {
+  PHYS_LABELS, STICK_MODES, STICK_DIRS, defaultBridgeMap, displayValue, toConfigJSON, keypressToValue,
+} from "./web/bridge-map.mjs";
+import { makeSink } from "./lib/bridge-sinks.mjs";
+
+// Don't crash if our output is piped into something that closes early (e.g. `| head`).
+process.stdout.on("error", (e) => { if (e.code === "EPIPE") process.exit(0); });
+
+function parseArgs(argv) {
+  const o = { sink: "dry-run", rate: 60, _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--sink") o.sink = argv[++i];
+    else if (a === "--config") o.config = argv[++i];
+    else if (a === "--simulate") o.simulate = argv[++i];
+    else if (a === "--device" || a === "-d") o.device = argv[++i];
+    else if (a === "--display") o.display = argv[++i];
+    else if (a === "--rate") o.rate = Number(argv[++i]);
+    else if (a === "--out" || a === "-o") o.out = argv[++i];
+    else if (a === "--help" || a === "-h") o.help = true;
+    else o._.push(a);
+  }
+  return o;
+}
+
+function loadMapping(file) {
+  if (!file) return DEFAULT_MAPPING;
+  const m = JSON.parse(readFileSync(file, "utf8"));
+  return m.mapping || m; // accept {mapping:{...}} or a bare mapping
+}
+
+const HELP = `ps-access bridge — drive a PC with the Access Controller (USB-C)
+
+Usage:
+  node bridge.mjs [--sink <name>] [options]     run the bridge (live or --simulate)
+  node bridge.mjs edit [--config f] [--out f]   interactive press-to-bind key editor
+  node bridge.mjs set <target=value>... [--out f]   set mappings non-interactively
+  node bridge.mjs show [--config f]             print the resolved config JSON
+
+edit/set targets: 0..9 (buttons), stick.mode, stick.up/down/left/right, mouse.speed
+  e.g.  node bridge.mjs set 0=ctrl+s 8=space 2=ctrl+c,ctrl+v stick.mode=mouse --out my-map.json
+
+Sinks:
+  dry-run        Print events only (default; no OS input)
+  xdotool        Keyboard + mouse via xdotool (X11)
+  uinput         Virtual gamepad/keyboard via /dev/uinput (Linux; needs access)
+
+Options:
+  --config <file>     JSON mapping (see DEFAULT_MAPPING in web/bridge-core.mjs)
+  --simulate <file>   Replay recorded input frames instead of reading hardware
+  --device <i|path>   Select controller (default 0)
+  --display <:N>      X display for xdotool (default $DISPLAY or :0)
+  --rate <hz>         Simulate playback rate (default 60)
+  -h, --help          This help
+
+Mapping config example (my-map.json):
+  { "buttons": { "8": "space", "0": "mouse1" },
+    "stick": { "mode": "mouse" }, "mouse": { "speed": 22 } }`;
+
+async function runSimulate(opts, engine, sink) {
+  // Frames file: JSON array of byte arrays (report id already stripped), each one input report.
+  const frames = JSON.parse(readFileSync(opts.simulate, "utf8"));
+  const delay = Math.max(0, Math.round(1000 / (opts.rate || 60)));
+  console.log(`simulate: ${frames.length} frames -> ${opts.sink}`);
+  for (const f of frames) {
+    sink.apply(engine.update(decodeInput(Uint8Array.from(f))));
+    if (delay) await new Promise((r) => setTimeout(r, delay));
+  }
+  sink.apply(engine.releaseAll());
+}
+
+async function runLive(opts, engine, sink) {
+  let HID;
+  try { ({ HID } = await import("./lib/hid-node.mjs")); }
+  catch (e) { throw new Error("node-hid is required for live mode (run `npm install`). " + (e.message || e)); }
+  const { listControllers } = await import("./lib/hid-node.mjs");
+  const list = listControllers();
+  if (!list.length) throw new Error("No Access Controller connected (VID 054C / PID 0E5F). Connect it via USB-C.");
+  const sel = opts.device ?? 0;
+  const entry = (typeof sel === "string" && sel.startsWith("/")) ? list.find((d) => d.path === sel) : list[Number(sel)];
+  if (!entry) throw new Error(`No controller for --device ${sel}`);
+  const device = new HID.HID(entry.path);
+  console.log(`bridge: ${entry.product} [${entry.index}] -> ${opts.sink}.  Ctrl-C to stop.`);
+  device.on("data", (buf) => {
+    // node-hid prefixes the report id for numbered reports; the decoder expects it stripped.
+    const d = buf[0] === 0x01 ? buf.subarray(1) : buf;
+    try { sink.apply(engine.update(decodeInput(d))); } catch (e) { console.error("map error:", e.message); }
+  });
+  device.on("error", (e) => { console.error("device error:", e.message); shutdown(); });
+  function shutdown() {
+    try { sink.apply(engine.releaseAll()); sink.close(); device.close(); } catch { /* ignore */ }
+    process.exit(0);
+  }
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  await new Promise(() => {}); // run until signal
+}
+
+// ---- config editing (no controller / node-hid needed) ----
+
+// Load a saved config into a full editable map (fills unset buttons, merges stick/mouse).
+function loadEditMap(file) {
+  const base = defaultBridgeMap();
+  if (!file) return base;
+  try {
+    const j = JSON.parse(readFileSync(file, "utf8"));
+    const m = j.mapping || j;
+    if (m.buttons) for (const k of Object.keys(base.buttons)) if (m.buttons[k] != null) base.buttons[k] = m.buttons[k];
+    if (m.stick) base.stick = { ...base.stick, ...m.stick };
+    if (m.mouse) base.mouse = { ...base.mouse, ...m.mouse };
+  } catch { /* treat as a new file */ }
+  return base;
+}
+
+function applySet(map, target, value) {
+  const val = value.includes(",") ? value.split(",").map((s) => s.trim()) : value; // comma -> macro
+  if (/^\d+$/.test(target)) { map.buttons[target] = val; return; }                  // 0..9 -> button
+  if (target === "stick.mode") { map.stick.mode = value; return; }
+  if (target.startsWith("stick.")) { map.stick[target.slice(6)] = val; return; }
+  if (target.startsWith("mouse.")) { map.mouse[target.slice(6)] = isNaN(+value) ? value : +value; return; }
+  throw new Error(`unknown target "${target}" (use 0..9, stick.mode, stick.up.., mouse.speed)`);
+}
+
+function showConfig(opts) {
+  console.log(toConfigJSON(loadEditMap(opts.config)));
+}
+
+function setConfig(opts) {
+  const assigns = opts._.slice(1);
+  if (!assigns.length) throw new Error('usage: set <target=value>...  e.g. set 0=ctrl+s 8=space stick.mode=mouse');
+  const map = loadEditMap(opts.config);
+  for (const a of assigns) {
+    const m = a.match(/^([^=]+)=(.*)$/);
+    if (!m) throw new Error(`bad assignment "${a}" (want target=value)`);
+    applySet(map, m[1].trim(), m[2].trim());
+  }
+  const out = opts.out || opts.config || "ps-access-bridge.json";
+  writeFileSync(out, toConfigJSON(map));
+  console.log(`wrote ${out}\n`);
+  console.log(toConfigJSON(map));
+}
+
+// Interactive press-to-bind editor — the CLI twin of the web Key Bridge blade.
+function editConfig(opts) {
+  if (!process.stdin.isTTY) throw new Error("`edit` needs an interactive terminal — use `set`/`show` for scripting.");
+  const map = loadEditMap(opts.config);
+  const out = opts.out || opts.config || "ps-access-bridge.json";
+  let sel = 0, capturing = false, note = "";
+
+  const targets = () => {
+    const t = PHYS_LABELS.map((label, i) => ({ type: "button", i, label, get: () => map.buttons[i] }));
+    t.push({ type: "stickmode", label: "Stick mode", get: () => map.stick.mode });
+    if (map.stick.mode === "keys") for (const dir of STICK_DIRS) t.push({ type: "stick", dir, label: "Stick " + dir, get: () => map.stick[dir] });
+    return t;
+  };
+  const assign = (t, v) => { if (t.type === "button") map.buttons[t.i] = v; else if (t.type === "stick") map.stick[t.dir] = v; };
+  const render = () => {
+    const list = targets();
+    let s = "\x1b[2J\x1b[H\n  ps-access bridge — key editor\n";
+    s += "  ↑/↓ select · Enter bind (or cycle stick mode) · Del clear · s save · q quit\n\n";
+    list.forEach((t, idx) => { s += `  ${idx === sel ? "\x1b[36m▸" : " "} ${t.label.padEnd(13)} ${displayValue(t.get())}\x1b[0m\n`; });
+    s += capturing ? "\n  \x1b[33m▶ press a key to bind…  (Esc cancels)\x1b[0m\n" : `\n  saving to: ${out}${note ? "   " + note : ""}\n`;
+    process.stdout.write(s);
+  };
+
+  readline.emitKeypressEvents(process.stdin);
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  render();
+  return new Promise((resolve) => {
+    const quit = () => { process.stdin.setRawMode(false); process.stdin.pause(); process.stdout.write("\n"); resolve(); };
+    process.stdin.on("keypress", (_str, key) => {
+      const list = targets();
+      const t = list[Math.min(sel, list.length - 1)];
+      if (capturing) {
+        if (key.name === "escape") { capturing = false; note = "cancelled"; }
+        else if (key.name === "delete") { assign(t, "nothing"); capturing = false; writeFileSync(out, toConfigJSON(map)); note = "cleared + saved"; }
+        else { const v = keypressToValue(key); if (v) { assign(t, v); capturing = false; writeFileSync(out, toConfigJSON(map)); note = "bound + saved"; } else return; }
+        render(); return;
+      }
+      if (key.name === "up") { sel = Math.max(0, sel - 1); note = ""; render(); }
+      else if (key.name === "down") { sel = Math.min(list.length - 1, sel + 1); note = ""; render(); }
+      else if (key.name === "return") {
+        if (t.type === "stickmode") { map.stick.mode = STICK_MODES[(STICK_MODES.indexOf(map.stick.mode) + 1) % STICK_MODES.length]; writeFileSync(out, toConfigJSON(map)); note = "saved"; }
+        else { capturing = true; note = ""; }
+        render();
+      }
+      else if (key.name === "s") { writeFileSync(out, toConfigJSON(map)); note = "saved " + out; render(); }
+      else if (key.name === "q" || (key.ctrl && key.name === "c")) quit();
+    });
+  });
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) { console.log(HELP); return; }
+  const sub = opts._[0];
+  try {
+    if (sub === "edit") return await editConfig(opts);
+    if (sub === "set") return setConfig(opts);
+    if (sub === "show") return showConfig(opts);
+  } catch (e) { console.error("error:", e.message); process.exit(1); }
+
+  // default: run the bridge
+  const engine = new BridgeEngine(loadMapping(opts.config));
+  const sink = makeSink(opts.sink, { display: opts.display });
+  try {
+    if (opts.simulate) { await runSimulate(opts, engine, sink); sink.close(); }
+    else await runLive(opts, engine, sink);
+  } catch (e) {
+    console.error("error:", e.message);
+    try { sink.close(); } catch { /* ignore */ }
+    process.exit(1);
+  }
+}
+main();