@horon-ai/react 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@horon-ai/react",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/horon-ai/design.git",
@@ -30,7 +30,7 @@
 	"dependencies": {
 		"@base-ui/react": "^1.9.0",
 		"@fontsource-variable/geist-mono": "^5.3.0",
-		"@horon-ai/tokens": "0.1.0",
+		"@horon-ai/tokens": "0.1.1",
 		"@phosphor-icons/react": "^2.1.10",
 		"@tanstack/react-table": "^9.3.1",
 		"pretendard": "^1.3.9",

package/src/components/agent-activity.tsx

@@ -1,6 +1,7 @@
 import { CaretDown, CaretRight, CheckCircle, WarningCircle, Wrench } from "@phosphor-icons/react";
 import { type ComponentProps, type ReactNode, useEffect, useRef, useState } from "react";
 
+import { useReducedMotion } from "../hooks/use-reduced-motion";
 import { cn } from "../lib/cn";
 import { Spinner } from "./spinner";
 
@@ -37,7 +38,7 @@ function codePointEnd(text: string, end: number): number {
  * bursty chunks read as steady typing; otherwise, and under reduced motion, everything shows at once.
  * Text that no longer extends what was shown (a rewrite) restarts from the shared prefix.
  */
-function useRevealedLength(text: string, smooth: boolean): number {
+function useRevealedLength(text: string, smooth: boolean, reducedMotion: boolean): number {
   const [shown, setShown] = useState(text.length);
   const shownRef = useRef(text.length);
   const previous = useRef(text);
@@ -54,7 +55,7 @@ function useRevealedLength(text: string, smooth: boolean): number {
     while (shared < start && text[shared] === before[shared]) shared++;
     start = shared;
 
-    if (!smooth || window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+    if (!smooth || reducedMotion) {
       set(text.length);
       return undefined;
     }
@@ -73,7 +74,7 @@ function useRevealedLength(text: string, smooth: boolean): number {
       if (length < text.length) frame = requestAnimationFrame(tick);
     });
     return () => cancelAnimationFrame(frame);
-  }, [text, smooth]);
+  }, [text, smooth, reducedMotion]);
 
   return Math.min(shown, text.length);
 }
@@ -95,7 +96,8 @@ export type StreamingTextProps = Omit<ComponentProps<"div">, "className" | "chil
  * when it is complete, instead of every chunk.
  */
 export function StreamingText({ text, streaming = true, smooth = true, className, ...props }: StreamingTextProps) {
-  const shown = useRevealedLength(text, streaming && smooth);
+  const reducedMotion = useReducedMotion();
+  const shown = useRevealedLength(text, streaming && smooth, reducedMotion);
   const typing = shown < text.length;
   return (
     <div

package/src/components/agent-panel.tsx

@@ -1,7 +1,10 @@
 import { CaretDown } from "@phosphor-icons/react";
 import type { ComponentProps, ReactNode } from "react";
 
+import { useDevice } from "../hooks/use-device";
+import { usePlatform } from "../hooks/use-platform";
 import { cn } from "../lib/cn";
+import { isModKey } from "../lib/platform";
 import { Kbd } from "./kbd";
 
 type WithClass<T> = Omit<T, "className"> & { className?: string };
@@ -75,7 +78,7 @@ export type TaskComposerProps = {
   className?: string;
 };
 
-/** Figma task `Composer` (Agent tasks 112:797): a 4% ink box, 18px radius, with pickers, ⌘↵ hint and Start. */
+/** Figma task `Composer` (Agent tasks 112:797): a 4% ink box, 18px radius, with pickers, a Mod+Enter hint and Start. */
 export function TaskComposer({
   placeholder = "Describe a task for a bot",
   value,
@@ -85,6 +88,8 @@ export function TaskComposer({
   startLabel = "Start",
   className,
 }: TaskComposerProps) {
+  const { os } = usePlatform();
+  const { keyboardHints } = useDevice();
   return (
     <div
       className={cn(
@@ -97,7 +102,7 @@ export function TaskComposer({
         value={value}
         onChange={(event) => onValueChange?.(event.target.value)}
         onKeyDown={(event) => {
-          if (event.key === "Enter" && event.metaKey) onStart?.();
+          if (event.key === "Enter" && isModKey(event, os)) onStart?.();
         }}
         placeholder={placeholder}
         aria-label={placeholder}
@@ -106,8 +111,7 @@ export function TaskComposer({
       <div className="flex flex-wrap items-center gap-1.5">
         {pickers && <span className="flex min-w-0 flex-wrap items-center gap-1.5">{pickers}</span>}
         <span className="min-w-0 flex-1" />
-        <Kbd>⌘</Kbd>
-        <Kbd>↵</Kbd>
+        {keyboardHints && <Kbd keys="Mod+Enter" />}
         <button
           type="button"
           onClick={onStart}

package/src/components/agent-steering-panel.tsx

@@ -1,7 +1,10 @@
-import { ArrowElbowDownLeft, ArrowUp, Check, Lightning, Path, Pause, Play, X } from "@phosphor-icons/react";
+import { ArrowUp, Check, Lightning, Path, Pause, Play, X } from "@phosphor-icons/react";
 import { type ComponentProps, type CSSProperties, type ReactNode, useState } from "react";
 
+import { useDevice } from "../hooks/use-device";
+import { usePlatform } from "../hooks/use-platform";
 import { cn } from "../lib/cn";
+import { isModKey } from "../lib/platform";
 import { Kbd } from "./kbd";
 import { Spinner } from "./spinner";
 
@@ -33,7 +36,7 @@ export type AgentSteeringPanelProps = Omit<ComponentProps<"section">, "className
   notes?: SteeringNote[];
   onApplyNow?: (id: string) => void;
   onRemoveNote?: (id: string) => void;
-  /** Called with the text typed in the steer box: Enter queues it for the next step, ⌘Enter interrupts now. */
+  /** Called with the text typed in the steer box: Enter queues it for the next step, Mod+Enter interrupts now. */
   onSteer?: (text: string, interrupt: boolean) => void;
   placeholder?: string;
   className?: string;
@@ -135,6 +138,8 @@ export function AgentSteeringPanel({
   ...props
 }: AgentSteeringPanelProps) {
   const [draft, setDraft] = useState("");
+  const { os } = usePlatform();
+  const { keyboardHints } = useDevice();
   const queued = notes.filter((note) => !note.applied);
   const submit = (interrupt: boolean) => {
     const text = draft.trim();
@@ -236,7 +241,7 @@ export function AgentSteeringPanel({
               if (event.nativeEvent.isComposing || event.keyCode === 229) return;
               if (event.key === "Enter") {
                 event.preventDefault();
-                submit(event.metaKey || event.ctrlKey);
+                submit(isModKey(event, os));
               }
             }}
             placeholder={placeholder}
@@ -253,21 +258,18 @@ export function AgentSteeringPanel({
           </button>
         </div>
 
-        <div className="flex flex-wrap items-center gap-x-3.5 gap-y-1.5 text-caption text-text-secondary">
-          <span className="flex items-center gap-1.25">
-            <Kbd>
-              <ArrowElbowDownLeft aria-hidden />
-            </Kbd>
-            next step
-          </span>
-          <span className="flex items-center gap-1.25">
-            <Kbd>⌘</Kbd>
-            <Kbd>
-              <ArrowElbowDownLeft aria-hidden />
-            </Kbd>
-            interrupt now
-          </span>
-        </div>
+        {keyboardHints && (
+          <div className="flex flex-wrap items-center gap-x-3.5 gap-y-1.5 text-caption text-text-secondary">
+            <span className="flex items-center gap-1.25">
+              <Kbd keys="Enter" />
+              next step
+            </span>
+            <span className="flex items-center gap-1.25">
+              <Kbd keys="Mod+Enter" />
+              interrupt now
+            </span>
+          </div>
+        )}
       </div>
     </section>
   );

package/src/components/bot-instructions-panel.tsx

@@ -2,7 +2,8 @@ import { CaretDown, Play } from "@phosphor-icons/react";
 import { type ComponentProps, type KeyboardEvent, type ReactNode, useRef, useState } from "react";
 
 import { cn } from "../lib/cn";
-import { useActiveIndicator } from "../lib/use-active-indicator";
+import { useActiveIndicator } from "../hooks/use-active-indicator";
+import { useDevice } from "../hooks/use-device";
 import { Kbd } from "./kbd";
 
 type WithClass<T> = Omit<T, "className"> & { className?: string };
@@ -174,6 +175,7 @@ export function BotInstructionsPanel({
   const [tab, setTab] = useState("instructions");
   const [scenario, setScenario] = useState(defaultScenario ?? scenarios?.[0]);
   const [runCount, setRunCount] = useState(0);
+  const { keyboardHints } = useDevice();
 
   return (
     <section
@@ -342,7 +344,9 @@ export function BotInstructionsPanel({
               >
                 <Play aria-hidden className="size-3.5" />
                 Run
-                <Kbd className="bg-bg-surface-6 text-text-inverse/80">⌘↵</Kbd>
+                {keyboardHints && (
+                  <Kbd keys="Mod+Enter" className="bg-bg-surface-6 text-text-inverse/80" />
+                )}
               </button>
             </div>
           </div>

package/src/components/command-palette.tsx

@@ -1,11 +1,16 @@
 import { Autocomplete } from "@base-ui/react/autocomplete";
 import { Dialog } from "@base-ui/react/dialog";
-import { MagnifyingGlass } from "@phosphor-icons/react";
+import { MagnifyingGlass, X } from "@phosphor-icons/react";
 import type { ReactNode } from "react";
 
+import { useDevice } from "../hooks/use-device";
 import { cn } from "../lib/cn";
 import { Kbd } from "./kbd";
 
+/** Close control shape for pointers that never reach a key: a 28px icon tile instead of the esc chip. */
+const touchCloseClass =
+  "flex size-7 shrink-0 motion-press cursor-pointer items-center justify-center rounded-full text-text-secondary hover:bg-overlay-ink-6 hover:text-text-primary focus-visible:outline-2 focus-visible:outline-text-brand [&_svg]:size-4";
+
 export type CommandItem = {
   value: string;
   label: string;
@@ -16,7 +21,7 @@ export type CommandItem = {
   tileClassName?: string;
   /** Caption after the label, such as the workspace. */
   meta?: ReactNode;
-  /** Right-side hint, usually `<Kbd>`. */
+  /** Right-side hint, usually `<Kbd>`; hidden when the device shows no keyboard hints. */
   hint?: ReactNode;
   onSelect?: () => void;
 };
@@ -30,7 +35,7 @@ export type CommandPaletteProps = {
   placeholder?: string;
   /** Shown when the query has no matches; defaults to "No results". */
   empty?: ReactNode;
-  /** Footer key hints, such as `[["↑↓", "Move"], ["↵", "Open"]]`. */
+  /** Footer key hints, such as `[["↑↓", "Move"], ["↵", "Open"]]`; hidden when the device shows no keyboard hints. */
   hints?: [ReactNode, string][];
   trigger?: ReactNode;
   /**
@@ -55,6 +60,7 @@ export function CommandPalette({
   surface = "solid",
   className,
 }: CommandPaletteProps) {
+  const { keyboardHints } = useDevice();
   return (
     <Dialog.Root open={open} onOpenChange={onOpenChange}>
       {trigger}
@@ -76,13 +82,16 @@ export function CommandPalette({
               placeholder={placeholder}
               empty={empty}
               closeControl={
-                <Dialog.Close aria-label="Close" className="motion-press cursor-pointer">
-                  <Kbd>esc</Kbd>
+                <Dialog.Close
+                  aria-label="Close"
+                  className={keyboardHints ? "motion-press cursor-pointer" : touchCloseClass}
+                >
+                  {keyboardHints ? <Kbd keys="Escape" /> : <X aria-hidden />}
                 </Dialog.Close>
               }
               onSelect={() => onOpenChange?.(false)}
             />
-            {hints && hints.length > 0 && (
+            {keyboardHints && hints && hints.length > 0 && (
               <div className="relative flex flex-wrap items-center gap-x-4 gap-y-1 px-3 pt-2 pb-1">
                 {hints.map(([key, label]) => (
                   <span key={label} className="flex items-center gap-1.5 text-caption text-text-secondary">
@@ -119,6 +128,7 @@ export function CommandPaletteBody({
   onClose,
   onSelect,
 }: CommandPaletteBodyProps) {
+  const { keyboardHints } = useDevice();
   return (
     <Autocomplete.Root
       open
@@ -138,8 +148,13 @@ export function CommandPaletteBody({
         />
         {closeControl ??
           (onClose === undefined ? null : (
-            <button type="button" aria-label={closeLabel} className="motion-press cursor-pointer" onClick={onClose}>
-              <Kbd>esc</Kbd>
+            <button
+              type="button"
+              aria-label={closeLabel}
+              className={keyboardHints ? "motion-press cursor-pointer" : touchCloseClass}
+              onClick={onClose}
+            >
+              {keyboardHints ? <Kbd keys="Escape" /> : <X aria-hidden />}
             </button>
           ))}
       </div>
@@ -179,7 +194,7 @@ export function CommandPaletteBody({
                   <span className="truncate text-label-md text-text-primary">{item.label}</span>
                   {item.meta && <span className="shrink-0 text-caption text-text-secondary">{item.meta}</span>}
                   <span className="flex-1" />
-                  {item.hint}
+                  {keyboardHints && item.hint}
                 </Autocomplete.Item>
               )}
             </Autocomplete.Collection>

package/src/components/filter-bar.tsx

@@ -1,7 +1,7 @@
 import { type ComponentProps, type ReactNode, useRef, useState } from "react";
 
 import { cn } from "../lib/cn";
-import { useActiveIndicator } from "../lib/use-active-indicator";
+import { useActiveIndicator } from "../hooks/use-active-indicator";
 
 export type FilterBarItem = {
   value: string;

package/src/components/flue-background.tsx

@@ -1,5 +1,6 @@
-import { type CSSProperties, useEffect, useRef, useSyncExternalStore } from "react";
+import { type CSSProperties, useEffect, useRef } from "react";
 
+import { useColorScheme } from "../hooks/use-color-scheme";
 import { cn } from "../lib/cn";
 
 export type FlueConfig = {
@@ -133,21 +134,6 @@ const FLUE_VARIANTS: Record<FlueVariant, FlueTuning> = {
   },
 };
 
-/** Follows the `.dark` class on <html>, the switch the theme uses. */
-function subscribeScheme(onChange: () => void): () => void {
-  const observer = new MutationObserver(onChange);
-  observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });
-  return () => observer.disconnect();
-}
-
-function useDarkScheme(): boolean {
-  return useSyncExternalStore(
-    subscribeScheme,
-    () => document.documentElement.classList.contains("dark"),
-    () => false,
-  );
-}
-
 const ENGINE_KEYS = new Set(["cursor", "maxDpr"]);
 
 const VERT = `#version 300 es
@@ -221,7 +207,7 @@ export type FlueBackgroundProps = {
  */
 export function FlueBackground({ className, style, variant = "default", config, tintClassName }: FlueBackgroundProps) {
   const canvasRef = useRef<HTMLCanvasElement>(null);
-  const dark = useDarkScheme();
+  const dark = useColorScheme() === "dark";
   const tuning = FLUE_VARIANTS[variant];
   const settings = { ...(dark ? FLUE_NIGHT : FLUE_SKY), ...(dark ? tuning.dark : tuning.light), ...config };
   const key = JSON.stringify(settings);

package/src/components/kbd.tsx

@@ -1,6 +1,8 @@
 import type { ComponentProps } from "react";
 
+import { usePlatform } from "../hooks/use-platform";
 import { cn } from "../lib/cn";
+import { formatShortcut } from "../lib/platform";
 import type { ControlSize } from "../lib/size";
 
 export type KbdSize = ControlSize;
@@ -8,6 +10,8 @@ export type KbdSize = ControlSize;
 export type KbdProps = Omit<ComponentProps<"kbd">, "className"> & {
   /** Chip size: `sm` tighter caption, `md` the Command palette chip (default), `lg` label-sm with more padding. */
   size?: KbdSize;
+  /** Shortcut such as `Mod+Enter`, drawn with the OS's key labels (`⌘↵` / `Ctrl+Enter`) instead of children. */
+  keys?: string;
   className?: string;
 };
 
@@ -19,7 +23,8 @@ const sizeClass: Record<KbdSize, string> = {
 };
 
 /** Figma `Kbd` (Command palette 110:676): a 6% ink chip with caption text. */
-export function Kbd({ size = "md", className, children, ...props }: KbdProps) {
+export function Kbd({ size = "md", keys, className, children, ...props }: KbdProps) {
+  const { os } = usePlatform();
   return (
     <kbd
       className={cn(
@@ -29,7 +34,9 @@ export function Kbd({ size = "md", className, children, ...props }: KbdProps) {
       )}
       {...props}
     >
-      <span className="inline-flex items-center gap-[inherit] text-trim">{children}</span>
+      <span className="inline-flex items-center gap-[inherit] text-trim">
+        {keys === undefined ? children : formatShortcut(keys, os)}
+      </span>
     </kbd>
   );
 }

package/src/components/message-extras.tsx

@@ -1,6 +1,7 @@
 import { Copy, FileText, X } from "@phosphor-icons/react";
-import { useEffect, useState, type ComponentProps, type ReactNode } from "react";
+import type { ComponentProps, ReactNode } from "react";
 
+import { useCopyToClipboard } from "../hooks/use-copy-to-clipboard";
 import { cn } from "../lib/cn";
 import { IconButton } from "./icon-button";
 import { LiquidGlass } from "./liquid-glass";
@@ -119,25 +120,14 @@ export function CodeBlock({
   className,
   ...props
 }: CodeBlockProps) {
-  const [copied, setCopied] = useState(false);
-  useEffect(() => {
-    if (!copied) return undefined;
-    const timer = setTimeout(() => setCopied(false), 1500);
-    return () => clearTimeout(timer);
-  }, [copied]);
-  const copy = () => {
-    navigator.clipboard?.writeText(code).then(
-      () => setCopied(true),
-      () => undefined,
-    );
-  };
+  const { copied, copy } = useCopyToClipboard(1500);
   return (
     <div className={cn("flex flex-col overflow-clip rounded-lg bg-surface-ink", className)} {...props}>
       <div className="flex items-center gap-2 bg-bg-surface-6 py-2 pr-3.5 pl-3.5 text-caption text-text-on-ink">
         <span className="min-w-0 flex-1 opacity-70">{language}</span>
         <button
           type="button"
-          onClick={copy}
+          onClick={() => copy(code)}
           className="flex shrink-0 motion-press cursor-pointer items-center gap-1 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-text-brand"
         >
           <Copy aria-hidden className="size-3.5 shrink-0" />

package/src/components/segmented-control.tsx

@@ -4,7 +4,7 @@ import { type ReactNode, useRef } from "react";
 
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
-import { useActiveIndicator } from "../lib/use-active-indicator";
+import { useActiveIndicator } from "../hooks/use-active-indicator";
 import { LiquidGlass } from "./liquid-glass";
 
 /** `tab` keeps Paper's page-tab rung beside the three control sizes. */

package/src/components/tab-bar.tsx

@@ -2,7 +2,7 @@ import { type ReactNode, useRef } from "react";
 
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
-import { useActiveIndicator } from "../lib/use-active-indicator";
+import { useActiveIndicator } from "../hooks/use-active-indicator";
 import { LiquidGlass } from "./liquid-glass";
 
 export type TabBarItem = { value: string; label: string; icon: ReactNode };

package/src/components/tool-call.tsx

@@ -1,7 +1,8 @@
 import { Collapsible } from "@base-ui/react/collapsible";
 import { ArrowClockwise, CaretDown, Check, CheckCircle, Copy, WarningCircle } from "@phosphor-icons/react";
-import { useEffect, useState, type ReactNode } from "react";
+import type { ReactNode } from "react";
 
+import { useCopyToClipboard } from "../hooks/use-copy-to-clipboard";
 import { cn } from "../lib/cn";
 import { Button } from "./button";
 import { Spinner } from "./spinner";
@@ -91,12 +92,7 @@ function Section({
   copyText?: string;
   footer?: ReactNode;
 }) {
-  const [copied, setCopied] = useState(false);
-  useEffect(() => {
-    if (!copied) return undefined;
-    const timer = setTimeout(() => setCopied(false), 1500);
-    return () => clearTimeout(timer);
-  }, [copied]);
+  const { copied, copy } = useCopyToClipboard(1500);
   return (
     <div className="flex min-w-0 flex-col gap-1.5">
       <div className="flex items-center gap-2 text-label-sm text-text-secondary">
@@ -105,12 +101,7 @@ function Section({
           <button
             type="button"
             aria-label={copied ? "Copied" : `Copy ${label.toLowerCase()}`}
-            onClick={() => {
-              navigator.clipboard?.writeText(copyText).then(
-                () => setCopied(true),
-                () => undefined,
-              );
-            }}
+            onClick={() => copy(copyText)}
             className="flex motion-press cursor-pointer items-center justify-center rounded-sm hover:text-text-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-text-brand"
           >
             {copied ? (

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+export * from "./use-active-indicator";
+export * from "./use-color-scheme";
+export * from "./use-copy-to-clipboard";
+export * from "./use-device";
+export * from "./use-hotkey";
+export * from "./use-media-query";
+export * from "./use-platform";
+export * from "./use-reduced-motion";

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

@@ -0,0 +1,27 @@
+import { useSyncExternalStore } from "react";
+
+export type ColorScheme = "light" | "dark";
+
+const noop = () => {};
+
+/**
+ * The theme is stored as the `.dark` class on <html> (the site's ThemeToggle
+ * writes it), so that class is the only source — `prefers-color-scheme` is not
+ * consulted.
+ */
+function subscribe(onChange: () => void): () => void {
+  if (typeof document === "undefined" || typeof MutationObserver === "undefined") return noop;
+  const observer = new MutationObserver(onChange);
+  observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });
+  return () => observer.disconnect();
+}
+
+function readIsDark(): boolean {
+  if (typeof document === "undefined") return false;
+  return document.documentElement.classList.contains("dark");
+}
+
+/** The active color scheme; `light` on the server and before hydration. */
+export function useColorScheme(): ColorScheme {
+  return useSyncExternalStore(subscribe, readIsDark, () => false) ? "dark" : "light";
+}

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

@@ -0,0 +1,32 @@
+import { useCallback, useEffect, useState } from "react";
+
+export type CopyToClipboard = {
+  copied: boolean;
+  /** Writes `text`; a failed write leaves `copied` false instead of throwing. */
+  copy: (text: string) => void;
+};
+
+/**
+ * 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.
+ */
+export function useCopyToClipboard(resetMs = 1500): CopyToClipboard {
+  const [copied, setCopied] = useState(false);
+
+  useEffect(() => {
+    if (!copied) return undefined;
+    const timer = setTimeout(() => setCopied(false), resetMs);
+    return () => clearTimeout(timer);
+  }, [copied, resetMs]);
+
+  const copy = useCallback((text: string) => {
+    if (typeof navigator === "undefined" || !navigator.clipboard) return;
+    navigator.clipboard.writeText(text).then(
+      () => setCopied(true),
+      () => undefined,
+    );
+  }, []);
+
+  return { copied, copy };
+}

package/src/hooks/use-device.ts

@@ -0,0 +1,41 @@
+import { useMediaQuery } from "./use-media-query";
+
+export type DeviceType = "mobile" | "tablet" | "desktop";
+
+export type DeviceInput = "touch" | "pointer";
+
+export type Device = {
+  /** `mobile` below 768px, `tablet` for a coarse pointer above that, `desktop` otherwise. */
+  type: DeviceType;
+  input: DeviceInput;
+  /** True only for a hovering fine pointer, the input that can actually reach a key chip. */
+  keyboardHints: boolean;
+};
+
+const MOBILE_QUERY = "(max-width: 767px)";
+const COARSE_QUERY = "(pointer: coarse)";
+const HINTS_QUERY = "(hover: hover) and (pointer: fine)";
+
+/**
+ * `useSyncExternalStore` compares snapshots by reference, so each result is
+ * built once and handed out again.
+ */
+const devices = new Map<string, Device>();
+
+function deviceSnapshot(type: DeviceType, input: DeviceInput, keyboardHints: boolean): Device {
+  const key = `${type}:${input}:${keyboardHints}`;
+  const cached = devices.get(key);
+  if (cached) return cached;
+  const next = { type, input, keyboardHints };
+  devices.set(key, next);
+  return next;
+}
+
+/** The device class and its primary input, as the layout and key hints need them. */
+export function useDevice(): Device {
+  const mobile = useMediaQuery(MOBILE_QUERY);
+  const coarse = useMediaQuery(COARSE_QUERY);
+  const keyboardHints = useMediaQuery(HINTS_QUERY, true);
+  const type: DeviceType = mobile ? "mobile" : coarse ? "tablet" : "desktop";
+  return deviceSnapshot(type, coarse ? "touch" : "pointer", keyboardHints);
+}

package/src/hooks/use-hotkey.ts

@@ -0,0 +1,35 @@
+import { useEffect, useRef } from "react";
+
+import { matchesShortcut } from "../lib/platform";
+import { usePlatform } from "./use-platform";
+
+export type HotkeyOptions = {
+  /** When false the listener is detached and the hotkey does nothing (default true). */
+  enabled?: boolean;
+};
+
+/**
+ * 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.
+ */
+export function useHotkey(keys: string, handler: (event: KeyboardEvent) => void, options: HotkeyOptions = {}) {
+  const { enabled = true } = options;
+  const platform = usePlatform();
+  const handlerRef = useRef(handler);
+
+  useEffect(() => {
+    handlerRef.current = handler;
+  });
+
+  useEffect(() => {
+    if (!enabled) return undefined;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (!matchesShortcut(event, keys, platform.os)) return;
+      event.preventDefault();
+      handlerRef.current(event);
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [keys, enabled, platform.os]);
+}

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

@@ -0,0 +1,25 @@
+import { useCallback, useSyncExternalStore } from "react";
+
+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.
+ */
+export function useMediaQuery(query: string, serverValue = false): boolean {
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      if (typeof window === "undefined" || typeof window.matchMedia !== "function") return noop;
+      const media = window.matchMedia(query);
+      media.addEventListener("change", onChange);
+      return () => media.removeEventListener("change", onChange);
+    },
+    [query],
+  );
+  const getSnapshot = useCallback(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return serverValue;
+    return window.matchMedia(query).matches;
+  }, [query, serverValue]);
+  return useSyncExternalStore(subscribe, getSnapshot, () => serverValue);
+}

package/src/hooks/use-platform.ts

@@ -0,0 +1,39 @@
+import { useSyncExternalStore } from "react";
+
+import { detectOs, detectRuntime, readNavigator, type Os, type Runtime } from "../lib/platform";
+
+export type ModKey = "meta" | "ctrl";
+
+export type Platform = {
+  os: Os;
+  runtime: Runtime;
+  /** The physical key behind `Mod` on this OS, ready for a keydown check. */
+  modKey: ModKey;
+};
+
+const noop = () => {};
+
+/** What a server render and the first hydration pass assume. */
+const SERVER_PLATFORM: Platform = { os: "unknown", runtime: "web", modKey: "meta" };
+
+/**
+ * The OS and shell do not change while a tab is open, so the platform is read
+ * once and every later render reuses the same object.
+ */
+let clientPlatform: Platform | null = null;
+
+function readPlatform(): Platform {
+  if (typeof window === "undefined") return SERVER_PLATFORM;
+  if (clientPlatform) return clientPlatform;
+  const os = detectOs(readNavigator());
+  const modKey: ModKey = os === "windows" || os === "linux" || os === "android" ? "ctrl" : "meta";
+  clientPlatform = { os, runtime: detectRuntime(window), modKey };
+  return clientPlatform;
+}
+
+const subscribe = (_onChange: () => void) => noop;
+
+/** The current OS, browser or desktop shell, and the key that means `Mod`. */
+export function usePlatform(): Platform {
+  return useSyncExternalStore(subscribe, readPlatform, () => SERVER_PLATFORM);
+}

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

@@ -0,0 +1,8 @@
+import { useMediaQuery } from "./use-media-query";
+
+const QUERY = "(prefers-reduced-motion: reduce)";
+
+/** True while the OS asks for reduced motion; false on the server. */
+export function useReducedMotion(): boolean {
+  return useMediaQuery(QUERY);
+}

package/src/index.ts

@@ -82,5 +82,18 @@ export * from "./components/tooltip";
 export * from "./components/top-bar";
 export * from "./components/usage-meter";
 export * from "./components/workspace-menu";
+export * from "./hooks";
 export { cn, type ClassValue } from "./lib/cn";
 export { mountCursorGhost, type CursorGhostOptions } from "./lib/cursor-ghost";
+export {
+  detectOs,
+  detectRuntime,
+  formatShortcut,
+  isModKey,
+  matchesShortcut,
+  type Os,
+  type PlatformInput,
+  type Runtime,
+  type RuntimeWindow,
+  type ShortcutEvent,
+} from "./lib/platform";

package/src/lib/platform.ts

@@ -0,0 +1,169 @@
+export type Os = "macos" | "windows" | "linux" | "ios" | "android" | "unknown";
+
+export type Runtime = "web" | "desktop";
+
+/** The parts of `navigator` that identify the OS; plain data so detection stays testable. */
+export type PlatformInput = {
+  userAgent?: string;
+  platform?: string;
+  uaPlatform?: string;
+  maxTouchPoints?: number;
+};
+
+/** The parts of `window` that tell a page from the desktop shell; plain data for the same reason. */
+export type RuntimeWindow = {
+  __TAURI_INTERNALS__?: unknown;
+  navigator?: { userAgent?: string };
+};
+
+/** The parts of a keyboard event a shortcut reads; `KeyboardEvent` satisfies it as-is. */
+export type ShortcutEvent = {
+  key?: string;
+  metaKey?: boolean;
+  ctrlKey?: boolean;
+  altKey?: boolean;
+  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.
+ */
+export function readNavigator(): PlatformInput {
+  if (typeof navigator === "undefined") return {};
+  const nav = navigator as {
+    userAgent?: string;
+    platform?: string;
+    maxTouchPoints?: number;
+    userAgentData?: { platform?: string };
+  };
+  return {
+    userAgent: nav.userAgent,
+    platform: nav.platform,
+    uaPlatform: nav.userAgentData?.platform,
+    maxTouchPoints: nav.maxTouchPoints,
+  };
+}
+
+const OS_HINTS = ["uaPlatform", "platform", "userAgent"] as const;
+
+/** Classifies one hint string; `undefined` when the hint names no OS we know. */
+function osFromHint(hint: string, maxTouchPoints: number): Os | undefined {
+  if (hint.includes("android")) return "android";
+  if (hint.includes("iphone") || hint.includes("ipad") || hint.includes("ipod") || hint.includes("ios")) return "ios";
+  // iPadOS reports a Mac platform and user agent, so touch points are what separate it from a Mac.
+  if (hint.includes("mac")) return maxTouchPoints > 1 ? "ios" : "macos";
+  if (hint.includes("win")) return "windows";
+  if (hint.includes("linux") || hint.includes("x11") || hint.includes("cros") || hint.includes("bsd")) return "linux";
+  return 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.
+ */
+export function detectOs(input: PlatformInput = {}): Os {
+  const maxTouchPoints = input.maxTouchPoints ?? 0;
+  for (const field of OS_HINTS) {
+    const hint = (input[field] ?? "").trim().toLowerCase();
+    if (!hint) continue;
+    const os = osFromHint(hint, maxTouchPoints);
+    if (os) return os;
+  }
+  return "unknown";
+}
+
+/** `desktop` for the Tauri shell and Electron; `web` everywhere else, including the server. */
+export function detectRuntime(win: RuntimeWindow | null = null): Runtime {
+  if (!win) return "web";
+  if ("__TAURI_INTERNALS__" in win) return "desktop";
+  return /electron/i.test(win.navigator?.userAgent ?? "") ? "desktop" : "web";
+}
+
+const MAC_LABELS: Record<string, string> = {
+  mod: "⌘",
+  shift: "⇧",
+  alt: "⌥",
+  enter: "↵",
+  escape: "esc",
+  esc: "esc",
+  arrowup: "↑",
+  arrowdown: "↓",
+  arrowleft: "←",
+  arrowright: "→",
+};
+
+const OTHER_LABELS: Record<string, string> = {
+  mod: "Ctrl",
+  shift: "Shift",
+  alt: "Alt",
+  enter: "Enter",
+  escape: "Esc",
+  esc: "Esc",
+  arrowup: "↑",
+  arrowdown: "↓",
+  arrowleft: "←",
+  arrowright: "→",
+};
+
+/**
+ * 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 `+`.
+ */
+export function formatShortcut(keys: string, os: Os): string {
+  const parts = keys
+    .split("+")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (parts.length === 0) return "";
+  // macOS, iOS and the unknown server default draw Mac symbols; everyone else spells them out.
+  const mac = os === "macos" || os === "ios" || os === "unknown";
+  const labels = mac ? MAC_LABELS : OTHER_LABELS;
+  return parts.map((part) => labels[part.toLowerCase()] ?? part).join(mac ? "" : "+");
+}
+
+/** Which physical key carries `Mod` for an OS; `either` is the server/unknown case. */
+function modifierSlot(os: Os): "meta" | "ctrl" | "either" {
+  if (os === "macos" || os === "ios") return "meta";
+  if (os === "windows" || os === "linux" || os === "android") return "ctrl";
+  return "either";
+}
+
+/** True when the platform's `Mod` key is down; the other side's key is not `Mod`. */
+export function isModKey(event: ShortcutEvent, os: Os): boolean {
+  const slot = modifierSlot(os);
+  const meta = event.metaKey === true;
+  const ctrl = event.ctrlKey === true;
+  if (slot === "meta") return meta && !ctrl;
+  if (slot === "ctrl") return ctrl && !meta;
+  return meta || ctrl;
+}
+
+/** Modifier names that are never the final key of a shortcut. */
+const MODIFIERS: Record<string, true> = { mod: true, shift: true, alt: true, ctrl: true, meta: true };
+
+const KEY_ALIASES: Record<string, string> = { esc: "escape" };
+
+function canonicalKey(value: string): string {
+  const lower = value.trim().toLowerCase();
+  return KEY_ALIASES[lower] ?? lower;
+}
+
+/**
+ * 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).
+ */
+export function matchesShortcut(event: ShortcutEvent, keys: string, os: Os): boolean {
+  const parts = keys
+    .split("+")
+    .map((part) => part.trim().toLowerCase())
+    .filter(Boolean);
+  const base = parts.find((part) => !MODIFIERS[part]);
+  if (!base) return false;
+  if ((event.altKey === true) !== parts.includes("alt")) return false;
+  if ((event.shiftKey === true) !== parts.includes("shift")) return false;
+  if (isModKey(event, os) !== parts.includes("mod")) return false;
+  return canonicalKey(event.key ?? "") === canonicalKey(base);
+}