feat(keychron): Hall-effect keyboard controls behind a flag

build/check-bundle-size.ts

@@ -19,9 +19,16 @@ import { join } from "node:path";
 // 2026-10-29: Razer, Logitech and SteelSeries keyboard HID clients and panels
 // add three real device protocols. Measured: 3,558,003 bytes across all
 // chunks, with the main chunk at 1,149,146 bytes (below its existing cap).
+// 2026-10-30: Keychron Hall-effect panel (key map, response curve graph) adds
+// styles/areas/keychron.css, about 3 kB. Measured: 164,771 bytes of CSS before the
+// bump; the lazy layout tables add a 251 kB chunk of JS (main grew 6.7 kB).
+// 2026-10-30: Arbiter Studio controls and Keychron Hall-effect controls together
+// add two keyboard workspaces, layouts, localized strings and device artwork.
+// Measured after merging both: 168,860 bytes CSS, 3,652,136 bytes JS;
+// main is 1,288,217 bytes, below its existing cap.
 const BUDGET_BYTES: Record<string, number> = {
-  ".css": 165_000,
-  ".js": 3_600_000,
+  ".css": 170_000,
+  ".js": 3_700_000,
 };
 
 // main-*.js measured 1,511,619 bytes right after the split (posthog ~377 kB

src/device/controller.ts

@@ -3259,8 +3259,9 @@ export function clearKeyboardSelection(): void {
 export async function applyKeyboardCommand(command: KeyboardCommand): Promise<void> {
   const client = activeKeyboard;
   if (!client || keyboardBusy) return;
+  const telemetry = command.kind === "keychronKeyTravel";
   keyboardBusy = true;
-  keyboardStatusText = st("kb.applying");
+  if (!telemetry) keyboardStatusText = st("kb.applying");
   emit();
   try {
     const update = await client.command(command);
@@ -3282,13 +3283,15 @@ export async function applyKeyboardCommand(command: KeyboardCommand): Promise<vo
       keyboardMatrix = trigger.matrix;
       keyboardKeys = trigger.keys;
     }
-    keyboardStatusText = command.kind === "caps" || command.kind === "direct" || command.kind === "steelseriesColor"
+    if (!telemetry) keyboardStatusText = command.kind === "caps" || command.kind === "direct" || command.kind === "steelseriesColor"
       ? st("kb.sent")
       : command.kind === "razerEffect" || command.kind === "logitechRgbEffect" || command.kind === "logitechSolidColor"
         ? st("kb.writeOnly")
         : st("kb.updated");
   } catch (error) {
     if (activeKeyboard !== client) return;
+    const recovered = client.recoveredWorkspace?.();
+    if (recovered) keyboardWorkspace = { ...keyboardWorkspace, ...recovered };
     keyboardStatusText = error instanceof Error ? error.message : st("kb.readFailed");
   } finally {
     if (activeKeyboard === client) { keyboardBusy = false; emit(); }

src/device/device-clients.ts

@@ -6,6 +6,8 @@ import { WootingKeyboardClient } from "./wooting-keyboard.ts";
 import { RazerKeyboardClient } from "./razer-keyboard.ts";
 import { LogitechKeyboardClient } from "./logitech-keyboard.ts";
 import { SteelSeriesKeyboardClient } from "./steelseries-keyboard.ts";
+import { KeychronKeyboardClient } from "./keychron-keyboard.ts";
+import { keychronHallEffectEnabled } from "./keychron-flag.ts";
 import type { PulsarClient, SupportedClient } from "@openmouse/protocol/drivers/registry";
 export { describeHidDevice } from "./hid-diagnostics.ts";
 export { type PulsarClient, type SupportedClient };
@@ -100,7 +102,7 @@ export type { KeyboardClient };
 export function isKeyboardClient(client: SupportedClient | KeyboardClient): client is KeyboardClient {
   return client instanceof WuqueKeyboardClient || client instanceof KochiKeyboardClient || client instanceof WootingKeyboardClient
     || client instanceof RazerKeyboardClient || client instanceof LogitechKeyboardClient || client instanceof SteelSeriesKeyboardClient
-    || client instanceof ArbiterKeyboardClient;
+    || client instanceof KeychronKeyboardClient || client instanceof ArbiterKeyboardClient;
 }
 
 /**
@@ -116,6 +118,7 @@ export function createKeyboardClient(device: HIDDevice): KeyboardClient | null {
   if (LogitechKeyboardClient.isSupported(device)) return new LogitechKeyboardClient(device);
   if (SteelSeriesKeyboardClient.isSupported(device)) return new SteelSeriesKeyboardClient(device);
   if (ArbiterKeyboardClient.isSupported(device)) return new ArbiterKeyboardClient(device);
+  if (keychronHallEffectEnabled() && KeychronKeyboardClient.isSupported(device)) return new KeychronKeyboardClient(device);
   return null;
 }
 

src/device/hid-filters.ts

@@ -1,5 +1,7 @@
 import { SUPPORTED_HID_FILTERS } from "@openmouse/protocol/drivers/vendors";
 import { SUPPORTED_HID_FILTERS as KEYBOARD_HID_FILTERS } from "@openmouse/keyboard-protocol/drivers";
+import { KEYCHRON_CONFIG_USAGE, KEYCHRON_CONFIG_USAGE_PAGE, KEYCHRON_HE_PRODUCTS, KEYCHRON_VENDOR_ID } from "@openmouse/keyboard-protocol/keychron";
+import { keychronHallEffectEnabled } from "./keychron-flag.ts";
 
 /**
  * The Basilisk V3 Pro in Bluetooth mode. It enumerates under Razer's Bluetooth
@@ -9,4 +11,16 @@ import { SUPPORTED_HID_FILTERS as KEYBOARD_HID_FILTERS } from "@openmouse/keyboa
  */
 export const BASILISK_V3_PRO_BLUETOOTH = { vendorId: 0x068e, productId: 0x00ac };
 
-export const HID_FILTERS: HIDDeviceFilter[] = [...SUPPORTED_HID_FILTERS, ...KEYBOARD_HID_FILTERS, BASILISK_V3_PRO_BLUETOOTH];
+/** Raw-HID command collection of every catalogued Keychron Hall-effect board. */
+export const KEYCHRON_HID_FILTERS: HIDDeviceFilter[] = Object.keys(KEYCHRON_HE_PRODUCTS).map((productId) => ({
+  vendorId: KEYCHRON_VENDOR_ID,
+  productId: Number(productId),
+  usagePage: KEYCHRON_CONFIG_USAGE_PAGE,
+  usage: KEYCHRON_CONFIG_USAGE,
+}));
+
+/** Keychron filters are offered only behind the experimental flag, read when the app loads. */
+export const HID_FILTERS: HIDDeviceFilter[] = [
+  ...SUPPORTED_HID_FILTERS, ...KEYBOARD_HID_FILTERS, ...(keychronHallEffectEnabled() ? KEYCHRON_HID_FILTERS : []),
+  BASILISK_V3_PRO_BLUETOOTH,
+];

src/device/keyboard-client.ts

@@ -3,7 +3,7 @@ import type { KeyboardIdentityView, KeyboardPollingView, KeyboardTriggerKey, Key
 
 export interface KeyboardClient {
   readonly device: HIDDevice;
-  readonly family: "wuque" | "kochi" | "wooting" | "razer" | "logitech" | "steelseries" | "arbiter";
+  readonly family: "wuque" | "kochi" | "wooting" | "razer" | "logitech" | "steelseries" | "keychron" | "arbiter";
   readonly brand: string;
   /** Set once the session needs a reconnect before it can be used again. */
   readonly faulted?: boolean;
@@ -12,6 +12,8 @@ export interface KeyboardClient {
   close(): Promise<void>;
   readIdentity(): Promise<KeyboardIdentityView>;
   command(command: KeyboardCommand): Promise<Partial<KeyboardWorkspace>>;
+  /** State to merge after `command` threw, when the failure also changed what the board holds. */
+  recoveredWorkspace?(): Partial<KeyboardWorkspace> | null;
   readPolling?(): Promise<KeyboardPollingView>;
   setPollingRate?(hz: number): Promise<KeyboardPollingView>;
   readTrigger?(): Promise<{ matrix: readonly (readonly number[])[]; keys: KeyboardTriggerKey[] }>;

src/device/keyboard-workspace.ts

@@ -7,6 +7,7 @@ import type { WootingAkcPayloadWrite, WootingRapidTriggerTarget, WootingRgbColor
 import type { RazerKeyboardCommand } from './razer-keyboard.ts';
 import type { LogitechKeyboardCommand } from './logitech-keyboard.ts';
 import type { SteelSeriesKeyboardCommand } from './steelseries-keyboard.ts';
+import type { KeychronKeyboardCommand, KeychronWorkspace } from './keychron-keyboard.ts';
 
 export interface WootingRgbView {
   core: WootingRgbCore | null;
@@ -21,6 +22,8 @@ export interface KeyboardWorkspace {
   razerGameModeLed?: boolean | null;
   /** Typed RGB core and color pages; raw `wooting.rgb` stays for diagnostics. */
   wootingRgb?: WootingRgbView | null;
+  /** Keychron Hall-effect state; set only while the experimental flag is on. */
+  keychron?: KeychronWorkspace | null;
   /** HB68 mode; independent of the Wuque global-settings structure. */
   systemMode?: "win" | "mac";
   global: WuqueGlobalState | null;
@@ -37,7 +40,7 @@ export interface KeyboardWorkspace {
 }
 export const emptyKeyboardWorkspace = (): KeyboardWorkspace => ({ global: null, lighting: null, custom: [], shell: null, layer: null, styles: [], defaults: [], macro: null, higher: null, adc: null });
 export type KeyboardCommand =
-  | RazerKeyboardCommand | LogitechKeyboardCommand | SteelSeriesKeyboardCommand
+  | RazerKeyboardCommand | LogitechKeyboardCommand | SteelSeriesKeyboardCommand | KeychronKeyboardCommand
   | { kind: 'refresh' }
   | { kind: 'wootingKeyActuation'; keys: number | readonly number[]; actuationMm: number | null }
   | { kind: 'wootingKeyRapidTrigger'; keys: number | readonly number[]; target: WootingRapidTriggerTarget | null }

src/device/keychron-curve.test.ts

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { KeychronState } from "@openmouse/keyboard-protocol/drivers";
+import type { KeychronCurve } from "@openmouse/keyboard-protocol/keychron";
+import { CURVE_MAX_Y, clampCurve, curveInRange, curveScale, linearCurve, setCurvePoint } from "./keychron-curve.ts";
+
+const base: KeychronState = {
+  productId: 0x040c, heVersion: 4, features: { switchAxis: true, resetSingleKey: false, dkr: false, turbo: false, gamepadDisable: false, supportMechanical: true },
+  unit: 0.1, profileSize: 0, dksCount: null, snapTapCount: null, rows: 6, cols: 19, travel: { min: 0.2, max: 3.3, deadzone: 0.2 },
+};
+
+test("x runs to floor(10 * (max + dead zone)) and y to 127", () => {
+  assert.deepEqual(curveScale(base, null), { maxX: 35, fromBoard: true, unverifiedStep: false });
+  assert.equal(curveScale({ ...base, travel: { min: 0.1, max: 3.35 } }, null).maxX, 33);
+  assert.equal(curveScale({ ...base, travel: null }, 3.3).maxX, 33);
+  assert.deepEqual(curveScale({ ...base, travel: null }, null), { maxX: 255, fromBoard: false, unverifiedStep: false });
+  assert.equal(curveScale({ ...base, heVersion: 5 }, null).unverifiedStep, true);
+});
+
+test("the linear preset is Launcher's: thirds along, ending at (max, 127)", () => {
+  assert.deepEqual(linearCurve(35), [[0, 0], [12, 42], [23, 85], [35, 127]]);
+  assert.ok(curveInRange(linearCurve(35), 35));
+  assert.ok(curveInRange(linearCurve(255), 255));
+});
+
+test("a point stays between its neighbours and inside the ranges", () => {
+  const curve = linearCurve(35);
+  assert.deepEqual(setCurvePoint(curve, 1, 99, 500, 35)[1], [23, 127]);
+  assert.deepEqual(setCurvePoint(curve, 2, -4, -9, 35)[2], [12, 0]);
+  assert.deepEqual(setCurvePoint(curve, 0, 8, 3, 35)[0], [8, 3]); // the first point may move right, up to the second point
+  assert.deepEqual(setCurvePoint(curve, 0, 40, 3, 35)[0], [12, 3]);
+  assert.deepEqual(setCurvePoint(curve, 3, 200, 10, 35)[3], [35, 10]);
+  assert.deepEqual(setCurvePoint(curve, 1, Number.NaN, Number.NaN, 35)[1], [0, 0]);
+});
+
+test("no sequence of edits can leave a byte out of range", () => {
+  let seed = 7;
+  const random = (): number => { seed = (seed * 48271) % 2147483647; return seed / 2147483647; };
+  for (const maxX of [1, 33, 35, 255]) {
+    let curve: KeychronCurve = linearCurve(maxX);
+    for (let step = 0; step < 500; step++) {
+      curve = setCurvePoint(curve, Math.floor(random() * 4), (random() - 0.3) * 600, (random() - 0.3) * 400, maxX);
+      assert.ok(curveInRange(curve, maxX), JSON.stringify(curve));
+    }
+  }
+});
+
+test("clampCurve repairs a curve outside the ranges", () => {
+  const repaired = clampCurve([[40, 200], [30, -3], [220, 50], [10, 127]], 35);
+  assert.deepEqual(repaired, [[35, CURVE_MAX_Y], [35, 0], [35, 50], [35, 127]]);
+  assert.ok(curveInRange(repaired, 35));
+  assert.equal(curveInRange([[0, 0], [36, 0], [36, 0], [36, 0]], 35), false);
+});

src/device/keychron-curve.ts

@@ -0,0 +1,67 @@
+import { KEYCHRON_ADVANCE_MODE, type KeychronCurve, type KeychronProfileBuffer } from "@openmouse/keyboard-protocol/keychron";
+import type { KeychronState } from "@openmouse/keyboard-protocol/drivers";
+
+/**
+ * Ranges for the response curve, as Keychron Launcher's curve editor uses them
+ * (read from its code, not verified on hardware): x is key travel in 0.1 mm
+ * steps up to the board's maximum travel plus dead zone, y is output strength
+ * 0 to 127, and the four points keep x non-decreasing left to right.
+ */
+export const CURVE_MAX_Y = 127;
+/** Millimetres per x step, as Launcher derives it (mm * 10). */
+export const CURVE_X_STEP_MM = 0.1;
+
+export interface CurveScale {
+  /** Largest x byte. */
+  maxX: number;
+  /** False when neither the board definition nor the axis type gave a travel range, so the byte limit is used. */
+  fromBoard: boolean;
+  /** Command v5 uses another travel step; Launcher still scales x by 10, so that scale is unverified there. */
+  unverifiedStep: boolean;
+}
+
+export function curveScale(state: KeychronState, axisMaxMm: number | null): CurveScale {
+  const travel = state.travel;
+  const mm = travel?.max !== undefined ? travel.max + (travel.deadzone ?? 0) : axisMaxMm;
+  const maxX = mm === null || mm <= 0 ? 255 : Math.min(255, Math.floor(mm / CURVE_X_STEP_MM + 1e-6));
+  return { maxX, fromBoard: mm !== null && mm > 0, unverifiedStep: state.heVersion >= 5 };
+}
+
+const clamp = (value: number, low: number, high: number): number => Math.min(high, Math.max(low, Math.round(Number.isFinite(value) ? value : low)));
+
+/** Move one point, keeping every byte in range and x between its neighbours. */
+export function setCurvePoint(curve: KeychronCurve, index: number, x: number, y: number, maxX: number): KeychronCurve {
+  const low = index === 0 ? 0 : curve[index - 1]![0];
+  const high = index === curve.length - 1 ? maxX : curve[index + 1]![0];
+  return curve.map((point, i) => (i === index ? [clamp(x, low, Math.max(low, high)), clamp(y, 0, CURVE_MAX_Y)] : point)) as unknown as KeychronCurve;
+}
+
+/** Bring any curve into range, left to right. */
+export function clampCurve(curve: KeychronCurve, maxX: number): KeychronCurve {
+  let previous = 0;
+  return curve.map(([x, y]) => {
+    previous = clamp(x, previous, maxX);
+    return [previous, clamp(y, 0, CURVE_MAX_Y)];
+  }) as unknown as KeychronCurve;
+}
+
+export function curveInRange(curve: KeychronCurve, maxX: number): boolean {
+  let previous = 0;
+  return curve.every(([x, y]) => {
+    const ok = Number.isInteger(x) && Number.isInteger(y) && x >= previous && x <= maxX && y >= 0 && y <= CURVE_MAX_Y;
+    previous = x;
+    return ok;
+  });
+}
+
+/** Launcher's linear preset: from (0, 0) to (max, 127) with the middle points a third and two thirds along. */
+export function linearCurve(maxX: number): KeychronCurve {
+  const at = (fraction: number): [number, number] => [Math.round(maxX * fraction), Math.round(CURVE_MAX_Y * fraction)];
+  return [[0, 0], at(1 / 3), at(2 / 3), [maxX, CURVE_MAX_Y]];
+}
+
+/** Keys set to the analog advanced mode; the curve shapes their output. */
+export function analogKeyCount(profile: KeychronProfileBuffer | null): number {
+  if (!profile) return 0;
+  return profile.keys.reduce((sum, row) => sum + row.filter((key) => key.advanceMode === KEYCHRON_ADVANCE_MODE.analog).length, 0);
+}

src/device/keychron-flag.ts

@@ -0,0 +1,16 @@
+/**
+ * Keychron Hall-effect support is experimental: the protocol was derived from
+ * static analysis of Keychron Launcher and has not run on a physical board.
+ * It stays off until the flag is set, e.g. in the browser console:
+ *
+ *   localStorage.setItem("openmouse.keychronHallEffect", "1"); location.reload();
+ */
+export const KEYCHRON_HALL_EFFECT_FLAG = "openmouse.keychronHallEffect";
+
+export function keychronHallEffectEnabled(): boolean {
+  try {
+    return globalThis.localStorage?.getItem(KEYCHRON_HALL_EFFECT_FLAG) === "1";
+  } catch {
+    return false;
+  }
+}