@horon-ai/react 0.0.0-stage → 0.1.1

package/src/components/tool-calls-header.tsx

@@ -0,0 +1,65 @@
+import { Collapsible } from "@base-ui/react/collapsible";
+import { CaretDown } from "@phosphor-icons/react";
+import { Children, type ReactNode } from "react";
+
+import { cn } from "../lib/cn";
+
+export type ToolCallsHeaderProps = {
+  /** Up to three 14px tool icons, drawn as overlapping 28px chips. */
+  icons?: ReactNode;
+  title?: ReactNode;
+  /** Elapsed time, such as "4.0s". */
+  elapsed?: ReactNode;
+  /** `ToolCall` cards, stacked 8px apart under the header. */
+  children?: ReactNode;
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  className?: string;
+};
+
+/** Figma `Tool-calls header` (Agents N11): overlapping tool chips, "Using tools…" and a caret that fold the ToolCall cards below. */
+export function ToolCallsHeader({
+  icons,
+  title = "Using tools…",
+  elapsed,
+  children,
+  defaultOpen = true,
+  open,
+  onOpenChange,
+  className,
+}: ToolCallsHeaderProps) {
+  const chips = Children.toArray(icons).slice(0, 3);
+  return (
+    <Collapsible.Root
+      defaultOpen={defaultOpen}
+      open={open}
+      onOpenChange={onOpenChange}
+      className={cn(
+        "flex w-full min-w-0 flex-col rounded-xl border border-border-default bg-bg-surface p-3",
+        className,
+      )}
+    >
+      <Collapsible.Trigger className="group flex w-full min-w-0 cursor-pointer items-center gap-2.5 pb-1 text-left focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-text-brand">
+        {chips.length > 0 && (
+          <span className="flex shrink-0 items-center">
+            {Children.map(chips, (icon) => (
+              <span className="-ml-2 flex size-7 shrink-0 items-center justify-center rounded-[10px] bg-bg-subtle text-text-secondary ring-2 ring-bg-surface first:ml-0 [&>svg]:size-3.5">
+                {icon}
+              </span>
+            ))}
+          </span>
+        )}
+        <span className="min-w-0 truncate text-label-md text-text-primary">{title}</span>
+        {elapsed && <span className="shrink-0 text-label-md text-text-secondary">· {elapsed}</span>}
+        <CaretDown
+          aria-hidden
+          className="ml-auto size-4 shrink-0 text-text-secondary transition-transform duration-200 ease-out-quint group-data-panel-open:rotate-180"
+        />
+      </Collapsible.Trigger>
+      <Collapsible.Panel className="motion-collapse">
+        <div className="flex min-w-0 flex-col gap-2 pt-1">{children}</div>
+      </Collapsible.Panel>
+    </Collapsible.Root>
+  );
+}

package/src/components/tool-permissions.tsx

@@ -0,0 +1,105 @@
+import { type ComponentProps, type ReactNode, useState } from "react";
+
+import { cn } from "../lib/cn";
+import { SegmentedControl } from "./segmented-control";
+
+export type ToolPermission = "allow" | "ask" | "off";
+
+export type ToolPermissionItem = {
+  name: string;
+  description?: ReactNode;
+  /** Starting choice for the uncontrolled component; defaults to `ask`. */
+  defaultValue?: ToolPermission;
+};
+
+export type ToolPermissionsProps = Omit<ComponentProps<"div">, "className" | "title" | "onChange"> & {
+  title: ReactNode;
+  tools: ToolPermissionItem[];
+  /** Controlled choices keyed by tool name. */
+  values?: Record<string, ToolPermission>;
+  onValuesChange?: (values: Record<string, ToolPermission>) => void;
+  /** Label of the text button that sets every tool to Allow. */
+  allowAllLabel?: ReactNode;
+  className?: string;
+};
+
+const options: { value: ToolPermission; label: string }[] = [
+  { value: "allow", label: "Allow" },
+  { value: "ask", label: "Ask" },
+  { value: "off", label: "Off" },
+];
+
+/**
+ * Paper `Tool permissions` (1VT5-0): one solid card, 16px radius with a default border. A subtle header
+ * carries the group title, a count pill and an "Allow all" text button; below it one divided row per tool
+ * with a mono name, a description and a small solid Allow / Ask / Off segmented control. 16px side padding
+ * on every row so the names, the header title and the controls line up.
+ */
+export function ToolPermissions({
+  title,
+  tools,
+  values,
+  onValuesChange,
+  allowAllLabel = "Allow all",
+  className,
+  ...props
+}: ToolPermissionsProps) {
+  const [inner, setInner] = useState<Record<string, ToolPermission>>(() =>
+    Object.fromEntries(tools.map((tool) => [tool.name, tool.defaultValue ?? "ask"])),
+  );
+  const current = values ?? inner;
+  const update = (next: Record<string, ToolPermission>) => {
+    setInner(next);
+    onValuesChange?.(next);
+  };
+  return (
+    <div
+      className={cn(
+        "flex w-full max-w-130 min-w-0 flex-col overflow-clip rounded-2xl border border-border-default bg-bg-surface",
+        className,
+      )}
+      {...props}
+    >
+      <div className="flex h-11 items-center gap-2 border-b border-border-default bg-bg-subtle px-4">
+        <span className="min-w-0 truncate text-label-md font-semibold text-text-primary">{title}</span>
+        <span className="inline-flex h-5 shrink-0 items-center rounded-full bg-overlay-ink-6 px-1.5 text-label-sm text-text-secondary">
+          <span className="text-trim">{tools.length}</span>
+        </span>
+        <span className="min-w-0 flex-1" />
+        <button
+          type="button"
+          className="shrink-0 cursor-pointer rounded-sm text-label-sm whitespace-nowrap text-text-secondary motion-colors hover:text-text-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-text-brand"
+          onClick={() => update(Object.fromEntries(tools.map((tool) => [tool.name, "allow" as const])))}
+        >
+          {allowAllLabel}
+        </button>
+      </div>
+      {tools.map((tool) => (
+        <div
+          key={tool.name}
+          className="flex flex-wrap items-center gap-x-4 gap-y-2 border-b border-border-default px-4 py-3 last:border-b-0"
+        >
+          <div className="flex min-w-0 grow basis-40 flex-col gap-1">
+            <span className="truncate font-mono text-code font-medium text-text-primary">{tool.name}</span>
+            {tool.description && (
+              <span className="text-caption wrap-break-word text-text-secondary">{tool.description}</span>
+            )}
+          </div>
+          <SegmentedControl
+            aria-label={`${tool.name} permission`}
+            size="sm"
+            surface="solid"
+            fill={false}
+            className="shrink-0"
+            items={options}
+            value={current[tool.name] ?? "ask"}
+            onValueChange={(value) => {
+              const next = options.find((option) => option.value === value);
+              if (next) update({ ...current, [tool.name]: next.value });
+            }}
+          />
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/tooltip.tsx

@@ -0,0 +1,33 @@
+import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip";
+import type { ReactElement, ReactNode } from "react";
+
+export type TooltipProps = {
+  /** The element that shows the tooltip on hover and focus. */
+  children: ReactElement;
+  label: ReactNode;
+  side?: "top" | "bottom" | "left" | "right";
+  delay?: number;
+};
+
+/** Figma `Tooltip` (62:282): an ink bubble, 10/6px padding, 8px radius, with a 10x6 arrow. */
+export function Tooltip({ children, label, side = "top", delay }: TooltipProps) {
+  return (
+    <BaseTooltip.Root>
+      <BaseTooltip.Trigger delay={delay} render={children} />
+      <BaseTooltip.Portal>
+        <BaseTooltip.Positioner side={side} sideOffset={6} className="z-50">
+          <BaseTooltip.Popup className="flex max-w-64 motion-popup rounded-sm bg-interactive-primary px-2.5 py-1.5 text-label-sm text-balance text-interactive-on-primary duration-150">
+            {label}
+            <BaseTooltip.Arrow className="flex data-[side=bottom]:-top-1.5 data-[side=bottom]:rotate-180 data-[side=left]:-right-2 data-[side=left]:-rotate-90 data-[side=right]:-left-2 data-[side=right]:rotate-90 data-[side=top]:-bottom-1.5">
+              <svg width="10" height="6" viewBox="0 0 10 6" aria-hidden className="fill-interactive-primary">
+                <path d="M0.67 1.5h8.66L5 6z" />
+              </svg>
+            </BaseTooltip.Arrow>
+          </BaseTooltip.Popup>
+        </BaseTooltip.Positioner>
+      </BaseTooltip.Portal>
+    </BaseTooltip.Root>
+  );
+}
+
+export const TooltipProvider = BaseTooltip.Provider;

package/src/components/top-bar.tsx

@@ -0,0 +1,65 @@
+import { CaretLeft, DotsThree } from "@phosphor-icons/react";
+import type { ComponentProps, ReactNode } from "react";
+
+import { cn } from "../lib/cn";
+import { Avatar } from "./avatar";
+import { IconButton } from "./icon-button";
+import { LiquidGlass } from "./liquid-glass";
+
+export type TopBarProps = Omit<ComponentProps<"header">, "className" | "title"> & {
+  title: ReactNode;
+  subtitle?: ReactNode;
+  /** Shows the live status dot on the avatar. */
+  live?: boolean;
+  onBack?: () => void;
+  onMore?: () => void;
+  backLabel?: string;
+  moreLabel?: string;
+  /** `solid` (default) is an opaque surface bar with a default border; `glass` is the regular glass bar. */
+  surface?: "solid" | "glass";
+  className?: string;
+};
+
+/** Paper `Top bar`: back button, bot avatar with a flush live dot, title and subtitle, on solid surface or regular glass. */
+export function TopBar({
+  title,
+  subtitle,
+  live,
+  onBack,
+  onMore,
+  backLabel = "Back",
+  moreLabel = "More",
+  surface = "solid",
+  className,
+  ...props
+}: TopBarProps) {
+  return (
+    <header
+      className={cn(
+        "relative z-10 flex items-center gap-2 overflow-clip rounded-full p-2",
+        surface === "glass" ? "bg-glass-regular" : "border border-border-default bg-bg-surface",
+        className,
+      )}
+      {...props}
+    >
+      {surface === "glass" && <LiquidGlass />}
+      {onBack && <IconButton icon={<CaretLeft />} label={backLabel} onClick={onBack} />}
+      <span className="relative inline-flex shrink-0">
+        <Avatar type="bot" size="md" />
+        {live && (
+          <span aria-hidden className="absolute right-0 bottom-0 flex animate-pop-in">
+            <span className="size-[9px] animate-live-pulse rounded-full bg-status-live text-status-live" />
+          </span>
+        )}
+      </span>
+      <div
+        key={typeof title === "string" ? `${title}|${typeof subtitle === "string" ? subtitle : ""}` : undefined}
+        className="relative flex min-w-0 flex-1 animate-fade-in flex-col overflow-clip"
+      >
+        <span className="truncate text-label-lg text-text-primary">{title}</span>
+        {subtitle && <span className="truncate text-caption text-text-secondary">{subtitle}</span>}
+      </div>
+      {onMore && <IconButton icon={<DotsThree weight="bold" />} label={moreLabel} onClick={onMore} />}
+    </header>
+  );
+}

package/src/components/usage-meter.tsx

@@ -0,0 +1,47 @@
+import { Meter } from "@base-ui/react/meter";
+import type { ReactNode } from "react";
+
+import { cn } from "../lib/cn";
+import { LiquidGlass } from "./liquid-glass";
+
+export type UsageMeterProps = {
+  label: ReactNode;
+  /** 0-100. */
+  value: number;
+  /** Left caption, such as "6,420 of 10,000 tasks". */
+  detail?: ReactNode;
+  /** Right caption, such as "Resets Nov 1". */
+  note?: ReactNode;
+  /** `solid` (default) is an opaque surface card with a default border; `glass` is the thick glass card. */
+  surface?: "solid" | "glass";
+  className?: string;
+};
+
+/** Figma `Usage meter` (in Loading 109:733): a card with a 6px sky fill, solid or thick glass. */
+export function UsageMeter({ label, value, detail, note, surface = "solid", className }: UsageMeterProps) {
+  return (
+    <Meter.Root
+      value={value}
+      className={cn(
+        "relative flex w-full max-w-75 min-w-0 flex-col gap-2 overflow-clip rounded-xl p-4",
+        surface === "glass" ? "bg-glass-thick" : "border border-border-default bg-bg-surface",
+        className,
+      )}
+    >
+      {surface === "glass" && <LiquidGlass />}
+      <div className="relative flex w-full items-center gap-2 text-label-md">
+        <Meter.Label className="min-w-0 flex-1 text-text-primary">{label}</Meter.Label>
+        <Meter.Value className="shrink-0 text-text-secondary tabular-nums" />
+      </div>
+      <Meter.Track className="relative h-1.5 w-full overflow-clip rounded-full bg-overlay-ink-8">
+        <Meter.Indicator className="h-full rounded-full bg-sky-500 transition-[width] duration-400 ease-out-quint" />
+      </Meter.Track>
+      {(detail || note) && (
+        <div className="relative flex w-full items-center gap-2 text-caption text-text-secondary">
+          <span className="min-w-0 flex-1">{detail}</span>
+          {note && <span className="shrink-0 whitespace-nowrap">{note}</span>}
+        </div>
+      )}
+    </Meter.Root>
+  );
+}

package/src/components/workspace-menu.tsx

@@ -0,0 +1,77 @@
+import { Check, GearSix, PlusCircle } from "@phosphor-icons/react";
+import type { ComponentProps, ReactNode } from "react";
+
+import { cn } from "../lib/cn";
+import { Menu, MenuContent, MenuItem, MenuLabel, MenuSeparator, MenuTile, MenuTrigger } from "./menu";
+
+export type WorkspaceMenuItem = {
+  id: string;
+  name: string;
+  /** Caption under the name, such as "12 members". */
+  meta?: ReactNode;
+  /** Tile initial; defaults to the first letter of the name. */
+  initial?: string;
+};
+
+export type WorkspaceMenuProps = {
+  workspaces: WorkspaceMenuItem[];
+  value: string;
+  onValueChange?: (id: string) => void;
+  onCreate?: () => void;
+  onSettings?: () => void;
+  /** The element that opens the menu, such as the sidebar workspace button. */
+  trigger: ComponentProps<typeof MenuTrigger>["render"];
+  triggerChildren?: ReactNode;
+  triggerClassName?: string;
+  label?: ReactNode;
+  className?: string;
+};
+
+/** Paper `Workspace menu`: solid 256px menu listing workspaces with a check on the current one. */
+export function WorkspaceMenu({
+  workspaces,
+  value,
+  onValueChange,
+  onCreate,
+  onSettings,
+  trigger,
+  triggerChildren,
+  triggerClassName,
+  label = "Workspaces",
+  className,
+}: WorkspaceMenuProps) {
+  return (
+    <Menu>
+      <MenuTrigger render={trigger} className={triggerClassName}>
+        {triggerChildren}
+      </MenuTrigger>
+      <MenuContent surface="solid" side="bottom" align="start" sideOffset={7} className={className}>
+        <MenuLabel>{label}</MenuLabel>
+        {workspaces.map((workspace) => (
+          <MenuItem
+            key={workspace.id}
+            icon={<MenuTile>{workspace.initial ?? workspace.name.charAt(0).toUpperCase()}</MenuTile>}
+            description={workspace.meta}
+            selected={workspace.id === value}
+            trailing={
+              <Check
+                weight="bold"
+                className={cn("transition-opacity duration-150", workspace.id === value ? "opacity-100" : "opacity-0")}
+              />
+            }
+            onClick={() => onValueChange?.(workspace.id)}
+          >
+            {workspace.name}
+          </MenuItem>
+        ))}
+        <MenuSeparator />
+        <MenuItem icon={<PlusCircle />} onClick={onCreate}>
+          New workspace
+        </MenuItem>
+        <MenuItem icon={<GearSix />} onClick={onSettings}>
+          Workspace settings
+        </MenuItem>
+      </MenuContent>
+    </Menu>
+  );
+}

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-active-indicator.ts

@@ -0,0 +1,60 @@
+import { type RefObject, useEffect, useLayoutEffect, useState } from "react";
+
+export type IndicatorRect = { left: number; top: number; width: number; height: number };
+
+/**
+ * Measures the active item inside a positioned track so one indicator can slide
+ * between items. `selector` finds the active item (for example `[data-pressed]`
+ * or `[aria-current="page"]`); the rect follows attribute changes and resizes.
+ * `animate` turns true one frame after the first placement, so the indicator
+ * lands in place instead of sliding in from 0,0.
+ */
+export function useActiveIndicator(track: RefObject<HTMLElement | null>, selector: string) {
+  const [rect, setRect] = useState<IndicatorRect | null>(null);
+  const [animate, setAnimate] = useState(false);
+
+  useLayoutEffect(() => {
+    const element = track.current;
+    if (!element) return undefined;
+    const measure = () => {
+      const active = element.querySelector<HTMLElement>(selector);
+      if (!active) {
+        setRect(null);
+        return;
+      }
+      const next = {
+        left: active.offsetLeft,
+        top: active.offsetTop,
+        width: active.offsetWidth,
+        height: active.offsetHeight,
+      };
+      setRect((previous) =>
+        previous &&
+        previous.left === next.left &&
+        previous.top === next.top &&
+        previous.width === next.width &&
+        previous.height === next.height
+          ? previous
+          : next,
+      );
+    };
+    measure();
+    const resize = new ResizeObserver(measure);
+    resize.observe(element);
+    for (const child of Array.from(element.children)) resize.observe(child);
+    const mutation = new MutationObserver(measure);
+    mutation.observe(element, { attributes: true, subtree: true, childList: true });
+    return () => {
+      resize.disconnect();
+      mutation.disconnect();
+    };
+  }, [track, selector]);
+
+  useEffect(() => {
+    if (!rect || animate) return undefined;
+    const frame = requestAnimationFrame(() => setAnimate(true));
+    return () => cancelAnimationFrame(frame);
+  }, [rect, animate]);
+
+  return { rect, animate };
+}

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);
+}