@horon-ai/react 0.1.1 → 0.1.3

package/src/hooks/use-color-scheme.ts

@@ -1,5 +1,6 @@
 import { useSyncExternalStore } from "react";
 
+/** The two schemes the `.dark` class switch can report. */
 export type ColorScheme = "light" | "dark";
 
 const noop = () => {};
@@ -21,7 +22,29 @@ function readIsDark(): boolean {
   return document.documentElement.classList.contains("dark");
 }
 
-/** The active color scheme; `light` on the server and before hydration. */
+/**
+ * The active color scheme; `light` on the server and before hydration.
+ *
+ * The `.dark` class on <html> is the only source, watched with a `MutationObserver`, so a toggle anywhere on the
+ * page re-renders every caller. `prefers-color-scheme` is deliberately ignored: the theme is an explicit switch,
+ * not an OS follow. A server render reports `light` until the class is read on the client.
+ *
+ * @returns `dark` while the root element carries the `.dark` class, `light` otherwise.
+ *
+ * @example
+ * ```tsx
+ * import { useColorScheme } from "@horon-ai/react";
+ *
+ * function ThemeToggle() {
+ *   const scheme = useColorScheme();
+ *   return (
+ *     <Button variant="ghost" onClick={() => document.documentElement.classList.toggle("dark")}>
+ *       {scheme === "dark" ? "Light" : "Dark"}
+ *     </Button>
+ *   );
+ * }
+ * ```
+ */
 export function useColorScheme(): ColorScheme {
   return useSyncExternalStore(subscribe, readIsDark, () => false) ? "dark" : "light";
 }

package/src/hooks/use-copy-to-clipboard.ts

@@ -1,6 +1,8 @@
 import { useCallback, useEffect, useState } from "react";
 
+/** What {@link useCopyToClipboard} returns: the transient flag and the write function. */
 export type CopyToClipboard = {
+  /** True from a successful write until `resetMs` has passed; stays false when the write fails. */
   copied: boolean;
   /** Writes `text`; a failed write leaves `copied` false instead of throwing. */
   copy: (text: string) => void;
@@ -10,6 +12,27 @@ export type CopyToClipboard = {
  * Clipboard writes with a self-clearing confirmation: `copied` turns true when
  * the write resolves and back to false after `resetMs`, so a button needs no
  * timer of its own.
+ *
+ * The write goes through `navigator.clipboard`, so it needs a secure context and a user gesture; where that API
+ * is missing the call is a no-op and `copied` never turns true. The timer is cleared when the component unmounts
+ * or `resetMs` changes.
+ *
+ * @param resetMs - How long `copied` stays true after a successful write, in milliseconds. @default 1500
+ * @returns A {@link CopyToClipboard}: the current `copied` flag and a stable `copy` function.
+ *
+ * @example
+ * ```tsx
+ * import { useCopyToClipboard } from "@horon-ai/react";
+ *
+ * function CopyRow({ value }: { value: string }) {
+ *   const { copied, copy } = useCopyToClipboard();
+ *   return (
+ *     <Button variant="ghost" onClick={() => copy(value)}>
+ *       {copied ? "Copied" : "Copy"}
+ *     </Button>
+ *   );
+ * }
+ * ```
  */
 export function useCopyToClipboard(resetMs = 1500): CopyToClipboard {
   const [copied, setCopied] = useState(false);

package/src/hooks/use-device.ts

@@ -1,12 +1,16 @@
 import { useMediaQuery } from "./use-media-query";
 
+/** The three layout classes: `mobile` under 768px, `tablet` for a coarse pointer above that, `desktop` otherwise. */
 export type DeviceType = "mobile" | "tablet" | "desktop";
 
+/** The primary input behind the pointer: `touch` for a coarse pointer, `pointer` for a fine one. */
 export type DeviceInput = "touch" | "pointer";
 
+/** What the layout and the key hints need: the device class, the input behind it and whether a key chip can be reached. */
 export type Device = {
   /** `mobile` below 768px, `tablet` for a coarse pointer above that, `desktop` otherwise. */
   type: DeviceType;
+  /** `touch` when the pointer is coarse, `pointer` when it is fine. */
   input: DeviceInput;
   /** True only for a hovering fine pointer, the input that can actually reach a key chip. */
   keyboardHints: boolean;
@@ -31,7 +35,31 @@ function deviceSnapshot(type: DeviceType, input: DeviceInput, keyboardHints: boo
   return next;
 }
 
-/** The device class and its primary input, as the layout and key hints need them. */
+/**
+ * The device class and its primary input, as the layout and key hints need them.
+ *
+ * The three queries go through {@link useMediaQuery}, so nothing is read during a server render or the first
+ * hydration pass: that pass reports `desktop` / `pointer` with `keyboardHints` on, the value the query hooks
+ * were given as their server fallback. The returned object is shared, so a re-render with the same device
+ * hands back the same reference.
+ *
+ * @returns The current `Device`: `type`, `input` and `keyboardHints`.
+ *
+ * @example
+ * ```tsx
+ * import { useDevice } from "@horon-ai/react";
+ *
+ * function ComposeFooter() {
+ *   const { type, keyboardHints } = useDevice();
+ *   return (
+ *     <footer className="flex items-center gap-2">
+ *       <span className="text-caption">{type}</span>
+ *       {keyboardHints && <Kbd keys="Mod+Enter" />}
+ *     </footer>
+ *   );
+ * }
+ * ```
+ */
 export function useDevice(): Device {
   const mobile = useMediaQuery(MOBILE_QUERY);
   const coarse = useMediaQuery(COARSE_QUERY);

package/src/hooks/use-hotkey.ts

@@ -3,6 +3,7 @@ import { useEffect, useRef } from "react";
 import { matchesShortcut } from "../lib/platform";
 import { usePlatform } from "./use-platform";
 
+/** Options of {@link useHotkey}: the only switch is whether the listener is attached. */
 export type HotkeyOptions = {
   /** When false the listener is detached and the hotkey does nothing (default true). */
   enabled?: boolean;
@@ -12,6 +13,26 @@ export type HotkeyOptions = {
  * Runs `handler` on a `document` keydown that matches `keys`, such as `Mod+K`,
  * and prevents the browser default. Text inputs keep their focus, so a palette
  * shortcut still fires mid-typing; the check follows the OS modifier key.
+ *
+ * The listener is attached in an effect, so a server render binds nothing. The handler is held in a ref, so a
+ * caller can pass an inline arrow without re-binding on every render; only `keys`, `enabled` and the OS
+ * re-subscribe. `Mod` follows {@link usePlatform}: ⌘ on macOS and iOS, Ctrl on Windows, Linux and Android,
+ * and either one while the OS is still unknown.
+ *
+ * @param keys - Shortcut string such as `Mod+K`, `Mod+Shift+Enter` or `Escape`, in the same syntax `Kbd` draws.
+ * @param handler - Called with the matching keydown event after `preventDefault()`.
+ * @param options - {@link HotkeyOptions}; `enabled` defaults to `true`.
+ * @returns Nothing; the listener is cleaned up when the component unmounts or `keys`/`enabled` change.
+ *
+ * @example
+ * ```tsx
+ * import { useHotkey } from "@horon-ai/react";
+ *
+ * function PaletteShortcut({ open }: { open: () => void }) {
+ *   useHotkey("Mod+K", open);
+ *   return <Kbd keys="Mod+K" />;
+ * }
+ * ```
  */
 export function useHotkey(keys: string, handler: (event: KeyboardEvent) => void, options: HotkeyOptions = {}) {
   const { enabled = true } = options;

package/src/hooks/use-media-query.ts

@@ -6,6 +6,24 @@ const noop = () => {};
  * Tracks one `matchMedia` query. The server render and the first client render
  * use `serverValue`, so static thumbnails and hydration agree before the browser
  * reports the real state.
+ *
+ * The subscription is rebuilt when `query` changes, and both the server snapshot and the snapshot taken before
+ * `window.matchMedia` exists fall back to `serverValue`. The query string must be a literal the caller keeps
+ * stable across renders, as the cache key is the string itself.
+ *
+ * @param query - A media query such as `(max-width: 767px)` or `(prefers-reduced-motion: reduce)`.
+ * @param serverValue - Result to report while rendering on the server or before `matchMedia` is available. @default false
+ * @returns Whether the query currently matches, or `serverValue` on the server and in the first pass.
+ *
+ * @example
+ * ```tsx
+ * import { useMediaQuery } from "@horon-ai/react";
+ *
+ * function Nav() {
+ *   const compact = useMediaQuery("(max-width: 767px)");
+ *   return compact ? <TabBar items={items} value={tab} onValueChange={setTab} /> : <Sidebar items={items} />;
+ * }
+ * ```
  */
 export function useMediaQuery(query: string, serverValue = false): boolean {
   const subscribe = useCallback(

package/src/hooks/use-platform.ts

@@ -2,10 +2,14 @@ import { useSyncExternalStore } from "react";
 
 import { detectOs, detectRuntime, readNavigator, type Os, type Runtime } from "../lib/platform";
 
+/** Which physical key carries `Mod` on this OS: `meta` is ⌘, `ctrl` is Ctrl. */
 export type ModKey = "meta" | "ctrl";
 
+/** What {@link usePlatform} reports: the OS, the shell the page runs in and the key behind `Mod`. */
 export type Platform = {
+  /** The detected OS, `unknown` on the server and when no hint names one. */
   os: Os;
+  /** `desktop` inside the Tauri shell or Electron, `web` everywhere else including the server. */
   runtime: Runtime;
   /** The physical key behind `Mod` on this OS, ready for a keydown check. */
   modKey: ModKey;
@@ -33,7 +37,32 @@ function readPlatform(): Platform {
 
 const subscribe = (_onChange: () => void) => noop;
 
-/** The current OS, browser or desktop shell, and the key that means `Mod`. */
+/**
+ * The current OS, browser or desktop shell, and the key that means `Mod`.
+ *
+ * The value is read from `navigator` and `window` and cached for the life of the page: there is no store to
+ * subscribe to, so the hook never re-renders on its own. A server render and the first hydration pass get
+ * `{ os: "unknown", runtime: "web", modKey: "meta" }`, which draws the Mac keys; on the client the first render
+ * already reports the detected platform.
+ *
+ * @returns The current {@link Platform}: `os`, `runtime` and `modKey`.
+ *
+ * @example
+ * ```tsx
+ * import { isModKey, usePlatform } from "@horon-ai/react";
+ *
+ * function Composer({ onStart }: { onStart: () => void }) {
+ *   const { os } = usePlatform();
+ *   return (
+ *     <textarea
+ *       onKeyDown={(event) => {
+ *         if (event.key === "Enter" && isModKey(event, os)) onStart();
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function usePlatform(): Platform {
   return useSyncExternalStore(subscribe, readPlatform, () => SERVER_PLATFORM);
 }

package/src/hooks/use-reduced-motion.ts

@@ -2,7 +2,24 @@ import { useMediaQuery } from "./use-media-query";
 
 const QUERY = "(prefers-reduced-motion: reduce)";
 
-/** True while the OS asks for reduced motion; false on the server. */
+/**
+ * True while the OS asks for reduced motion; false on the server.
+ *
+ * A thin reading of {@link useMediaQuery} over `(prefers-reduced-motion: reduce)`; the CSS side of the same
+ * preference is handled by the motion utilities in `globals.css`, which collapse their durations.
+ *
+ * @returns Whether the user prefers reduced motion; `false` during a server render and the first pass.
+ *
+ * @example
+ * ```tsx
+ * import { useReducedMotion } from "@horon-ai/react";
+ *
+ * function Stream({ text }: { text: string }) {
+ *   const reducedMotion = useReducedMotion();
+ *   return <StreamingText text={text} smooth={!reducedMotion} />;
+ * }
+ * ```
+ */
 export function useReducedMotion(): boolean {
   return useMediaQuery(QUERY);
 }

package/src/index.ts

@@ -1,3 +1,34 @@
+/**
+ * Horon Design System for React.
+ *
+ * The package holds the 84 Horon components ported from the Figma `Horon` file. Behaviour and
+ * accessibility come from Base UI (`@base-ui/react`); layout and colour come from Tailwind CSS v4
+ * utilities whose values are the `@horon-ai/tokens` variables, so class names such as `text-label-md`
+ * or `bg-glass-regular` are the design tokens themselves. TypeScript source ships as-is, with no
+ * build output, so the consuming bundler compiles it.
+ *
+ * Import everything from the barrel, or one component from its subpath:
+ *
+ * - `import { Button, Card, Input } from "@horon-ai/react"` re-exports every component and its prop types.
+ * - `import { Button } from "@horon-ai/react/components/button"` resolves to the same source file
+ *   through the `./components/*` export map, which keeps a bundle to the components it uses.
+ * - `import { cn } from "@horon-ai/react"` is the tailwind-merge helper that understands the token
+ *   names, so a caller class overrides a component default.
+ * - `import { mountCursorGhost } ...` / `import "@horon-ai/react/cursor-ghost"` adds the desktop
+ *   cursor trail outside React.
+ * - `import { usePlatform, useDevice, useHotkey } from "@horon-ai/react"` reads the OS, the browser or
+ *   desktop shell and the input device, and binds a `Mod+K`-style shortcut. The hooks are barrel-only,
+ *   with no subpath, and the same `lib/platform` helpers (`formatShortcut`, `matchesShortcut`, `isModKey`)
+ *   are exported so a caller's shortcut draws and matches the keys the components use.
+ *
+ * Import `@horon-ai/react/globals.css` once in the app entry stylesheet: it brings in Tailwind CSS v4,
+ * Pretendard, Geist Mono, the generated token theme and the liquid-glass layer styles. Add an `@source`
+ * line beside it that points at the package `src` folder so Tailwind scans the component sources (see
+ * the README for the exact line). Then set `class="dark"` on an ancestor for the dark palette, and
+ * `data-platform="desktop"` or `data-platform="mobile"` to switch the typography board.
+ *
+ * @packageDocumentation
+ */
 export * from "./components/agent-activity";
 export * from "./components/agent-lane";
 export * from "./components/agent-lanes-timeline";

package/src/lib/cn.ts

@@ -1,6 +1,10 @@
 import { lightColors, primitives, radius, shadow, textStyles } from "@horon-ai/tokens";
 import { extendTailwindMerge } from "tailwind-merge";
 
+/**
+ * One class-name argument accepted by {@link cn}: a class string, or a falsy value that is skipped.
+ * `false`, `null` and `undefined` are common when a class is applied conditionally.
+ */
 export type ClassValue = string | false | null | undefined;
 
 /**
@@ -19,7 +23,15 @@ const merge = extendTailwindMerge({
   },
 });
 
-/** Joins class names, skipping empty values; later classes win over conflicting earlier ones. */
+/**
+ * Joins class names, skipping empty values; later classes win over conflicting earlier ones.
+ *
+ * Use it in every component so a caller's class overrides the component default instead of
+ * duplicating it; the merge is extended with the Horon token names.
+ *
+ * @param values - Any number of class strings or falsy values, applied left to right.
+ * @returns One space-separated class string with conflicting utilities collapsed.
+ */
 export function cn(...values: ClassValue[]): string {
   return merge(values.filter(Boolean).join(" "));
 }

package/src/lib/cursor-ghost.ts

@@ -12,15 +12,15 @@
  */
 
 export type CursorGhostOptions = {
-  /** Number of arrow copies. */
+  /** Number of arrow copies. @default 5 */
   ghosts?: number;
-  /** Arrow height in CSS px. */
+  /** Arrow height in CSS px. @default 26 */
   size?: number;
-  /** Lerp factor of the first copy toward the pointer, per frame. */
+  /** Lerp factor of the first copy toward the pointer, per frame. @default 0.16 */
   headFollow?: number;
-  /** Blur spread of the last copy in CSS px. */
+  /** Blur spread of the last copy in CSS px. @default 14 */
   smear?: number;
-  /** Arrow fill. Blended with `difference`, so white reads dark on light pages. */
+  /** Arrow fill. Blended with `difference`, so white reads dark on light pages. @default "#FFFFFF" */
   color?: string;
 };
 
@@ -195,6 +195,13 @@ function startEffect({ ghosts, size, headFollow, smear, color }: Required<Cursor
 /**
  * Mounts the Cursor Ghost trail and returns its teardown. The trail appears and
  * disappears on its own as the pointer type or the reduced-motion setting changes.
+ *
+ * Safe to call during server rendering: without a `window`, `document` or `matchMedia`
+ * it returns a no-op teardown. Call it after `<html data-horon-cursor="off">` is set when
+ * you want both the automatic mount suppressed and custom options.
+ *
+ * @param options - Overrides for the trail; omitted keys fall back to the built-in defaults.
+ * @returns A teardown that removes the layer, its listeners and any pending animation frame.
  */
 export function mountCursorGhost(options: CursorGhostOptions = {}): () => void {
   if (typeof window === "undefined" || typeof document === "undefined" || !window.matchMedia) return () => {};
@@ -234,7 +241,10 @@ export function mountCursorGhost(options: CursorGhostOptions = {}): () => void {
 
 function autoMount() {
   if (typeof window === "undefined" || typeof document === "undefined") return;
-  const registry = globalThis as typeof globalThis & { [AUTO_MOUNT_KEY]?: true };
+  const registry = globalThis as typeof globalThis & {
+    /** Set once the automatic mount has run, so a second import does not add another trail. */
+    [AUTO_MOUNT_KEY]?: true;
+  };
   if (registry[AUTO_MOUNT_KEY]) return;
   if (document.documentElement.getAttribute(OPT_OUT_ATTRIBUTE) === "off") return;
   registry[AUTO_MOUNT_KEY] = true;

package/src/lib/platform.ts

@@ -1,41 +1,69 @@
+/** The operating systems the shortcut helpers know; `unknown` is what a server render and an empty hint report. */
 export type Os = "macos" | "windows" | "linux" | "ios" | "android" | "unknown";
 
+/** Where the page runs: `desktop` inside the Tauri shell or Electron, `web` everywhere else including the server. */
 export type Runtime = "web" | "desktop";
 
 /** The parts of `navigator` that identify the OS; plain data so detection stays testable. */
 export type PlatformInput = {
+  /** Full user agent string, the last and coarsest hint. */
   userAgent?: string;
+  /** `navigator.platform`, still the most reliable hint in Safari and Firefox. */
   platform?: string;
+  /** `navigator.userAgentData.platform`, the first hint when the browser exposes it. */
   uaPlatform?: string;
+  /** Touch points, which is what separates iPadOS (a Mac hint) from a Mac. */
   maxTouchPoints?: number;
 };
 
 /** The parts of `window` that tell a page from the desktop shell; plain data for the same reason. */
 export type RuntimeWindow = {
+  /** Set by Tauri in the desktop shell. */
   __TAURI_INTERNALS__?: unknown;
-  navigator?: { userAgent?: string };
+  /** `window.navigator`, read for the Electron fragment in its user agent. */
+  navigator?: {
+    /** User agent string, tested for `electron`. */
+    userAgent?: string;
+  };
 };
 
 /** The parts of a keyboard event a shortcut reads; `KeyboardEvent` satisfies it as-is. */
 export type ShortcutEvent = {
+  /** `KeyboardEvent.key`, for example `k`, `Enter` or `ArrowUp`. */
   key?: string;
+  /** ⌘ on macOS and iOS. */
   metaKey?: boolean;
+  /** Ctrl on Windows, Linux and Android. */
   ctrlKey?: boolean;
+  /** ⌥ or Alt. */
   altKey?: boolean;
+  /** ⇧ or Shift. */
   shiftKey?: boolean;
 };
 
 /**
  * Reads the platform hints from the live `navigator`. `userAgentData` is not in
  * the DOM typings yet, so the shape is spelled out here instead of cast away.
+ *
+ * Every field is copied out, and a missing `navigator` (a server render) yields an empty object, so
+ * {@link detectOs} falls through to `unknown` instead of throwing.
+ *
+ * @returns The four hints as {@link PlatformInput}; fields the browser does not expose stay `undefined`.
  */
 export function readNavigator(): PlatformInput {
   if (typeof navigator === "undefined") return {};
   const nav = navigator as {
+    /** Full user agent string. */
     userAgent?: string;
+    /** `navigator.platform`, such as `MacIntel`. */
     platform?: string;
+    /** Number of touch points, which tells iPadOS from a Mac. */
     maxTouchPoints?: number;
-    userAgentData?: { platform?: string };
+    /** Chromium's hint object, absent in Safari and Firefox. */
+    userAgentData?: {
+      /** The OS hint, such as `macOS` or `Windows`. */
+      platform?: string;
+    };
   };
   return {
     userAgent: nav.userAgent,
@@ -62,6 +90,13 @@ function osFromHint(hint: string, maxTouchPoints: number): Os | undefined {
  * Finds the OS from the first hint that names one: `userAgentData.platform`,
  * then `navigator.platform`, then the user agent string. Empty input is
  * `unknown`, which the shortcuts treat as the macOS/⌘ rendering.
+ *
+ * A hint containing `mac` is `ios` when `maxTouchPoints` is above 1, since iPadOS reports a Mac platform and
+ * user agent. A hint that matches nothing is skipped, so a browser that names no known OS still reports
+ * `unknown` rather than a wrong guess.
+ *
+ * @param input - The hints to read, usually from {@link readNavigator}; omitted means empty. @default {}
+ * @returns The first `Os` a hint names, or `unknown` when none does.
  */
 export function detectOs(input: PlatformInput = {}): Os {
   const maxTouchPoints = input.maxTouchPoints ?? 0;
@@ -74,7 +109,14 @@ export function detectOs(input: PlatformInput = {}): Os {
   return "unknown";
 }
 
-/** `desktop` for the Tauri shell and Electron; `web` everywhere else, including the server. */
+/**
+ * `desktop` for the Tauri shell and Electron; `web` everywhere else, including the server.
+ *
+ * The Tauri test wins over the user agent, so a shell that also advertises Electron still reports `desktop`.
+ *
+ * @param win - The window to inspect, usually `window`; `null` or omitted reports `web`. @default null
+ * @returns `desktop` inside either shell, `web` otherwise.
+ */
 export function detectRuntime(win: RuntimeWindow | null = null): Runtime {
   if (!win) return "web";
   if ("__TAURI_INTERNALS__" in win) return "desktop";
@@ -110,6 +152,13 @@ const OTHER_LABELS: Record<string, string> = {
 /**
  * Draws a `+`-joined shortcut for one OS: `Mod+K` is `⌘K` on macOS and iOS,
  * `Ctrl+K` on Windows and Linux. Mac families glue the parts, the rest keep `+`.
+ *
+ * `mod`, `shift`, `alt`, `enter`, `escape`/`esc` and the four arrows have labels; any other part is kept as
+ * written, so a bare `K` stays `K`. An empty string, or one made only of `+` and spaces, returns `""`.
+ *
+ * @param keys - Shortcut in the same syntax `Kbd` and {@link matchesShortcut} take, such as `Mod+Shift+Enter`.
+ * @param os - The OS to draw for; `unknown` draws the Mac symbols, the server default.
+ * @returns The label to render, for example `⌘⇧↵` or `Ctrl+Shift+Enter`.
  */
 export function formatShortcut(keys: string, os: Os): string {
   const parts = keys
@@ -130,7 +179,16 @@ function modifierSlot(os: Os): "meta" | "ctrl" | "either" {
   return "either";
 }
 
-/** True when the platform's `Mod` key is down; the other side's key is not `Mod`. */
+/**
+ * True when the platform's `Mod` key is down; the other side's key is not `Mod`.
+ *
+ * On macOS and iOS that means `metaKey` without `ctrlKey`; on Windows, Linux and Android `ctrlKey` without
+ * `metaKey`, so Ctrl+⌘ on a Mac is not `Mod`. With an `unknown` OS either key counts.
+ *
+ * @param event - The keyboard event or anything shaped like {@link ShortcutEvent}.
+ * @param os - The OS whose `Mod` to test, usually from {@link detectOs} or `usePlatform().os`.
+ * @returns Whether this event carries the platform's modifier.
+ */
 export function isModKey(event: ShortcutEvent, os: Os): boolean {
   const slot = modifierSlot(os);
   const meta = event.metaKey === true;
@@ -154,6 +212,15 @@ function canonicalKey(value: string): string {
  * Tests a keyboard event against a shortcut string such as `Mod+K` or
  * `Mod+Shift+Enter`. `Mod` is the platform key (⌘ on macOS/iOS, Ctrl
  * elsewhere, either one when the OS is unknown).
+ *
+ * Matching is exact on the modifier set: Alt and Shift must be present or absent exactly as the shortcut says,
+ * and a missing base key (a string of modifiers only) never matches. `esc` and `escape` are the same key, and
+ * the comparison is case-insensitive.
+ *
+ * @param event - The keydown event or anything shaped like {@link ShortcutEvent}.
+ * @param keys - Shortcut string, with `mod` standing for the platform key, such as `Mod+K`.
+ * @param os - The OS whose `Mod` to test.
+ * @returns Whether the event is exactly this shortcut on this OS.
  */
 export function matchesShortcut(event: ShortcutEvent, keys: string, os: Os): boolean {
   const parts = keys