ps-access 0.0.1

package/web/access-protocol.mjs

@@ -0,0 +1,310 @@
+// PlayStation Access Controller profile protocol.
+//
+// Pure, I/O-free. Works in Node and the browser (operates on Uint8Array / DataView).
+// Transcribed and verified against jfedor's web editor (https://www.jfedor.org/ps-access/),
+// credited in PROTOCOL.md. No PS5 required.
+
+// ---- Device identity ----
+export const VENDOR_ID = 0x054c; // Sony
+export const PRODUCT_ID = 0x0e5f; // Access Controller
+
+// ---- Feature reports / transport ----
+export const REPORT_ID_CMD = 0x60; // host -> device command channel
+export const REPORT_ID_DATA = 0x61; // device -> host data channel
+export const BT_ONLY_REPORT_ID = 99; // present only over Bluetooth; absent over USB (profile channel is USB-only)
+export const CMD_PAYLOAD_SIZE = 63; // bytes after the report id in a 0x60 packet
+export const PROFILE_SIZE = 956; // bytes of a single profile blob
+export const PROFILE_COUNT = 3; // on-device profile slots (1..3)
+const PACKET_COUNT = 18; // 18 * 56 = 1008 >= 956
+const CHUNK = 56; // payload bytes per packet
+const READ_PAYLOAD_OFFSET = 4; // payload offset within a 0x61 response (after report id + header)
+const WRITE_PAYLOAD_OFFSET = 2; // payload offset within a 0x60 write packet
+
+// ---- CRC-32 (standard zlib/IEEE, port of crc.js) ----
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+
+export function crc32(bytes, length = bytes.length) {
+  let c = 0xffffffff;
+  for (let n = 0; n < length; n++) c = CRC_TABLE[(c ^ bytes[n]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+// ---- Enum tables (from index.html dropdowns) ----
+// Button action codes (used for physical buttons and expansion-port-as-button).
+export const ACTIONS = {
+  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",
+};
+// Stick assignment for ports configured as a stick (stored value = code - 100).
+export const STICKS = { 1: "left stick", 2: "right stick" };
+// Built-in stick orientation.
+export const ORIENTATIONS = {
+  0: "stick below", 1: "stick on the right", 2: "stick above", 3: "stick on the left",
+};
+// Stick tuning. The device stores 0 for "firmware default"; these are the values jfedor's
+// editor writes as the PS5 "default" preset. Exact value semantics are not publicly
+// documented, so the UI exposes these as adjustable/experimental.
+export const STICK_DEFAULT_SENSITIVITY = 3;
+export const STICK_DEFAULT_DEADZONE = [0x80, 0x80, 0xc4, 0xc4, 0xe1, 0xe1];
+
+export const ACTION_BY_NAME = invert(ACTIONS);
+export const STICK_BY_NAME = invert(STICKS);
+export const ORIENTATION_BY_NAME = invert(ORIENTATIONS);
+function invert(o) {
+  const r = {};
+  for (const [k, v] of Object.entries(o)) r[v.toLowerCase()] = Number(k);
+  return r;
+}
+
+// ---- Profile layout offsets ----
+const OFF = {
+  sentinel: 0, // u8 == 0x02
+  name: 4, // UTF-16LE, up to 40 chars
+  uuid: 84, // 16 bytes
+  buttons: 100, // 10 * 5 bytes: [map1, map2, ...]
+  toggle: 150, // u16 LE bitfield: bits 0..9 buttons, bits 9+port ports
+  ports: 152, // 5 * 45 bytes
+  timestamp: 948, // i64 LE
+};
+const BUTTON_COUNT = 10;
+const BUTTON_STRIDE = 5;
+const PORT_COUNT = 5;
+const PORT_STRIDE = 45;
+const NAME_MAX = 40;
+
+// Decode a 956-byte profile blob into an editable object. Keeps the raw bytes so a
+// write can preserve fields we don't model (stick sensitivity/deadzone, uuid, etc.).
+export function parseProfile(bytes) {
+  const u8 = u8of(bytes);
+  if (u8.length < PROFILE_SIZE) throw new Error(`profile too short: ${u8.length}`);
+  const dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
+  if (dv.getUint8(OFF.sentinel) !== 0x02) {
+    throw new Error(`expected byte 0 == 0x02, got 0x${dv.getUint8(0).toString(16)}`);
+  }
+
+  let name = "";
+  for (let i = 0; i < NAME_MAX; i++) {
+    const c = dv.getUint16(OFF.name + 2 * i, true);
+    if (c === 0) break;
+    name += String.fromCharCode(c);
+  }
+
+  const toggleBits = dv.getUint16(OFF.toggle, true);
+  const buttons = [];
+  for (let b = 0; b < BUTTON_COUNT; b++) {
+    const base = OFF.buttons + b * BUTTON_STRIDE;
+    buttons.push({
+      map1: dv.getUint8(base),
+      map2: dv.getUint8(base + 1),
+      toggle: (toggleBits & (1 << b)) !== 0,
+    });
+  }
+
+  const ports = [];
+  for (let p = 0; p < PORT_COUNT; p++) {
+    const base = OFF.ports + p * PORT_STRIDE;
+    const type = dv.getUint8(base);
+    if (type === 0x00) {
+      ports.push({ kind: "none" });
+    } else if (type === 0x01) {
+      ports.push({
+        kind: "stick",
+        stick: dv.getUint8(base + 1), // 1=left, 2=right
+        orientation: dv.getUint8(base + 2),
+        sensitivity: dv.getUint8(base + 5), // 0 = firmware default
+        deadzone: [...u8.slice(base + 8, base + 14)], // 6 bytes, 0 = firmware default
+      });
+    } else if (type === 0x02 || type === 0x03) {
+      ports.push({
+        kind: "button",
+        analog: type === 0x02,
+        map1: dv.getUint8(base + 2),
+        map2: dv.getUint8(base + 3),
+        toggle: (toggleBits & (1 << (9 + p))) !== 0,
+      });
+    } else {
+      throw new Error(`unexpected expansion-port type 0x${type.toString(16)} on port ${p}`);
+    }
+  }
+
+  const uuid = [...u8.slice(OFF.uuid, OFF.uuid + 16)]
+    .map((x) => x.toString(16).padStart(2, "0"))
+    .join("");
+  const timestamp = Number(dv.getBigInt64(OFF.timestamp, true));
+
+  return { name, uuid, timestamp, buttons, ports, _raw: u8.slice(0, PROFILE_SIZE) };
+}
+
+// Build a 956-byte profile blob from an object. Starts from `_raw` when present so
+// unmodeled fields (stick sensitivity/deadzone) survive a round trip. Pass a Date.now()
+// value as `now` to refresh the timestamp (caller supplies it; the lib stays pure).
+export function buildProfile(profile, { now = null, regenerateUuid = false, randomBytes = null } = {}) {
+  const out = profile._raw ? u8of(profile._raw).slice(0, PROFILE_SIZE) : new Uint8Array(PROFILE_SIZE);
+  const dv = new DataView(out.buffer, out.byteOffset, out.byteLength);
+  out[OFF.sentinel] = 0x02;
+
+  if (profile.name != null) {
+    for (let i = 0; i < NAME_MAX; i++) {
+      dv.setUint16(OFF.name + 2 * i, i < profile.name.length ? profile.name.charCodeAt(i) : 0, true);
+    }
+  }
+
+  if (regenerateUuid) {
+    const rnd = randomBytes || defaultRandom(16);
+    out.set(rnd.slice(0, 16), OFF.uuid);
+  }
+
+  let toggleBits = 0;
+  const buttons = profile.buttons || [];
+  for (let b = 0; b < BUTTON_COUNT; b++) {
+    const base = OFF.buttons + b * BUTTON_STRIDE;
+    const btn = buttons[b];
+    if (btn) {
+      dv.setUint8(base, btn.map1 & 0xff);
+      dv.setUint8(base + 1, btn.map2 & 0xff);
+      if (btn.toggle) toggleBits |= 1 << b;
+    }
+  }
+
+  const ports = profile.ports || [];
+  for (let p = 0; p < PORT_COUNT; p++) {
+    const base = OFF.ports + p * PORT_STRIDE;
+    const port = ports[p];
+    if (!port) continue;
+    if (port.kind === "none") {
+      dv.setUint8(base, 0x00);
+    } else if (port.kind === "stick") {
+      dv.setUint8(base, 0x01);
+      dv.setUint8(base + 1, port.stick & 0xff);
+      dv.setUint8(base + 2, port.orientation & 0xff);
+      // Stick tuning. 0 = firmware default. Written explicitly when the model carries them
+      // (so edits persist); otherwise the bytes from _raw are kept as-is.
+      if (port.sensitivity != null) dv.setUint8(base + 5, port.sensitivity & 0xff);
+      if (Array.isArray(port.deadzone)) {
+        for (let i = 0; i < 6; i++) dv.setUint8(base + 8 + i, port.deadzone[i] & 0xff);
+      }
+    } else if (port.kind === "button") {
+      dv.setUint8(base, port.analog ? 0x02 : 0x03);
+      dv.setUint8(base + 2, port.map1 & 0xff);
+      dv.setUint8(base + 3, port.map2 & 0xff);
+      if (port.toggle) toggleBits |= 1 << (9 + p);
+    }
+  }
+
+  dv.setUint16(OFF.toggle, toggleBits, true);
+  if (now != null) dv.setBigInt64(OFF.timestamp, BigInt(now), true);
+  return out;
+}
+
+// ---- Transport packet builders (platform-agnostic) ----
+
+// 0x60 command requesting profile N (1..3) be streamed back on 0x61.
+export function buildReadCommand(profileNumber) {
+  checkProfileNumber(profileNumber);
+  const buf = new Uint8Array(CMD_PAYLOAD_SIZE);
+  buf[0] = 0x10 + (profileNumber - 1);
+  return buf;
+}
+
+// 0x60 command that switches the controller's *active* profile (1..3) — the same thing the
+// device's profile button does. Reverse-engineered by probing the command channel while
+// watching input-report byte 39: opcode 0x05 with the 1-based profile number in byte 1.
+export const CMD_SET_ACTIVE = 0x05;
+export function buildSetActiveCommand(profileNumber) {
+  checkProfileNumber(profileNumber);
+  const buf = new Uint8Array(CMD_PAYLOAD_SIZE);
+  buf[0] = CMD_SET_ACTIVE;
+  buf[1] = profileNumber;
+  return buf;
+}
+
+// Reassemble a 956-byte profile from the 18 raw 0x61 responses. Each response is the
+// full report (report id at [0]); payload starts at READ_PAYLOAD_OFFSET.
+export function assembleProfile(packets) {
+  const out = new Uint8Array(PROFILE_SIZE);
+  for (let i = 0; i < PACKET_COUNT; i++) {
+    const pkt = u8of(packets[i]);
+    for (let j = 0; j < CHUNK; j++) {
+      const idx = i * CHUNK + j;
+      if (idx < PROFILE_SIZE) out[idx] = pkt[READ_PAYLOAD_OFFSET + j] ?? 0;
+    }
+  }
+  return out;
+}
+
+// Build the 18 0x60 write packets for profile N from a 956-byte blob. CRC32 (LE) of the
+// whole blob is embedded at offset 6 of the final packet. Returns CMD_PAYLOAD_SIZE buffers
+// (no report id prefix — the transport adds 0x60).
+export function buildWritePackets(profileNumber, profileBytes) {
+  checkProfileNumber(profileNumber);
+  const data = u8of(profileBytes);
+  if (data.length < PROFILE_SIZE) throw new Error(`profile too short: ${data.length}`);
+  const crc = crc32(data, PROFILE_SIZE);
+  const packets = [];
+  for (let i = 0; i < PACKET_COUNT; i++) {
+    const buf = new Uint8Array(CMD_PAYLOAD_SIZE);
+    const dv = new DataView(buf.buffer);
+    buf[0] = 0x08 + profileNumber;
+    buf[1] = i;
+    for (let j = 0; j < CHUNK; j++) {
+      const idx = i * CHUNK + j;
+      if (idx < PROFILE_SIZE) buf[WRITE_PAYLOAD_OFFSET + j] = data[idx];
+    }
+    if (i === PACKET_COUNT - 1) dv.setUint32(6, crc, true);
+    packets.push(buf);
+  }
+  return packets;
+}
+
+export const PACKETS_PER_PROFILE = PACKET_COUNT;
+
+// ---- helpers ----
+function checkProfileNumber(n) {
+  if (!Number.isInteger(n) || n < 1 || n > PROFILE_COUNT) {
+    throw new Error(`profile number must be 1..${PROFILE_COUNT}, got ${n}`);
+  }
+}
+function u8of(x) {
+  if (x instanceof Uint8Array) return x;
+  if (x instanceof ArrayBuffer) return new Uint8Array(x);
+  if (ArrayBuffer.isView(x)) return new Uint8Array(x.buffer, x.byteOffset, x.byteLength);
+  if (Array.isArray(x)) return Uint8Array.from(x);
+  throw new Error("expected bytes");
+}
+function defaultRandom(n) {
+  const a = new Uint8Array(n);
+  if (typeof globalThis.crypto?.getRandomValues === "function") globalThis.crypto.getRandomValues(a);
+  return a;
+}
+
+// Human-readable summary used by the CLI and (optionally) the UI.
+export function describeProfile(p) {
+  const lines = [`name: ${JSON.stringify(p.name)}`, `uuid: ${p.uuid}`];
+  p.buttons.forEach((b, i) => {
+    const m = ACTIONS[b.map1] ?? `?${b.map1}`;
+    const m2 = b.map2 ? ` + ${ACTIONS[b.map2] ?? b.map2}` : "";
+    lines.push(`  button ${i + 1}: ${m}${m2}${b.toggle ? " [toggle]" : ""}`);
+  });
+  p.ports.forEach((pt, i) => {
+    let desc;
+    if (pt.kind === "none") desc = "—";
+    else if (pt.kind === "stick") {
+      const tuned = pt.sensitivity || (pt.deadzone || []).some((x) => x);
+      desc = `${STICKS[pt.stick] ?? "?"} (${ORIENTATIONS[pt.orientation] ?? "?"})` +
+        (tuned ? ` [sens=${pt.sensitivity}, deadzone=${(pt.deadzone || []).map((x) => x.toString(16)).join(" ")}]` : "");
+    }
+    else desc = `${ACTIONS[pt.map1] ?? "?"}${pt.map2 ? " + " + (ACTIONS[pt.map2] ?? pt.map2) : ""}${pt.analog ? " [analog]" : ""}${pt.toggle ? " [toggle]" : ""}`;
+    lines.push(`  port ${i}${i === 0 ? " (built-in stick)" : ""}: ${desc}`);
+  });
+  return lines.join("\n");
+}

package/web/bridge-core.mjs

@@ -0,0 +1,132 @@
+// PC input bridge — pure, platform-agnostic mapping engine.
+//
+// Turns the Access Controller's live input (physical buttons + stick) into abstract
+// output events (key/button down·up, relative mouse motion, gamepad axes). It does NO
+// I/O: a "sink" (xdotool, uinput, dry-run…) turns these events into real OS input.
+// This is the reusable heart of the bridge — read once, map anywhere.
+
+// Physical input indices (matches web/controller-render.mjs decodePhysical):
+//   0..7 = perimeter buttons, 8 = center, 9 = stick-click.
+export const PHYS_BUTTONS = 10;
+
+// Decode a raw input report (report id ALREADY stripped) into { buttons:Set, axes:[x,y] }.
+// Mirrors decodePhysical: byte 15 bits 0-7 = perimeter; byte 16 bit0 = center, bit1 = stick-click;
+// bytes 0/1 = stick X/Y (0..255, 128 center).
+export function decodeInput(data, deadzone = 0.16) {
+  const buttons = new Set();
+  for (let bit = 0; bit < 8; bit++) if (data[15] & (1 << bit)) buttons.add(bit);
+  if (data[16] & 0x01) buttons.add(8);
+  if (data[16] & 0x02) buttons.add(9);
+  const dz = (v) => (Math.abs(v) < deadzone ? 0 : v);
+  return { buttons, axes: [dz((data[0] - 128) / 128), dz((data[1] - 128) / 128)] };
+}
+
+// A default, keyboard-oriented mapping: stick drives the arrow keys, the center button
+// confirms (Enter), and the perimeter buttons cover space + common keys. Good for general
+// PC access / navigation; override per game via a config file.
+export const DEFAULT_MAPPING = {
+  // physical index -> output key name (sink translates names to OS keysyms/codes)
+  buttons: {
+    0: "space", 1: "Return", 2: "Escape", 3: "BackSpace",
+    4: "Tab", 5: "f", 6: "e", 7: "q",
+    8: "Return",      // center
+    9: "shift",       // stick-click
+  },
+  stick: { mode: "keys", up: "Up", down: "Down", left: "Left", right: "Right", threshold: 0.5 },
+  mouse: { speed: 18, deadzone: 0.2 }, // used only when stick.mode === "mouse"
+};
+
+// The engine diffs successive input states and emits only the changes (edges), so a sink
+// can hold keys/buttons down for as long as the physical input is held.
+export class BridgeEngine {
+  constructor(mapping = DEFAULT_MAPPING) {
+    this.mapping = normalizeMapping(mapping);
+    this.down = new Set();        // currently-asserted HELD output codes
+    this.prevPhys = new Set();    // physical buttons last tick (for press-edge detection)
+    // Classify each button's mapping: a held key, a chord ("ctrl+s"), or a macro (array).
+    this.btnOut = {};
+    for (const [idx, val] of Object.entries(this.mapping.buttons)) this.btnOut[idx] = parseOutput(val);
+  }
+
+  // Feed a decoded input state; returns an array of output events:
+  //   { type:"key", code, action:"down"|"up" }      keyboard/button
+  //   { type:"mouseMove", dx, dy }                   relative pointer motion
+  //   { type:"axis", code:"x"|"y", value }           gamepad axis (-1..1)
+  update(state) {
+    const events = [];
+    const want = new Set();          // HELD output codes that should be down this tick
+    const m = this.mapping;
+
+    // physical buttons -> output. Held keys stay down; chords/macros fire once on press edge.
+    for (const idx of state.buttons) {
+      const out = this.btnOut[idx];
+      if (!out) continue;
+      if (out.type === "hold") want.add(out.code);
+      else if (!this.prevPhys.has(idx)) events.push(...expand(out)); // momentary, on press edge only
+    }
+    this.prevPhys = new Set(state.buttons);
+
+    // stick -> keys / mouse / axis
+    const [x, y] = state.axes;
+    if (m.stick.mode === "keys") {
+      const t = m.stick.threshold;
+      if (x <= -t && m.stick.left) want.add(m.stick.left);
+      if (x >= t && m.stick.right) want.add(m.stick.right);
+      if (y <= -t && m.stick.up) want.add(m.stick.up);
+      if (y >= t && m.stick.down) want.add(m.stick.down);
+    } else if (m.stick.mode === "mouse") {
+      const dz = m.mouse.deadzone, sp = m.mouse.speed;
+      const ax = Math.abs(x) < dz ? 0 : x, ay = Math.abs(y) < dz ? 0 : y;
+      if (ax || ay) events.push({ type: "mouseMove", dx: Math.round(ax * sp), dy: Math.round(ay * sp) });
+    } else if (m.stick.mode === "axis") {
+      events.push({ type: "axis", code: "x", value: x }, { type: "axis", code: "y", value: y });
+    }
+
+    // diff against what's currently held: emit ups for released, downs for newly pressed
+    for (const code of this.down) if (!want.has(code)) { events.push({ type: "key", code, action: "up" }); }
+    for (const code of want) if (!this.down.has(code)) { events.push({ type: "key", code, action: "down" }); }
+    this.down = want;
+    return events;
+  }
+
+  // Events to release everything still held (call on shutdown so no key gets "stuck").
+  releaseAll() {
+    const events = [...this.down].map((code) => ({ type: "key", code, action: "up" }));
+    this.down = new Set();
+    return events;
+  }
+}
+
+// Classify a mapping value into how it should fire:
+//   "a"           -> held while the button is held            { type:"hold", code:"a" }
+//   "ctrl+s"      -> chord, fired once on press               { type:"chord", parts:["ctrl","s"] }
+//   ["g","g"]     -> macro (sequence of chords), once on press{ type:"macro", steps:[["g"],["g"]] }
+//   ["ctrl+c","ctrl+v"] -> macro of chords
+export function parseOutput(value) {
+  if (Array.isArray(value)) return { type: "macro", steps: value.map(toParts) };
+  if (typeof value === "string" && value.includes("+")) return { type: "chord", parts: toParts(value) };
+  return { type: "hold", code: String(value) };
+}
+function toParts(s) { return String(s).split("+").map((p) => p.trim()).filter(Boolean); }
+
+// Expand a chord/macro into a burst of key down/up events (modifiers held around the key).
+function expandChord(parts) {
+  const ev = [];
+  for (const p of parts) ev.push({ type: "key", code: p, action: "down" });
+  for (let i = parts.length - 1; i >= 0; i--) ev.push({ type: "key", code: parts[i], action: "up" });
+  return ev;
+}
+function expand(out) {
+  if (out.type === "chord") return expandChord(out.parts);
+  if (out.type === "macro") return out.steps.flatMap(expandChord);
+  return [];
+}
+
+function normalizeMapping(mapping) {
+  const m = mapping || {};
+  return {
+    buttons: { ...DEFAULT_MAPPING.buttons, ...(m.buttons || {}) },
+    stick: { ...DEFAULT_MAPPING.stick, ...(m.stick || {}) },
+    mouse: { ...DEFAULT_MAPPING.mouse, ...(m.mouse || {}) },
+  };
+}

package/web/bridge-map.mjs

@@ -0,0 +1,102 @@
+// Helpers for the in-app Key Bridge editor — pure, I/O-free, testable.
+//
+// The editor lets you assign a keyboard key / chord to each physical input and the stick,
+// then export a config the local `bridge.mjs` process runs. The browser can author and
+// preview this, but cannot inject input into other apps (that's the local bridge's job).
+
+import { DEFAULT_MAPPING } from "./bridge-core.mjs";
+
+// Physical input labels (index 0..9), matching controller-render PHYS layout.
+export const PHYS_LABELS = [
+  "Button 1", "Button 2", "Button 3", "Button 4", "Button 5", "Button 6", "Button 7", "Button 8",
+  "Center", "Stick-click",
+];
+export const STICK_MODES = ["keys", "mouse", "axis"];
+export const STICK_DIRS = ["up", "down", "left", "right"];
+
+// A fresh, editable copy of the default mapping with buttons keyed 0..9.
+export function defaultBridgeMap() {
+  const m = JSON.parse(JSON.stringify(DEFAULT_MAPPING));
+  const buttons = {};
+  for (let i = 0; i < PHYS_LABELS.length; i++) buttons[i] = m.buttons[i] ?? "nothing";
+  return { buttons, stick: m.stick, mouse: m.mouse };
+}
+
+// Translate a browser keyboard event into a bridge value ("a", "ctrl+s", …) or null if the
+// event is a modifier on its own (caller should keep listening for the real key).
+export function keyEventToValue(e) {
+  if (["Control", "Shift", "Alt", "Meta"].includes(e.key)) return null;
+  const base = keysym(e.key);
+  if (!base) return null;
+  const parts = [];
+  if (e.ctrlKey) parts.push("ctrl");
+  if (e.altKey) parts.push("alt");
+  if (e.shiftKey && base !== "shift") parts.push("shift");
+  if (e.metaKey) parts.push("super");
+  parts.push(base);
+  return parts.join("+");
+}
+
+// Translate a Node readline "keypress" event (terminal) into a bridge value — the CLI
+// equivalent of keyEventToValue. key = { name, ctrl, meta, shift, sequence }.
+export function keypressToValue(key) {
+  if (!key) return null;
+  let base = TERM_NAME[key.name];
+  if (!base) {
+    if (key.name && /^f\d+$/.test(key.name)) base = key.name.toUpperCase();
+    else if (key.name && key.name.length === 1) base = key.name.toLowerCase();
+    else if (key.sequence && key.sequence.length === 1 && key.sequence >= " ") base = key.sequence.toLowerCase();
+  }
+  if (!base) return null;
+  const parts = [];
+  if (key.ctrl) parts.push("ctrl");
+  if (key.meta) parts.push("alt");
+  if (key.shift && base !== "shift") parts.push("shift");
+  parts.push(base);
+  return parts.join("+");
+}
+const TERM_NAME = {
+  return: "Return", enter: "Return", space: "space", tab: "Tab", backspace: "BackSpace",
+  escape: "Escape", up: "Up", down: "Down", left: "Left", right: "Right",
+  delete: "Delete", home: "Home", end: "End", pageup: "Prior", pagedown: "Next",
+};
+
+const KEYSYM = {
+  " ": "space", "Spacebar": "space", "Enter": "Return", "Tab": "Tab", "Backspace": "BackSpace",
+  "ArrowUp": "Up", "ArrowDown": "Down", "ArrowLeft": "Left", "ArrowRight": "Right",
+  "Delete": "Delete", "Home": "Home", "End": "End", "PageUp": "Prior", "PageDown": "Next",
+  "Escape": "Escape", "Control": "ctrl", "Shift": "shift", "Alt": "alt", "Meta": "super",
+};
+function keysym(k) {
+  if (KEYSYM[k]) return KEYSYM[k];
+  if (k.length === 1) return k.toLowerCase();
+  if (/^F\d+$/.test(k)) return k;
+  return k;
+}
+
+// Human-readable value for the UI.
+export function displayValue(v) {
+  if (v == null || v === "" || v === "nothing") return "—";
+  if (Array.isArray(v)) return v.join(" , ");
+  return v;
+}
+
+// Reduce an editable map to a clean config object (drops unassigned buttons; mouse only in mouse mode).
+export function toConfig(map) {
+  const buttons = {};
+  for (const [i, val] of Object.entries(map.buttons)) {
+    if (val && val !== "nothing") buttons[i] = val;
+  }
+  const cfg = { buttons, stick: { ...map.stick } };
+  if (map.stick.mode === "mouse") cfg.mouse = { ...map.mouse };
+  return cfg;
+}
+
+export function toConfigJSON(map) {
+  return JSON.stringify(toConfig(map), null, 2);
+}
+
+// A ready-to-run command for the exported config.
+export function runCommand(filename = "ps-access-bridge.json", sink = "xdotool") {
+  return `node bridge.mjs --config ${filename} --sink ${sink}`;
+}

package/web/controller-render.mjs

@@ -0,0 +1,79 @@
+// Shared controller rendering + physical-input decoding for the XMB configurator and the
+// input monitor. Pure (no DOM/IO) so any page can build a render and decode reports.
+import { ACTIONS } from "./access-protocol.mjs";
+
+// Glyphs for actions with a recognizable symbol; others fall back to short text.
+export const SYMBOLS = { 1: "○", 2: "✕", 3: "△", 4: "□", 5: "▲", 6: "▼", 7: "◀", 8: "▶", 15: "☰", 18: "▭" };
+export const symLabel = (code) => (code === 0 ? "—" : SYMBOLS[code] ?? ACTIONS[code] ?? `?${code}`);
+export const nameLabel = (code) => (code === 0 ? "Not assigned" : ACTIONS[code] ?? `?${code}`);
+
+// geometry
+export const M = { CX: 220, CY: 220, RO: 140, RI: 82, RM: 111, CTR: 54, GAP: 3.2, CORNER: 14,
+  STICK_DIST: 182, STICK_R: 30, THUMB_R: 14, PORT_R: 17, PORT_ARC: 186 };
+export const ORIENT_ROT = { 0: 0, 1: 270, 2: 180, 3: 90 };
+export const rotV = (x, y, t) => [x * Math.cos(t) - y * Math.sin(t), x * Math.sin(t) + y * Math.cos(t)];
+export const rad = (d) => d * Math.PI / 180;
+
+export function roundedWedge(cx, cy, ri, ro, a0, a1, cr) {
+  const pol = (r, a) => [cx + r * Math.cos(a), cy + r * Math.sin(a)];
+  const f = (p) => `${p[0].toFixed(1)},${p[1].toFixed(1)}`;
+  cr = Math.min(cr, (ro - ri) / 2 - 1, ((a1 - a0) * ri) / 2 - 1);
+  const dO = Math.asin(cr / (ro - cr)), dI = Math.asin(cr / (ri + cr));
+  const roS = (ro - cr) * Math.cos(dO), riS = (ri + cr) * Math.cos(dI);
+  const P1 = pol(ro, a0 + dO), P2 = pol(ro, a1 - dO), P3 = pol(roS, a1), P4 = pol(riS, a1),
+    P5 = pol(ri, a1 - dI), P6 = pol(ri, a0 + dI), P7 = pol(riS, a0), P8 = pol(roS, a0);
+  return `M${f(P1)} A${ro},${ro} 0 0 1 ${f(P2)} A${cr},${cr} 0 0 1 ${f(P3)} L${f(P4)} `
+    + `A${cr},${cr} 0 0 1 ${f(P5)} A${ri},${ri} 0 0 0 ${f(P6)} A${cr},${cr} 0 0 1 ${f(P7)} `
+    + `L${f(P8)} A${cr},${cr} 0 0 1 ${f(P1)} Z`;
+}
+
+// Build a neutral controller SVG. Live highlight (data-btn → .on) + thumb motion are applied
+// by the page. `focus` = {type:'button'|'port'|'stick', index} outlines one input.
+export function profileSVG(profile, { focus = null } = {}) {
+  if (!profile) return "";
+  const stick = profile.ports[0];
+  const orient = stick.kind === "stick" ? stick.orientation : 3;
+  const oDeg = ORIENT_ROT[orient] ?? 0, theta = rad(oDeg);
+  const R = (x, y) => { const [rx, ry] = rotV(x - M.CX, y - M.CY, theta); return [M.CX + rx, M.CY + ry]; };
+  const seg = (f) => `seg${f ? " foc" : ""}`;
+  let s = `<svg viewBox="0 0 440 440" xmlns="http://www.w3.org/2000/svg">`;
+  for (let i = 0; i < 8; i++) {
+    const ca = rad(90 - i * 45 + oDeg);
+    const d = roundedWedge(M.CX, M.CY, M.RI, M.RO, ca - rad(22.5 - M.GAP), ca + rad(22.5 - M.GAP), M.CORNER);
+    const b = profile.buttons[i];
+    s += `<path d="${d}" class="${seg(focus?.type === "button" && focus.index === i)}" data-btn="${i}"/>`;
+    s += `<text x="${(M.CX + M.RM * Math.cos(ca)).toFixed(1)}" y="${(M.CY + M.RM * Math.sin(ca) + 7).toFixed(1)}" class="lab">${symLabel(b.map1)}</text>`;
+  }
+  s += `<circle cx="${M.CX}" cy="${M.CY}" r="${M.CTR}" class="${seg(focus?.type === "button" && focus.index === 8)}" data-btn="8"/>`;
+  s += `<text x="${M.CX}" y="${M.CY + 8}" class="lab big">${symLabel(profile.buttons[8].map1)}</text>`;
+  for (let p = 1; p <= 4; p++) {
+    const a = rad(-90 + (p - 2.5) * 24 + oDeg);
+    const [x, y] = [M.CX + M.PORT_ARC * Math.cos(a), M.CY + M.PORT_ARC * Math.sin(a)];
+    const port = profile.ports[p];
+    const lbl = port.kind === "stick" ? "stk" : port.kind === "button" ? symLabel(port.map1) : `E${p}`;
+    s += `<circle cx="${x.toFixed(1)}" cy="${y.toFixed(1)}" r="${M.PORT_R}" class="${seg(focus?.type === "port" && focus.index === p)}"/>`;
+    s += `<text x="${x.toFixed(1)}" y="${(y + 5).toFixed(1)}" class="lab sm">${lbl}</text>`;
+  }
+  const [sx, sy] = R(M.CX, M.CY + M.STICK_DIST);
+  const stickFoc = focus?.type === "stick" || (focus?.type === "button" && focus.index === 9);
+  s += `<circle cx="${sx.toFixed(1)}" cy="${sy.toFixed(1)}" r="${M.STICK_R}" class="stickwell${stickFoc ? " foc" : ""}"/>`;
+  s += `<circle cx="${sx.toFixed(1)}" cy="${sy.toFixed(1)}" r="${M.STICK_R - 8}" class="thumb${stickFoc ? " foc" : ""}" data-bx="${sx.toFixed(1)}" data-by="${sy.toFixed(1)}" data-btn="9"/>`;
+  s += `</svg>`;
+  return s;
+}
+
+// Physical button names by index (0-7 perimeter 1-8, 8 center, 9 stick-click). Reverse-engineered.
+export const PHYS_NAMES = ["1", "2", "3", "4", "5", "6", "7", "8", "Center", "Stick-click"];
+
+// Decode physical button + stick state from a raw input-report data view (report id excluded):
+// byte 15 bits 0-7 = perimeter 1-8; byte 16 bit 0 = center, bit 1 = stick-click; bytes 0/1 = stick X/Y;
+// byte 16 bit 3 (0x08) = profile-switch button; byte 39 = active on-device profile (1-based).
+export function decodePhysical(data) {
+  const buttons = new Set();
+  for (let bit = 0; bit < 8; bit++) if (data[15] & (1 << bit)) buttons.add(bit);
+  if (data[16] & 0x01) buttons.add(8);
+  if (data[16] & 0x02) buttons.add(9);
+  const dz = (v) => (Math.abs(v) < 0.16 ? 0 : v);
+  const profile = data.length > 39 && data[39] >= 1 && data[39] <= 3 ? data[39] : 0; // 0 = unknown
+  return { buttons, axes: [dz((data[0] - 128) / 128), dz((data[1] - 128) / 128)], profile };
+}