fix(core): read a blank client-hints platform as unknown, not as non-Apple

`isApplePlatform()` in `useHotkeys` and `detectMac()` in `Kbd` both prefer
`navigator.userAgentData.platform` and fall back to `navigator.platform`.
The guard on that preference was `'platform' in uaData`, true whenever the
key exists at all, blank or not. A build reporting `platform: ''` committed
to the client-hints branch, evaluated `/mac/i.test('')`, and got `false`
without ever reaching the fallback that would have answered correctly. An
empty string was read as "not Apple" rather than as "no answer".

Electron and other embedders that rewrite the app's user-agent or
client-hints identity ship exactly that. On macOS every `mod` combo
registered through `useHotkeys` listened for Ctrl instead of Cmd, and every
`<Kbd>` drew Ctrl. Both surfaces agreed with each other, so nothing looked
broken: the shortcut never fired, and the hint named the key that also did
not work.

A blank platform now falls through to `navigator.platform`. Both call sites
change in this one commit, since the `useHotkeys` docstring states it
mirrors the detection used by `Kbd` so displayed and handled shortcuts
agree.

Fixes #5253

Author: Astro-Han

.changeset/kbd-hotkeys-blank-client-hints-platform.md

@@ -0,0 +1,27 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `mod` hotkeys and `Kbd` resolve to Cmd on macOS again when client hints report a blank platform
+
+`isApplePlatform()` in `useHotkeys` and `detectMac()` in `Kbd` both prefer
+`navigator.userAgentData.platform` and fall back to `navigator.platform`. The
+guard on that preference was `'platform' in uaData`, which is true whenever the
+key exists at all, blank or not. A build that reports `platform: ''` therefore
+committed to the client-hints branch, evaluated `/mac/i.test('')`, and got
+`false` without ever reaching the fallback that would have answered correctly.
+An empty string was being read as "not Apple" rather than as "no answer".
+
+Electron and other embedders that rewrite the app's user-agent or client-hints
+identity ship exactly that. On macOS the result was that every `mod` combo
+registered through `useHotkeys` listened for Ctrl instead of Cmd, and every
+`<Kbd>` drew Ctrl. Both surfaces agreed with each other, so nothing looked
+broken: the shortcut simply never fired, and the hint named the key that also
+did not work.
+
+A blank platform is now treated as unknown and falls through to
+`navigator.platform`. Both call sites change together, since the `useHotkeys`
+docstring states it mirrors the detection used by `Kbd` so displayed and
+handled shortcuts agree.
+
+@Astro-Han

packages/core/src/Kbd/Kbd.test.tsx

@@ -23,8 +23,25 @@ describe('Kbd', () => {
       value: originalPlatform,
       configurable: true,
     });
+    delete (navigator as {userAgentData?: unknown}).userAgentData;
   });
 
+  function spoofPlatform(platform: string) {
+    Object.defineProperty(navigator, 'platform', {
+      value: platform,
+      configurable: true,
+    });
+  }
+
+  function spoofBlankClientHints() {
+    // Builds that rewrite their client-hints identity expose the key with an
+    // empty value; navigator.platform is the only surface left that answers.
+    Object.defineProperty(navigator, 'userAgentData', {
+      value: {platform: ''},
+      configurable: true,
+    });
+  }
+
   it('renders a single key', () => {
     render(<Kbd keys="k" />);
     const kbd = screen.getByText('K');
@@ -54,6 +71,22 @@ describe('Kbd', () => {
     expect(screen.getByText('\u2318')).toBeInTheDocument(); // \u2318
   });
 
+  it('reads a blank userAgentData.platform as unknown, not as non-Mac', () => {
+    spoofBlankClientHints();
+    spoofPlatform('MacIntel');
+
+    render(<Kbd keys="mod" />);
+    expect(screen.getByText('\u2318')).toBeInTheDocument();
+  });
+
+  it('still renders Ctrl when both platform surfaces are non-Mac', () => {
+    spoofBlankClientHints();
+    spoofPlatform('Win32');
+
+    render(<Kbd keys="mod" />);
+    expect(screen.getByText('Ctrl')).toBeInTheDocument();
+  });
+
   it('maps modifier keys to symbols', () => {
     render(<Kbd keys="ctrl+alt+shift+k" />);
     expect(screen.getByText('\u2303')).toBeInTheDocument(); // \u2303

packages/core/src/Kbd/Kbd.tsx

@@ -124,8 +124,9 @@ function getServerPlatformSnapshot(): boolean {
 
 /**
  * Detects whether the current platform is macOS/iOS.
- * Prefers the User-Agent Client Hints API when available (modern Chrome/Edge),
- * falls back to navigator.platform (deprecated but universally supported).
+ * Prefers the User-Agent Client Hints API when it names a platform (modern
+ * Chrome/Edge), falls back to navigator.platform (deprecated but universally
+ * supported) when it is absent or blank.
  */
 function detectMac(): boolean {
   if (typeof navigator === 'undefined') {
@@ -134,7 +135,13 @@ function detectMac(): boolean {
   // Prefer User-Agent Client Hints API (not deprecated)
   const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
   if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
-    return /mac/i.test((uaData as {platform: string}).platform ?? '');
+    const uaPlatform = (uaData as {platform?: unknown}).platform;
+    // A blank platform is no answer, not a negative one. Builds that rewrite
+    // their client-hints identity ship '', so fall through rather than
+    // reading it as "not Apple".
+    if (typeof uaPlatform === 'string' && uaPlatform.trim() !== '') {
+      return /mac/i.test(uaPlatform);
+    }
   }
   // Fallback: navigator.platform (deprecated but still shipped everywhere)
   return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');

packages/core/src/hooks/useHotkeys.test.ts

@@ -22,6 +22,12 @@ function stubOtherPlatform() {
   vi.stubGlobal('navigator', {platform: 'Win32'});
 }
 
+function stubBlankClientHints(platform: string) {
+  // Builds that rewrite their client-hints identity expose the key with an
+  // empty value; navigator.platform is the only surface left that answers.
+  vi.stubGlobal('navigator', {userAgentData: {platform: ''}, platform});
+}
+
 function press(
   key: string,
   init: KeyboardEventInit & {target?: HTMLElement} = {},
@@ -67,6 +73,31 @@ describe('useHotkeys', () => {
     expect(onPress).toHaveBeenCalledTimes(1);
   });
 
+  it('reads a blank userAgentData.platform as unknown, not as non-Apple', () => {
+    stubBlankClientHints('MacIntel');
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    press('k', {ctrlKey: true});
+    expect(onPress).not.toHaveBeenCalled();
+
+    const event = press('k', {metaKey: true});
+    expect(onPress).toHaveBeenCalledTimes(1);
+    expect(onPress).toHaveBeenCalledWith(event);
+  });
+
+  it('still maps mod to ctrlKey when both platform surfaces are non-Apple', () => {
+    stubBlankClientHints('Win32');
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    press('k', {metaKey: true});
+    expect(onPress).not.toHaveBeenCalled();
+
+    press('k', {ctrlKey: true});
+    expect(onPress).toHaveBeenCalledTimes(1);
+  });
+
   it('does not fire a bare key when modifiers are held', () => {
     stubApplePlatform();
     const onPress = vi.fn();

packages/core/src/hooks/useHotkeys.ts

@@ -73,8 +73,9 @@ const KEY_ALIASES: Record<string, string> = {
 
 /**
  * Detects whether the current platform is macOS/iOS.
- * Prefers the User-Agent Client Hints API when available (modern Chrome/Edge),
- * falls back to navigator.platform (deprecated but universally supported).
+ * Prefers the User-Agent Client Hints API when it names a platform (modern
+ * Chrome/Edge), falls back to navigator.platform (deprecated but universally
+ * supported) when it is absent or blank.
  * Mirrors the detection used by Kbd so displayed and handled shortcuts agree.
  */
 function isApplePlatform(): boolean {
@@ -83,7 +84,13 @@ function isApplePlatform(): boolean {
   }
   const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
   if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
-    return /mac/i.test((uaData as {platform: string}).platform ?? '');
+    const uaPlatform = (uaData as {platform?: unknown}).platform;
+    // A blank platform is no answer, not a negative one. Builds that rewrite
+    // their client-hints identity ship '', so fall through rather than
+    // reading it as "not Apple".
+    if (typeof uaPlatform === 'string' && uaPlatform.trim() !== '') {
+      return /mac/i.test(uaPlatform);
+    }
   }
   return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
 }