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,16 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `mod` hotkeys and `Kbd` resolve to Cmd on macOS again when client hints report a blank platform
+
+`useHotkeys` and `Kbd` both prefer `navigator.userAgentData.platform` and fall
+back to `navigator.platform`, but guarded the preference with
+`'platform' in uaData`, which is true whenever the key exists at all. A build
+reporting `platform: ''` therefore committed to the client-hints branch and got
+`false` without ever reaching the fallback, so on macOS every `mod` combo
+listened for Ctrl and every `<Kbd>` drew Ctrl. Electron and other embedders
+that rewrite the app's user-agent identity ship exactly that. A blank platform
+is now treated as unknown and falls through.
+
+@Astro-Han

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

@@ -23,6 +23,7 @@ describe('Kbd', () => {
       value: originalPlatform,
       configurable: true,
     });
+    delete (navigator as {userAgentData?: unknown}).userAgentData;
   });
 
   it('renders a single key', () => {
@@ -54,6 +55,22 @@ describe('Kbd', () => {
     expect(screen.getByText('\u2318')).toBeInTheDocument(); // \u2318
   });
 
+  it('reads a blank userAgentData.platform as unknown, not as non-Mac', () => {
+    // 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,
+    });
+    Object.defineProperty(navigator, 'platform', {
+      value: 'MacIntel',
+      configurable: true,
+    });
+
+    render(<Kbd keys="mod" />);
+    expect(screen.getByText('\u2318')).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

@@ -67,6 +67,24 @@ describe('useHotkeys', () => {
     expect(onPress).toHaveBeenCalledTimes(1);
   });
 
+  it('reads a blank userAgentData.platform as unknown, not as non-Apple', () => {
+    // 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: '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('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 ?? '');
 }