From cd55732072163c75f2c8598e63e3797c88fdad48 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Fri, 6 Nov 2026 11:11:30 +0000
Subject: [PATCH] feat: add live client OS detection and compatibility warnings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The plugin page now tells the visitor whether an extension supports their
machine before they try to install it, which matters for tools like
saturn-patcher that ship Windows and Linux builds only.

- src/lib/detectOS.ts: pure detection and compatibility logic (Windows, macOS,
  Linux, Android, plus iOS and Unknown). Runs on the server and in the browser
  so the two can never disagree.
- src/lib/compat-client.ts: browser entry that re-checks against
  navigator.userAgent and corrects the pill.
- src/pages/plugin/[id].astro: renders the pill above the action buttons and
  adds a "Download anyway for another PC" link when the OS is unsupported.
- src/components/Icon.astro: adds check-circle and alert-triangle.

The server renders the pill from the request User-Agent, so it is correct on
first paint and cannot shift layout. The client only ever toggles `hidden` on
nodes that are always in the DOM, so a correction cannot shift layout either.
It exists for iPadOS, which reports a Macintosh User-Agent but is really iOS —
maxTouchPoints is the only tell and the server cannot see it.

An unreadable User-Agent, or a plugin with no platform data, renders nothing
rather than guessing. Tests cover both layers, including the iPadOS correction.

Co-authored-by: openhands <openhands@all-hands.dev>
---
 src/components/Icon.astro   |   3 +
 src/lib/compat-client.ts    |  69 +++++++++++++++
 src/lib/detectOS.ts         | 105 +++++++++++++++++++++++
 src/pages/plugin/[id].astro |  91 ++++++++++++++++++++
 tests/compat-client.test.ts | 163 ++++++++++++++++++++++++++++++++++++
 tests/detectOS.test.ts      | 105 +++++++++++++++++++++++
 6 files changed, 536 insertions(+)
 create mode 100644 src/lib/compat-client.ts
 create mode 100644 src/lib/detectOS.ts
 create mode 100644 tests/compat-client.test.ts
 create mode 100644 tests/detectOS.test.ts

diff --git a/src/components/Icon.astro b/src/components/Icon.astro
index 36118cf..e96fa90 100644
--- a/src/components/Icon.astro
+++ b/src/components/Icon.astro
@@ -26,6 +26,9 @@ const ICONS: Record<string, string> = {
   layers:
     '<path d="m12.83 2.18a2 2 0 0 0-1.66 0L2.6 6.08a1 1 0 0 0 0 1.83l8.58 3.91a2 2 0 0 0 1.66 0l8.58-3.9a1 1 0 0 0 0-1.83Z"/><path d="m22 17.65-9.17 4.16a2 2 0 0 1-1.66 0L2 17.65"/><path d="m22 12.65-9.17 4.16a2 2 0 0 1-1.66 0L2 12.65"/>',
   'shield-check': '<path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z"/><path d="m9 12 2 2 4-4"/>',
+  'alert-triangle':
+    '<path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><line x1="12" x2="12" y1="9" y2="13"/><line x1="12" x2="12.01" y1="17" y2="17"/>',
+  'check-circle': '<circle cx="12" cy="12" r="10"/><path d="m9 12 2 2 4-4"/>',
   wrench: '<path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"/>',
   cpu: '<rect width="16" height="16" x="4" y="4" rx="2"/><rect width="6" height="6" x="9" y="9" rx="1"/><path d="M15 2v2M15 20v2M2 15h2M2 9h2M20 15h2M20 9h2M9 2v2M9 20v2"/>',
   sparkles:
diff --git a/src/lib/compat-client.ts b/src/lib/compat-client.ts
new file mode 100644
index 0000000..7d6d699
--- /dev/null
+++ b/src/lib/compat-client.ts
@@ -0,0 +1,69 @@
+/**
+ * Browser entry for the plugin compatibility pill.
+ *
+ * The server renders the pill from the request `User-Agent` so the layout is
+ * final on first paint. This re-runs the same check against
+ * `navigator.userAgent` and corrects the pill if the two disagree — the usual
+ * cause being iPadOS in desktop mode, which reports a Macintosh User-Agent but
+ * is really iOS.
+ *
+ * Corrections only ever toggle `hidden` on nodes that are always in the DOM, so
+ * a correction cannot change the element's height and shift the layout.
+ *
+ * This module touches the DOM, so it is only imported from `<script>` blocks
+ * (which Vite bundles for the client); it must never be imported from server code.
+ */
+
+import { compatibilityFor, detectOS, supportedLabel, type Compatibility } from './detectOS.ts';
+
+/** Base shell classes, kept in sync with the server-rendered markup. */
+const SHELL_BASE = 'rounded-xl border p-4';
+const SHELL_VARIANT: Record<Exclude<Compatibility, 'unknown'>, string> = {
+  compatible: 'border-emerald-500/40 bg-emerald-500/10 shadow-[0_0_25px_rgba(16,185,129,0.15)]',
+  incompatible: 'border-amber-500/40 bg-amber-500/10 shadow-[0_0_25px_rgba(245,158,11,0.12)]',
+};
+
+function setHidden(element: Element | null, hidden: boolean): void {
+  if (element) element.classList.toggle('hidden', hidden);
+}
+
+function apply(root: HTMLElement, state: Compatibility, os: string, platforms: string[]): void {
+  root.dataset.compatState = state;
+
+  const shell = root.querySelector<HTMLElement>('[data-compat-shell]');
+  if (shell) {
+    shell.className =
+      state === 'unknown' ? `${SHELL_BASE} hidden` : `${SHELL_BASE} ${SHELL_VARIANT[state]}`;
+  }
+
+  setHidden(root.querySelector('[data-compat-icon="compatible"]'), state !== 'compatible');
+  setHidden(root.querySelector('[data-compat-icon="incompatible"]'), state !== 'incompatible');
+  setHidden(root.querySelector('[data-compat-supported]'), state !== 'incompatible');
+  // Sits below the action buttons, outside this root, so it is matched globally.
+  setHidden(document.querySelector('[data-compat-download-anyway]'), state !== 'incompatible');
+
+  const text = root.querySelector<HTMLElement>('[data-compat-text]');
+  if (text) {
+    text.textContent =
+      state === 'compatible'
+        ? `✅ Compatible with your system (${os})`
+        : state === 'incompatible'
+          ? `⚠️ Not compatible with your current OS (${os})`
+          : '';
+    text.classList.toggle('text-emerald-300', state === 'compatible');
+    text.classList.toggle('text-amber-300', state === 'incompatible');
+  }
+
+  const supported = root.querySelector<HTMLElement>('[data-compat-platforms]');
+  if (supported) supported.textContent = supportedLabel(platforms);
+}
+
+export function initCompatibility(root: HTMLElement): void {
+  const platforms = (root.dataset.platforms ?? '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+  const os = detectOS(navigator.userAgent, { maxTouchPoints: navigator.maxTouchPoints });
+  apply(root, compatibilityFor(os, platforms), os, platforms);
+}
diff --git a/src/lib/detectOS.ts b/src/lib/detectOS.ts
new file mode 100644
index 0000000..9931302
--- /dev/null
+++ b/src/lib/detectOS.ts
@@ -0,0 +1,105 @@
+/**
+ * Visitor OS detection and plugin compatibility.
+ *
+ * The same pure functions run in two places:
+ *   - the server, against the request's `User-Agent`, so the compatibility pill
+ *     is already correct on first paint (no layout shift), and
+ *   - the browser, against `navigator.userAgent`, as the authoritative check.
+ *
+ * Keeping one implementation means the two can never disagree about what a UA
+ * string means.
+ */
+
+export type DetectedOS = 'Windows' | 'macOS' | 'Linux' | 'Android' | 'iOS' | 'Unknown';
+
+/**
+ * `compatible` / `incompatible` are claims we can defend from a UA string.
+ * `unknown` is the honest answer when we cannot tell — the caller renders
+ * nothing rather than guessing.
+ */
+export type Compatibility = 'compatible' | 'incompatible' | 'unknown';
+
+/** A plugin tagged with this runs everywhere; it is a storefront convention, not a real OS. */
+export const ALL_PLATFORMS = 'All Platforms';
+
+/**
+ * The storefront label each OS matches in `platforms_json`.
+ * `null` means the storefront never publishes a build for that platform, so a
+ * plugin can never be compatible with it (iOS ships no `.orplug` binaries).
+ */
+const PLATFORM_LABEL: Record<DetectedOS, string | null> = {
+  Windows: 'Windows',
+  macOS: 'macOS',
+  Linux: 'Linux',
+  Android: 'Android',
+  iOS: null,
+  Unknown: null,
+};
+
+export interface DetectOptions {
+  /**
+   * `navigator.maxTouchPoints`. iPadOS 13+ reports a desktop `Macintosh`
+   * User-Agent, so the only client-side tell is a touch-capable "Mac". The
+   * server cannot see this, which is exactly why the browser re-checks.
+   */
+  maxTouchPoints?: number;
+}
+
+/**
+ * Classify a User-Agent string. Order matters: an Android UA also contains
+ * "Linux", and ChromeOS contains "Linux" too, so the more specific tokens are
+ * tested first.
+ */
+export function detectOS(
+  userAgent: string | null | undefined,
+  options: DetectOptions = {},
+): DetectedOS {
+  const ua = (userAgent ?? '').toLowerCase();
+  if (!ua) return 'Unknown';
+
+  if (ua.includes('android')) return 'Android';
+  if (/(iphone|ipod)/.test(ua)) return 'iOS';
+  // An explicit "iPad" UA (older iPadOS) also contains "like Mac OS X", so it
+  // must be tested before the Mac branch below.
+  if (ua.includes('ipad')) return 'iOS';
+
+  const looksLikeMac = ua.includes('mac os x') || ua.includes('macintosh');
+  if (looksLikeMac) {
+    // An iPad in desktop mode (iPadOS 13+) reports a desktop Safari UA with no
+    // "iPad" token; a touch-capable "Macintosh" is the only tell.
+    if ((options.maxTouchPoints ?? 0) > 1) return 'iOS';
+    return 'macOS';
+  }
+
+  if (ua.includes('windows')) return 'Windows';
+  // ChromeOS UAs end in "CrOS ... Linux", so treat them as Linux desktops.
+  if (ua.includes('linux') || ua.includes('x11') || ua.includes('cros')) return 'Linux';
+
+  return 'Unknown';
+}
+
+/**
+ * Decide whether a plugin supports the detected OS.
+ *
+ * An empty platform list means we have no compatibility data to stand on, so we
+ * say `unknown` instead of implying the plugin works everywhere.
+ */
+export function compatibilityFor(
+  detected: DetectedOS,
+  platforms: readonly string[] | null | undefined,
+): Compatibility {
+  if (detected === 'Unknown') return 'unknown';
+
+  const list = (platforms ?? []).filter((platform): platform is string => Boolean(platform));
+  if (list.length === 0) return 'unknown';
+  if (list.includes(ALL_PLATFORMS)) return 'compatible';
+
+  const label = PLATFORM_LABEL[detected];
+  if (!label) return 'incompatible';
+  return list.includes(label) ? 'compatible' : 'incompatible';
+}
+
+/** Human-readable "Only available on: …" list, in the order the plugin declares. */
+export function supportedLabel(platforms: readonly string[] | null | undefined): string {
+  return (platforms ?? []).filter(Boolean).join(', ');
+}
diff --git a/src/pages/plugin/[id].astro b/src/pages/plugin/[id].astro
index e6fb5b1..68dc19c 100644
--- a/src/pages/plugin/[id].astro
+++ b/src/pages/plugin/[id].astro
@@ -12,6 +12,7 @@ import {
   orskinFileName,
 } from '../../lib/theme';
 import { renderMarkdown } from '../../lib/markdown';
+import { compatibilityFor, detectOS, supportedLabel } from '../../lib/detectOS';
 
 export const prerender = false;
 
@@ -80,6 +81,14 @@ const manifest = plugin
     }
   : null;
 
+// Compatibility is decided from the request's User-Agent so the pill is correct
+// on first paint. The client re-checks against navigator.userAgent and corrects
+// it (iPadOS in desktop mode reports a Macintosh UA), which is why the server
+// result is only a starting point.
+const detectedOS = detectOS(Astro.request.headers.get('user-agent'));
+const compatibility = plugin ? compatibilityFor(detectedOS, plugin.platforms) : 'unknown';
+const supportedText = plugin ? supportedLabel(plugin.platforms) : '';
+
 const heading = dbError ? 'Plugin unavailable' : 'Plugin not found';
 const displayHeading = dbError
   ? 'Plugin unavailable'
@@ -188,6 +197,68 @@ const body = dbError
             </div>
           </div>
 
+          {/* Live OS compatibility. The server renders it from the request
+              User-Agent so it is correct on first paint; the client re-checks
+              and only toggles `hidden` on whole nodes, so a correction can never
+              shift the layout. */}
+          <div
+            class="mt-6"
+            data-compat
+            data-compat-state={compatibility}
+            data-platforms={plugin.platforms.join(',')}
+          >
+            <div
+              data-compat-shell
+              class:list={[
+                'rounded-xl border p-4',
+                compatibility === 'compatible' &&
+                  'border-emerald-500/40 bg-emerald-500/10 shadow-[0_0_25px_rgba(16,185,129,0.15)]',
+                compatibility === 'incompatible' &&
+                  'border-amber-500/40 bg-amber-500/10 shadow-[0_0_25px_rgba(245,158,11,0.12)]',
+                compatibility === 'unknown' && 'hidden',
+              ]}
+            >
+              <div class="flex items-start gap-2.5">
+                <span
+                  data-compat-icon="compatible"
+                  class:list={['shrink-0', compatibility !== 'compatible' && 'hidden']}
+                >
+                  <Icon name="check-circle" class="h-5 w-5 text-emerald-400" />
+                </span>
+                <span
+                  data-compat-icon="incompatible"
+                  class:list={['shrink-0', compatibility !== 'incompatible' && 'hidden']}
+                >
+                  <Icon name="alert-triangle" class="h-5 w-5 text-amber-400" />
+                </span>
+                <div class="min-w-0">
+                  <p
+                    data-compat-text
+                    class:list={[
+                      'text-sm font-medium',
+                      compatibility === 'compatible' && 'text-emerald-300',
+                      compatibility === 'incompatible' && 'text-amber-300',
+                    ]}
+                  >
+                    {compatibility === 'compatible'
+                      ? `✅ Compatible with your system (${detectedOS})`
+                      : compatibility === 'incompatible'
+                        ? `⚠️ Not compatible with your current OS (${detectedOS})`
+                        : ''}
+                  </p>
+
+                  <p
+                    data-compat-supported
+                    class:list={['mt-2 text-sm text-zinc-400', compatibility !== 'incompatible' && 'hidden']}
+                  >
+                    Only available on:{' '}
+                    <span class="font-medium text-zinc-300" data-compat-platforms>{supportedText}</span>
+                  </p>
+                </div>
+              </div>
+            </div>
+          </div>
+
           {/* Actions */}
           <div class="mt-6 flex flex-wrap items-center gap-3">
             {published ? (
@@ -254,6 +325,22 @@ const body = dbError
             )
           }
 
+          {/* The download stays available when the visitor's OS is not supported,
+              but the label says what they are getting so it is a deliberate choice. */}
+          <p
+            data-compat-download-anyway
+            class:list={[
+              'mt-3 text-xs text-zinc-500',
+              compatibility !== 'incompatible' && 'hidden',
+            ]}
+          >
+            Downloading anyway?{' '}
+            <a href={`/api/download/${plugin.id}`} class="text-amber-400 hover:underline">
+              Download anyway for another PC
+            </a>
+            .
+          </p>
+
           {/* Quick facts */}
           <dl class="mt-6 flex flex-wrap items-center gap-x-6 gap-y-3 border-t border-zinc-800/70 pt-5 text-xs text-zinc-500">
             <div class="flex items-center gap-1.5">
@@ -605,6 +692,10 @@ const body = dbError
         </div>
       </main>
       <script>
+        import { initCompatibility } from '../../lib/compat-client';
+
+        document.querySelectorAll<HTMLElement>('[data-compat]').forEach(initCompatibility);
+
         document.addEventListener('click', async (event) => {
           const trigger = (event.target as HTMLElement).closest<HTMLElement>('[data-copy]');
           if (!trigger) return;
diff --git a/tests/compat-client.test.ts b/tests/compat-client.test.ts
new file mode 100644
index 0000000..94af332
--- /dev/null
+++ b/tests/compat-client.test.ts
@@ -0,0 +1,163 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { initCompatibility } from '../src/lib/compat-client.ts';
+
+/**
+ * A deliberately tiny DOM stand-in. Node has no DOM and this repo has no jsdom
+ * dependency, so the element behaviour `initCompatibility` relies on — attribute
+ * lookup, `classList` toggling, `className`, `dataset` and `textContent` — is
+ * faked here. The detection and compatibility logic it calls is the real code.
+ */
+class FakeClassList {
+  constructor(element: FakeElement) {
+    this.element = element;
+  }
+  private element: FakeElement;
+  add(...tokens: string[]) {
+    for (const token of tokens) this.element.tokens.add(token);
+  }
+  remove(...tokens: string[]) {
+    for (const token of tokens) this.element.tokens.delete(token);
+  }
+  toggle(token: string, force?: boolean) {
+    const on = force ?? !this.element.tokens.has(token);
+    if (on) this.element.tokens.add(token);
+    else this.element.tokens.delete(token);
+    return on;
+  }
+  contains(token: string) {
+    return this.element.tokens.has(token);
+  }
+}
+
+class FakeElement {
+  attrs: Record<string, string> = {};
+  children: FakeElement[] = [];
+  tokens = new Set<string>();
+  dataset: Record<string, string> = {};
+  textContent = '';
+  classList = new FakeClassList(this);
+
+  constructor(attrs: Record<string, string> = {}) {
+    this.attrs = attrs;
+  }
+
+  add(child: FakeElement): FakeElement {
+    this.children.push(child);
+    return child;
+  }
+
+  get className(): string {
+    return [...this.tokens].join(' ');
+  }
+  set className(value: string) {
+    this.tokens = new Set(value.split(/\s+/).filter(Boolean));
+  }
+
+  /** Supports the two selector shapes the client uses: `[data-x]` and `[data-x="v"]`. */
+  private matches(selector: string): boolean {
+    const match = /^\[([\w-]+)(?:="([^"]*)")?\]$/.exec(selector);
+    if (!match) throw new Error(`unsupported selector in test: ${selector}`);
+    const [, name, value] = match;
+    if (!(name in this.attrs)) return false;
+    return value === undefined || this.attrs[name] === value;
+  }
+
+  querySelectorAll(selector: string): FakeElement[] {
+    const found: FakeElement[] = [];
+    for (const child of this.children) {
+      if (child.matches(selector)) found.push(child);
+      found.push(...child.querySelectorAll(selector));
+    }
+    return found;
+  }
+
+  querySelector(selector: string): FakeElement | null {
+    return this.querySelectorAll(selector)[0] ?? null;
+  }
+}
+
+/** Mirror the markup the plugin page renders, so the selectors must line up. */
+function buildTree() {
+  const root = new FakeElement({ 'data-compat': '' });
+  root.dataset.platforms = 'Windows,Linux';
+
+  const shell = root.add(new FakeElement({ 'data-compat-shell': '' }));
+  const iconCompatible = shell.add(new FakeElement({ 'data-compat-icon': 'compatible' }));
+  const iconIncompatible = shell.add(new FakeElement({ 'data-compat-icon': 'incompatible' }));
+  const text = shell.add(new FakeElement({ 'data-compat-text': '' }));
+  const supported = shell.add(new FakeElement({ 'data-compat-supported': '' }));
+  supported.add(new FakeElement({ 'data-compat-platforms': '' }));
+
+  const downloadAnyway = new FakeElement({ 'data-compat-download-anyway': '' });
+
+  // The client looks the "download anyway" node up globally because it sits
+  // outside the `[data-compat]` root; the stub only needs that one query.
+  const document = {
+    querySelector: (selector: string) =>
+      selector === '[data-compat-download-anyway]' ? downloadAnyway : null,
+  };
+
+  return { root, shell, iconCompatible, iconIncompatible, text, supported, downloadAnyway, document };
+}
+
+function withNavigator(userAgent: string, maxTouchPoints: number) {
+  Object.defineProperty(globalThis, 'navigator', {
+    value: { userAgent, maxTouchPoints },
+    configurable: true,
+  });
+}
+
+const LINUX_UA = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/141 Safari/537.36';
+const MAC_UA =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Version/18.0 Safari/605.1.15';
+
+function run(userAgent: string, maxTouchPoints = 0) {
+  const tree = buildTree();
+  withNavigator(userAgent, maxTouchPoints);
+  (globalThis as Record<string, unknown>).document = tree.document;
+  initCompatibility(tree.root as unknown as HTMLElement);
+  return tree;
+}
+
+test('client renders the compatible state and hides the warning nodes', () => {
+  const t = run(LINUX_UA);
+  assert.equal(t.root.dataset.compatState, 'compatible');
+  assert.equal(t.shell.classList.contains('hidden'), false);
+  assert.equal(t.shell.classList.contains('border-emerald-500/40'), true);
+  assert.equal(t.iconCompatible.classList.contains('hidden'), false);
+  assert.equal(t.iconIncompatible.classList.contains('hidden'), true);
+  assert.equal(t.supported.classList.contains('hidden'), true);
+  assert.equal(t.downloadAnyway.classList.contains('hidden'), true);
+  assert.equal(t.text.textContent, '✅ Compatible with your system (Linux)');
+  assert.equal(t.text.classList.contains('text-emerald-300'), true);
+});
+
+test('client flips to the incompatible state when the OS is not supported', () => {
+  // Server would have said compatible for a Windows list; the client corrects it.
+  const t = run(MAC_UA);
+  assert.equal(t.root.dataset.compatState, 'incompatible');
+  assert.equal(t.shell.classList.contains('border-amber-500/40'), true);
+  assert.equal(t.iconCompatible.classList.contains('hidden'), true);
+  assert.equal(t.iconIncompatible.classList.contains('hidden'), false);
+  assert.equal(t.supported.classList.contains('hidden'), false);
+  assert.equal(t.downloadAnyway.classList.contains('hidden'), false);
+  assert.equal(t.text.textContent, '⚠️ Not compatible with your current OS (macOS)');
+  assert.equal(t.text.classList.contains('text-amber-300'), true);
+});
+
+test('client corrects a Macintosh UA to iOS on a touch-capable device', () => {
+  // iPadOS 13+ reports a desktop Macintosh UA; maxTouchPoints is the only tell.
+  const t = run(MAC_UA, 5);
+  assert.equal(t.root.dataset.compatState, 'incompatible');
+  assert.equal(t.text.textContent, '⚠️ Not compatible with your current OS (iOS)');
+});
+
+test('client hides everything when the UA cannot be identified', () => {
+  const t = run('curl/8.7.1');
+  assert.equal(t.root.dataset.compatState, 'unknown');
+  assert.equal(t.shell.classList.contains('hidden'), true);
+  assert.equal(t.downloadAnyway.classList.contains('hidden'), true);
+  assert.equal(t.text.textContent, '');
+});
diff --git a/tests/detectOS.test.ts b/tests/detectOS.test.ts
new file mode 100644
index 0000000..a9f4510
--- /dev/null
+++ b/tests/detectOS.test.ts
@@ -0,0 +1,105 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  ALL_PLATFORMS,
+  compatibilityFor,
+  detectOS,
+  supportedLabel,
+} from '../src/lib/detectOS.ts';
+
+// Real User-Agent strings, trimmed to the parts that matter.
+const UA = {
+  windows:
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36',
+  macOS:
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Safari/605.1.15',
+  linux:
+    'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36',
+  android:
+    'Mozilla/5.0 (Linux; Android 15; Pixel 9) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Mobile Safari/537.36',
+  iphone:
+    'Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1',
+  ipadLegacy:
+    'Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
+  chromeOS:
+    'Mozilla/5.0 (X11; CrOS x86_64 14541.0.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36',
+  firefoxLinux:
+    'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:132.0) Gecko/20100101 Firefox/132.0',
+};
+
+test('detectOS classifies the common desktop and mobile platforms', () => {
+  assert.equal(detectOS(UA.windows), 'Windows');
+  assert.equal(detectOS(UA.macOS), 'macOS');
+  assert.equal(detectOS(UA.linux), 'Linux');
+  assert.equal(detectOS(UA.firefoxLinux), 'Linux');
+  assert.equal(detectOS(UA.android), 'Android');
+  assert.equal(detectOS(UA.iphone), 'iOS');
+});
+
+test('detectOS prefers Android over the Linux token it also carries', () => {
+  // An Android UA contains "Linux"; the more specific token must win.
+  assert.match(UA.android, /Linux/);
+  assert.equal(detectOS(UA.android), 'Android');
+});
+
+test('detectOS treats ChromeOS as a Linux desktop', () => {
+  assert.equal(detectOS(UA.chromeOS), 'Linux');
+});
+
+test('detectOS recognises an explicit iPad UA as iOS', () => {
+  assert.equal(detectOS(UA.ipadLegacy), 'iOS');
+});
+
+test('detectOS reads a touch-capable Macintosh as iPadOS, not macOS', () => {
+  // iPadOS 13+ reports a desktop Safari UA; only maxTouchPoints gives it away.
+  assert.equal(detectOS(UA.macOS), 'macOS');
+  assert.equal(detectOS(UA.macOS, { maxTouchPoints: 0 }), 'macOS');
+  assert.equal(detectOS(UA.macOS, { maxTouchPoints: 5 }), 'iOS');
+  // A real Mac with a trackpad reports 0 touch points, so it stays macOS.
+  assert.equal(detectOS(UA.macOS, { maxTouchPoints: 1 }), 'macOS');
+});
+
+test('detectOS returns Unknown for missing or unrecognised agents', () => {
+  for (const value of [null, undefined, '', 'curl/8.7.1', 'SomeCrawler/1.0']) {
+    assert.equal(detectOS(value), 'Unknown', `${value} should be Unknown`);
+  }
+});
+
+test('compatibilityFor matches the OS against the platform list', () => {
+  const saturn = ['Windows', 'Linux'];
+  assert.equal(compatibilityFor('Windows', saturn), 'compatible');
+  assert.equal(compatibilityFor('Linux', saturn), 'compatible');
+  assert.equal(compatibilityFor('macOS', saturn), 'incompatible');
+  assert.equal(compatibilityFor('Android', saturn), 'incompatible');
+});
+
+test('compatibilityFor treats All Platforms as compatible everywhere', () => {
+  for (const os of ['Windows', 'macOS', 'Linux', 'Android'] as const) {
+    assert.equal(compatibilityFor(os, [ALL_PLATFORMS]), 'compatible');
+  }
+  // A theme tagged All Platforms alongside a real OS is still compatible.
+  assert.equal(compatibilityFor('macOS', [ALL_PLATFORMS, 'Windows']), 'compatible');
+});
+
+test('compatibilityFor is Unknown when we cannot judge', () => {
+  // No platform data at all — do not claim compatibility.
+  assert.equal(compatibilityFor('Windows', []), 'unknown');
+  assert.equal(compatibilityFor('Windows', null), 'unknown');
+  assert.equal(compatibilityFor('Windows', undefined), 'unknown');
+  // An unreadable UA cannot be judged even with a full platform list.
+  assert.equal(compatibilityFor('Unknown', ['Windows', 'Linux']), 'unknown');
+});
+
+test('compatibilityFor never claims compatibility for iOS', () => {
+  // The storefront ships no iOS builds, so iOS is always incompatible.
+  assert.equal(compatibilityFor('iOS', ['Windows', 'Linux', 'macOS']), 'incompatible');
+  assert.equal(compatibilityFor('iOS', [ALL_PLATFORMS]), 'compatible');
+});
+
+test('supportedLabel joins the declared platforms in order', () => {
+  assert.equal(supportedLabel(['Windows', 'Linux']), 'Windows, Linux');
+  assert.equal(supportedLabel(['Windows']), 'Windows');
+  assert.equal(supportedLabel([]), '');
+  assert.equal(supportedLabel(null), '');
+});