feat: anonymous PostHog analytics with opt-out

.env.example

@@ -1,3 +1,3 @@
-# No public build-time variables are required. The app reads no VITE_* keys at
-# build time; the former Supabase and voting/Turnstile configuration was removed
-# when the request catalog and protected voting were retired.
+# Public PostHog browser configuration. Copy these values into a local .env file.
+VITE_POSTHOG_KEY=
+VITE_POSTHOG_HOST=

.github/workflows/ci.yml

@@ -51,6 +51,7 @@ jobs:
             "@openmouse/keyboard-protocol": keyboardProtocolVersion,
             "@openmouse/protocol": protocolVersion,
             "lucide-react": "^1.43.0",
+            "posthog-js": "^1.438.17",
             "preact": "^10.29.8",
           };
 

build/check-bundle-size.ts

@@ -1,9 +1,11 @@
 import { readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 
+// JS raised from 2_800_000: posthog-js (anonymous analytics, src/platform/analytics.ts)
+// added about 340 kB; measured 3_125_781 bytes with it.
 const BUDGET_BYTES: Record<string, number> = {
   ".css": 165_000,
-  ".js": 2_800_000,
+  ".js": 3_150_000,
 };
 
 const ASSETS = join("dist", "assets");

functions/_lib/security-headers.js

@@ -22,14 +22,14 @@
 
 export const CSP = [
   "default-src 'self'",
-  "script-src 'self'",
+  "script-src 'self' https://us-assets.i.posthog.com",
   "script-src-attr 'none'",
   "style-src 'self' https://fonts.googleapis.com",
   "style-src-attr 'none'",
   "font-src 'self' data: https://fonts.gstatic.com",
   "img-src 'self' data: blob: https://img.openmouse.app https://cdn.cloudflare.steamstatic.com https://shared.akamai.steamstatic.com https://store-images.s-microsoft.com http://127.0.0.1:17846",
   "media-src 'self'",
-  "connect-src 'self' https://api.github.com https://cdn.jsdelivr.net http://127.0.0.1:17846 ws://127.0.0.1:17846",
+  "connect-src 'self' https://us.i.posthog.com https://us-assets.i.posthog.com https://api.github.com https://cdn.jsdelivr.net http://127.0.0.1:17846 ws://127.0.0.1:17846",
   "worker-src 'self'",
   "manifest-src 'self'",
   "object-src 'none'",

package.json

@@ -16,6 +16,7 @@
     "@openmouse/keyboard-protocol": "1.1.0",
     "@openmouse/protocol": "0.45.2",
     "lucide-react": "^1.43.0",
+    "posthog-js": "^1.438.17",
     "preact": "^10.29.8"
   },
   "devDependencies": {

public/_headers

@@ -22,7 +22,7 @@
 # isolation buys the app nothing it needs.
 
 /*
-  Content-Security-Policy: default-src 'self'; script-src 'self'; script-src-attr 'none'; style-src 'self' https://fonts.googleapis.com; style-src-attr 'none'; font-src 'self' data: https://fonts.gstatic.com; img-src 'self' data: blob: https://img.openmouse.app https://cdn.cloudflare.steamstatic.com https://shared.akamai.steamstatic.com https://store-images.s-microsoft.com http://127.0.0.1:17846; media-src 'self'; connect-src 'self' https://api.github.com https://cdn.jsdelivr.net http://127.0.0.1:17846 ws://127.0.0.1:17846; worker-src 'self'; manifest-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'; require-trusted-types-for 'script'; trusted-types openmouse
+  Content-Security-Policy: default-src 'self'; script-src 'self' https://us-assets.i.posthog.com; script-src-attr 'none'; style-src 'self' https://fonts.googleapis.com; style-src-attr 'none'; font-src 'self' data: https://fonts.gstatic.com; img-src 'self' data: blob: https://img.openmouse.app https://cdn.cloudflare.steamstatic.com https://shared.akamai.steamstatic.com https://store-images.s-microsoft.com http://127.0.0.1:17846; media-src 'self'; connect-src 'self' https://us.i.posthog.com https://us-assets.i.posthog.com https://api.github.com https://cdn.jsdelivr.net http://127.0.0.1:17846 ws://127.0.0.1:17846; worker-src 'self'; manifest-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'; require-trusted-types-for 'script'; trusted-types openmouse
   X-Content-Type-Options: nosniff
   X-Frame-Options: DENY
   Referrer-Policy: strict-origin-when-cross-origin

src/device/controller.ts

@@ -1,4 +1,5 @@
 import { emptyKeyboardWorkspace } from "./keyboard-workspace.ts";
+import { track, deviceProps, scrubError } from "../platform/analytics";
 import type { KeyboardCommand } from "./keyboard-workspace.ts";
 import { cachedBatterySamples, estimateBatteryTime, estimateFromRatedLife, ratedBattery, recordBatterySample, type BatteryMode } from "../features/devices/battery-history";
 import { bridgeEmptyResultMessage, isBridgeHidActive } from "../features/bridge/bridge-hid";
@@ -2244,6 +2245,7 @@ export async function flashPendingChanges(): Promise<void> {
     : st("ctl.flashedMany", { n: written });
   setReadStatus(flashed);
   pushToast("success", flashed);
+  track("pending_changes_applied", { change_count: written });
 }
 
 function endDeviceWrite(): void {
@@ -2366,7 +2368,15 @@ function recordDiagnosticCommand(command: string): void {
   renderDeviceDiagnostics(latestDiagnosticStatus);
 }
 
-function recordDiagnosticError(error: unknown, fallback: string): void {
+/** Model-level facts about the active device for analytics: no serials or ids. */
+function activeDeviceFacts(): { vendorId: number; productId: number; productName: string } | undefined {
+  return activeDevice
+    ? { vendorId: activeDevice.vendorId, productId: activeDevice.productId, productName: activeDevice.productName }
+    : undefined;
+}
+
+function recordDiagnosticError(error: unknown, fallback: string, report = true): void {
+  if (report) track("device_error", { ...deviceProps(activeDeviceFacts()), ...scrubError(error) });
   lastDiagnosticError = diagnosticErrorMessage(error, fallback);
   markHidActivity(lastDiagnosticError, { failed: true });
   renderDeviceDiagnostics(latestDiagnosticStatus);
@@ -2619,6 +2629,7 @@ export function downloadDiagnostics(): void {
   link.click();
   URL.revokeObjectURL(url);
   diagnosticDownloadStatus = st("ctl.savedName", { name });
+  track("diagnostics_downloaded");
   emit();
 }
 
@@ -3651,7 +3662,9 @@ function handleHidDisconnect(event: HIDConnectionEvent): void {
 }
 
 /** Ask the browser for a device, then pick the best keyboard or mouse client. */
-async function requestSupportedClient(): Promise<SupportedClient | KeyboardClient | null> {
+async function requestSupportedClient(
+  onSelected?: (device: HIDDevice) => void,
+): Promise<SupportedClient | KeyboardClient | null> {
   if (!navigator.hid) throw new Error(st("ctl.noWebHid"));
   const devices = await navigator.hid.requestDevice({ filters: HID_FILTERS });
   if (devices.length === 0) {
@@ -3667,6 +3680,9 @@ async function requestSupportedClient(): Promise<SupportedClient | KeyboardClien
     }
     return null;
   }
+  // Remember what was picked now, so a failure reports this device and not
+  // whichever one happens to be active when the error lands.
+  onSelected?.(devices[0]);
 
   if (devices.some((device) => eggWeIsSupported(device))) {
     const weClient = eggWeFromAuthorized(await eggWeAuthorizedPool(devices));
@@ -3764,8 +3780,11 @@ export async function connect(): Promise<void> {
   readStatus = st("ctl.choosePrompt");
   emit();
 
+  let attempted: { vendorId: number; productId: number; productName: string } | undefined;
   try {
-    const client = await requestSupportedClient();
+    const client = await requestSupportedClient((device) => {
+      attempted = { vendorId: device.vendorId, productId: device.productId, productName: device.productName };
+    });
     if (!client) {
       deviceStatusText = st("ctl.notConnected");
       readStatus = st("ctl.noSelection");
@@ -3779,10 +3798,15 @@ export async function connect(): Promise<void> {
     });
     emit();
     await activateClient(client);
+    track("device_connected", deviceProps(attempted));
   } catch (error) {
     const message = error instanceof Error ? error.message : "Unable to read the mouse.";
     const wrongDevice = error instanceof NotAMouseError;
-    if (!wrongDevice) recordDiagnosticError(error, message);
+    if (!wrongDevice) recordDiagnosticError(error, message, false);
+    track(wrongDevice ? "device_not_a_mouse" : "device_connection_failed", {
+      ...deviceProps(attempted),
+      ...scrubError(error),
+    });
     if (eggClient() ?? eggWeClient()) {
       await active?.close().catch(() => undefined);
       active = null;

src/features/games/GameRequestDialog.tsx

@@ -1,4 +1,5 @@
 import { displayText } from "../../i18n/index";
+import { track } from "../../platform/analytics";
 import { useUiLocale } from "../../shared/ui-locale";
 import { useEffect, useRef, useState, type ReactNode } from "react";
 import { Check, Copy, Gamepad2 } from "lucide-react";
@@ -215,6 +216,7 @@ export function GameRequestDialog({ open, onClose, locale = "en", bridgeActive,
         /* the cooldown is a courtesy; storage failures just skip it */
       }
       control.pushToast("success", t(locale, "gamereq.sent"), tp(locale, "gamereq.sentDetail", { name: trimmedName }));
+      track("game_request_submitted", { request_kind: kind });
       setName("");
       setPath("");
       onClose();

src/features/hardware-test/HardwareTestPage.tsx

@@ -1,4 +1,5 @@
 import { displayText } from "../../i18n/index";
+import { track } from "../../platform/analytics";
 import { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
 import * as control from "../../device/controller";
 import type { ControlSnapshot } from "../../device/types";
@@ -106,6 +107,7 @@ export function HardwareTestPage({ snapshot }: { snapshot: ControlSnapshot }): R
     setStages([]);
     setLiveSample(null);
     setSamplingElapsedMs(0);
+    track("hardware_test_started");
 
     void (async () => {
       let info = deviceInfoFromSnapshot(snapshot);
@@ -372,6 +374,7 @@ export function HardwareTestPage({ snapshot }: { snapshot: ControlSnapshot }): R
         build: snapshot.buildLabel,
         supportedPage: crosscheckSupportedDevices(info, verdict),
       });
+      track("hardware_test_completed", { verdict });
     })().catch(() => {
       addStage({ kind: "check", label: "The suite crashed — restart the test", state: "fail" });
       setReport(null);
@@ -393,6 +396,7 @@ export function HardwareTestPage({ snapshot }: { snapshot: ControlSnapshot }): R
     anchor.click();
     anchor.remove();
     URL.revokeObjectURL(url);
+    track("hardware_test_report_downloaded");
   }, [report, running]);
 
   // Opens the WebHID/Bridge device picker and connects the chosen mouse.

src/features/settings/InterfaceSettings.tsx

@@ -1,4 +1,5 @@
 import { displayText } from "../../i18n/index";
+import { analyticsAvailable, analyticsEnabled, setAnalyticsEnabled, track } from "../../platform/analytics";
 import { Globe, RotateCcw } from "lucide-react";
 import { useState, type ReactNode } from "react";
 import * as control from "../../device/controller";
@@ -48,6 +49,7 @@ export function ProfileKeyFields({ snapshot }: { snapshot: ControlSnapshot }): R
           onClick={() => {
             if (!key) return;
             void navigator.clipboard.writeText(key).then(() => {
+              track("profile_key_copied");
               setCopied(true);
               setTimeout(() => setCopied(false), 1500);
             });
@@ -116,6 +118,7 @@ function SettingsGroup({ id, title, children }: { id: string; title: string; chi
 export function InterfaceSettings({ snapshot }: { snapshot: ControlSnapshot }): ReactNode {
   const preferences = snapshot.preferences;
   const locale = preferences.locale;
+  const [analyticsOn, setAnalyticsOn] = useState(analyticsEnabled);
   const set = <K extends keyof typeof preferences>(key: K) => (value: (typeof preferences)[K]): void =>
     control.setPreference(key, value);
 
@@ -192,6 +195,12 @@ export function InterfaceSettings({ snapshot }: { snapshot: ControlSnapshot }):
         {toggle("interface-sounds", t(locale, "set.soundTitle"), t(locale, "set.soundDescription"), preferences.enabledSounds, set("enabledSounds"))}
         {toggle("interface-expand-sections", t(locale, "set.advancedEditors"), t(locale, "set.advancedEditorsBody"), preferences.expandSections, set("expandSections"))}
         {toggle("interface-show-experimental", t(locale, "set.experimentalTitle"), t(locale, "set.experimentalBody"), preferences.showExperimental, set("showExperimental"))}
+        {analyticsAvailable
+          ? toggle("interface-analytics", t(locale, "set.analytics"), t(locale, "set.analyticsBody"), analyticsOn, (next) => {
+              setAnalyticsEnabled(next);
+              setAnalyticsOn(next);
+            })
+          : null}
       </SettingsGroup>
 
       <SettingsGroup id="settings-profile-key" title={t(locale, "set.profileKey")}>