@flamingo-stack/openframe-frontend-core 0.0.705 → 0.0.706-snapshot.20261006190707

package/src/hooks/ui/use-nav-menus.ts

@@ -0,0 +1,200 @@
+'use client';
+
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type MouseEvent as ReactMouseEvent,
+  type RefCallback,
+} from 'react';
+
+export interface UseNavMenusOptions {
+  /** The host router's pathname: any change closes the open menu. */
+  pathname: string;
+  /** Hover intent: how long the pointer rests on a trigger before it opens. */
+  hoverOpenMs?: number;
+  /** How long after the pointer left the trigger and the panel the menu closes. */
+  hoverCloseMs?: number;
+}
+
+export interface NavMenuTriggerProps {
+  ref: RefCallback<HTMLElement>;
+  'aria-expanded': boolean;
+  'aria-controls': string;
+  onClick: (event: ReactMouseEvent) => void;
+  onMouseEnter: () => void;
+  onMouseLeave: () => void;
+}
+
+export interface NavMenuPanelProps {
+  ref: RefCallback<HTMLElement>;
+  id: string;
+  inert: boolean;
+  'data-state': 'open' | 'closed';
+  onMouseEnter: () => void;
+  onMouseLeave: () => void;
+}
+
+export interface UseNavMenusResult {
+  /** The id of the open menu, or `null`. One menu is open at a time. */
+  openId: string | null;
+  close: () => void;
+  getTriggerProps: (id: string) => NavMenuTriggerProps;
+  getPanelProps: (id: string) => NavMenuPanelProps;
+}
+
+/**
+ * Open state for a row of disclosure menus (the site header's dropdowns and
+ * mega menus).
+ *
+ * - Click toggles; the trigger is a `<button>`, so Enter and Space arrive as
+ *   that same click.
+ * - Hover on a trigger opens after `hoverOpenMs`; with a menu already open,
+ *   hovering another trigger switches to it at once. Leaving the trigger and the
+ *   panel closes after `hoverCloseMs`; entering the panel or any trigger
+ *   cancels that close, so the pointer can cross the gap between them.
+ * - Escape closes and returns focus to the trigger. A pointer-down outside
+ *   every trigger and panel closes. A `pathname` change closes.
+ * - No arrow-key roving: these are plain disclosures, Tab moves in DOM order.
+ */
+export function useNavMenus({
+  pathname,
+  hoverOpenMs = 150,
+  hoverCloseMs = 300,
+}: UseNavMenusOptions): UseNavMenusResult {
+  const baseId = useId();
+  // The open menu is remembered WITH the pathname it was opened on, so a
+  // navigation closes it during render: no effect, no frame of a stale panel.
+  // The stale entry is dropped in the same render, or coming back to that
+  // pathname would reopen it.
+  const [opened, setOpened] = useState<{ id: string; pathname: string } | null>(null);
+  const stale = opened !== null && opened.pathname !== pathname;
+  if (stale) setOpened(null);
+  const openId = opened && !stale ? opened.id : null;
+
+  const triggers = useRef(new Map<string, HTMLElement>());
+  const panels = useRef(new Map<string, HTMLElement>());
+  const openTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // The menu a HOVER opened, until a click claims it (see `onClick`).
+  const openedByHover = useRef<string | null>(null);
+
+  const clearTimers = useCallback(() => {
+    if (openTimer.current) clearTimeout(openTimer.current);
+    if (closeTimer.current) clearTimeout(closeTimer.current);
+    openTimer.current = null;
+    closeTimer.current = null;
+  }, []);
+
+  useEffect(() => clearTimers, [clearTimers]);
+
+  const close = useCallback(() => {
+    clearTimers();
+    setOpened(null);
+  }, [clearTimers]);
+
+  const cancelClose = useCallback(() => {
+    if (closeTimer.current) clearTimeout(closeTimer.current);
+    closeTimer.current = null;
+  }, []);
+
+  const scheduleClose = useCallback(() => {
+    if (openTimer.current) clearTimeout(openTimer.current);
+    openTimer.current = null;
+    cancelClose();
+    closeTimer.current = setTimeout(() => {
+      closeTimer.current = null;
+      setOpened(null);
+    }, hoverCloseMs);
+  }, [cancelClose, hoverCloseMs]);
+
+  useEffect(() => {
+    if (!openId) return undefined;
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape') return;
+      const trigger = triggers.current.get(openId);
+      close();
+      trigger?.focus({ preventScroll: true });
+    };
+    const handlePointerDown = (event: PointerEvent) => {
+      const target = event.target;
+      if (!(target instanceof Node)) return;
+      for (const el of triggers.current.values()) if (el.contains(target)) return;
+      for (const el of panels.current.values()) if (el.contains(target)) return;
+      close();
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    document.addEventListener('pointerdown', handlePointerDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+      document.removeEventListener('pointerdown', handlePointerDown);
+    };
+  }, [openId, close]);
+
+  const getTriggerProps = useCallback(
+    (id: string): NavMenuTriggerProps => ({
+      ref: el => {
+        if (el) triggers.current.set(id, el);
+        else triggers.current.delete(id);
+      },
+      'aria-expanded': openId === id,
+      'aria-controls': `${baseId}-panel-${id}`,
+      onClick: () => {
+        // A touch tap fires mouseenter first: drop its pending open, or it
+        // would reopen the menu this click just closed.
+        clearTimers();
+        // A click on a menu the pointer's hover already opened means "open
+        // it": it keeps the menu open instead of toggling it shut (a mouse
+        // user hovers, then clicks; a touch tap fires mouseenter, then click).
+        // The click claims the menu, so the next click on it closes it.
+        const hovered = openedByHover.current === id;
+        openedByHover.current = null;
+        if (hovered) {
+          setOpened({ id, pathname });
+          return;
+        }
+        setOpened(prev => (prev && prev.id === id && prev.pathname === pathname ? null : { id, pathname }));
+      },
+      onMouseEnter: () => {
+        clearTimers();
+        if (openId === id) return;
+        // A menu is already open: the visitor is browsing the row, so the next
+        // one opens at once. The hover-intent wait is only for the FIRST open
+        // (it filters a pointer merely crossing the bar).
+        if (openId !== null) {
+          openedByHover.current = id;
+          setOpened({ id, pathname });
+          return;
+        }
+        openTimer.current = setTimeout(() => {
+          openTimer.current = null;
+          openedByHover.current = id;
+          setOpened({ id, pathname });
+        }, hoverOpenMs);
+      },
+      onMouseLeave: scheduleClose,
+    }),
+    [baseId, openId, pathname, hoverOpenMs, clearTimers, scheduleClose],
+  );
+
+  const getPanelProps = useCallback(
+    (id: string): NavMenuPanelProps => ({
+      ref: el => {
+        if (el) panels.current.set(id, el);
+        else panels.current.delete(id);
+      },
+      id: `${baseId}-panel-${id}`,
+      inert: openId !== id,
+      'data-state': openId === id ? 'open' : 'closed',
+      onMouseEnter: cancelClose,
+      onMouseLeave: scheduleClose,
+    }),
+    [baseId, openId, cancelClose, scheduleClose],
+  );
+
+  return { openId, close, getTriggerProps, getPanelProps };
+}

package/src/hooks/ui/use-visitor-os.ts

@@ -0,0 +1,33 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+import { detectVisitorOs, type VisitorOs } from '../../utils/visitor-os';
+
+export type VisitorOsState = { known: false; os: null } | { known: true; os: VisitorOs | null };
+
+const UNKNOWN: VisitorOsState = { known: false, os: null };
+// One state object per answer, so the snapshot is stable between reads.
+const KNOWN = new Map<VisitorOs | null, VisitorOsState>();
+
+const subscribe = () => () => {};
+const getServerSnapshot = () => UNKNOWN;
+function getSnapshot(): VisitorOsState {
+  // `userAgentData` is the Client Hints API (Chromium only, so not in every DOM typing).
+  const stated = (navigator as Navigator & { userAgentData?: { platform?: string } }).userAgentData?.platform;
+  const os = detectVisitorOs(navigator.userAgent, { platform: stated, maxTouchPoints: navigator.maxTouchPoints });
+  let state = KNOWN.get(os);
+  if (!state) {
+    state = { known: true, os };
+    KNOWN.set(os, state);
+  }
+  return state;
+}
+
+/**
+ * The visitor's system in the browser, through the one detection rule
+ * (`utils/visitor-os`). `known` is false on the server and while React
+ * hydrates: the server cannot see the browser, and a guess would mismatch.
+ */
+export function useVisitorOs(): VisitorOsState {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/src/hooks/use-location-hash.ts

@@ -0,0 +1,34 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+import { normalizeHashFragment } from '../utils/same-page-hash-nav';
+
+/** `navigateSamePageHash` dispatches `hashchange` itself; `popstate` covers back and forward. */
+const HASH_EVENTS = ['hashchange', 'popstate'] as const;
+
+function subscribe(onChange: () => void): () => void {
+  for (const event of HASH_EVENTS) window.addEventListener(event, onChange);
+  return () => {
+    for (const event of HASH_EVENTS) window.removeEventListener(event, onChange);
+  };
+}
+
+function readHash(): string {
+  const raw = normalizeHashFragment(window.location.hash).replace(/^#/, '');
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * The URL's hash without its `#`, or `''`: the READ side of same-page anchor
+ * navigation (`navigateSamePageHash` writes it, `useScrollToHash` scrolls to
+ * it). For a component whose state follows the anchor: a tab group that opens
+ * the tab a link names. Empty on the server and during hydration (the server
+ * never sees a hash), then the real one.
+ */
+export function useLocationHash(): string {
+  return useSyncExternalStore(subscribe, readHash, () => '');
+}

package/src/styles/chat-animations.css

@@ -134,12 +134,12 @@
   }
 }
 
-/* Ring mask: clips the rotating conic layer to a 3px band along the frame's
+/* Ring mask: clips the rotating conic layer to a 1px band along the frame's
    rounded outline (padding-box XOR), so the interior stays fully transparent
    and the host background shows through — no opaque cover element. */
 .mingo-edge-frame {
   overflow: hidden;
-  padding: 3px;
+  padding: 1px;
   -webkit-mask:
     linear-gradient(#fff 0 0) content-box,
     linear-gradient(#fff 0 0);
@@ -198,3 +198,58 @@
     opacity: 0;
   }
 }
+
+/* -----------------------------------------------------------------------------
+ * Site header mega menus: how a panel's CONTENT arrives.
+ *   open        from a closed bar: a short fade and settle.
+ *   from-start  from the menu before it in the row: slides in from the left.
+ *   from-end    from the menu after it: slides in from the right.
+ * Between two mega menus the surface itself does not animate (NavPanel hands it
+ * over in one frame), so only the content moves, in the direction the pointer
+ * travelled. Short and ease-out: it must never make the menu feel slower.
+ * Reduced motion: no movement, a plain fade.
+ * ---------------------------------------------------------------------------*/
+@keyframes nav-panel-open {
+  from {
+    opacity: 0;
+    transform: translateY(-4px);
+  }
+}
+
+@keyframes nav-panel-from-start {
+  from {
+    opacity: 0;
+    transform: translateX(-24px);
+  }
+}
+
+@keyframes nav-panel-from-end {
+  from {
+    opacity: 0;
+    transform: translateX(24px);
+  }
+}
+
+@keyframes nav-panel-fade {
+  from {
+    opacity: 0;
+  }
+}
+
+.nav-panel-content[data-motion='open'] {
+  animation: nav-panel-open 180ms cubic-bezier(0.2, 0, 0, 1);
+}
+
+.nav-panel-content[data-motion='from-start'] {
+  animation: nav-panel-from-start 220ms cubic-bezier(0.2, 0, 0, 1);
+}
+
+.nav-panel-content[data-motion='from-end'] {
+  animation: nav-panel-from-end 220ms cubic-bezier(0.2, 0, 0, 1);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .nav-panel-content[data-motion] {
+    animation: nav-panel-fade 120ms linear;
+  }
+}

package/src/types/case-study.ts

@@ -82,6 +82,22 @@ export interface CaseStudy {
   case_study_tags?: TagAssoc[];
 }
 
+/**
+ * What a case study card reads: the story, its cover and video, whose story it
+ * is and who tells it. A full `CaseStudy` row satisfies it; a surface that ships
+ * the card's data to the browser (the site menu) sends only this.
+ */
+export type CaseStudyCardData = Pick<CaseStudy, 'id' | 'title' | 'summary' | 'featured_image'> &
+  Partial<
+    Pick<
+      CaseStudy,
+      'main_video_url' | 'main_video_thumbnail' | 'highlight_video_url' | 'highlight_video_thumbnail' | 'video_bites'
+    >
+  > & {
+    user?: Pick<UserProfile, 'full_name' | 'job_title'> & Partial<Pick<UserProfile, 'avatar_url'>>;
+    msp?: Pick<MSP, 'name' | 'icon_url'>;
+  };
+
 export interface CreateCaseStudyData {
   title: string;
   slug: string;

package/src/types/navigation.ts

@@ -1,4 +1,5 @@
 import type React from 'react';
+import type { CaseStudyCardData } from './case-study';
 
 /**
  * Base navigation item interface used across all navigation components
@@ -13,80 +14,93 @@ export interface NavigationItem {
   children?: NavigationItem[];
   onClick?: () => void;
   element?: React.ReactNode; // For completely custom navigation items
-  isExternal?: boolean; // For external links that open in new tab
-  type?: 'single' | 'dropdown'; // Type of navigation item
-  dropdownContent?: React.ReactNode; // Additional content for dropdown (e.g., social icons)
-  showDropdownDivider?: boolean; // Whether to show divider above dropdown content
-  className?: string; // Custom CSS classes to override default styling
-  dropdownClassName?: string; // Custom CSS classes for dropdown menu background
 }
 
 /**
- * Configuration for the header component
+ * The site navigation model: ONE serializable description of a platform's
+ * header, mega menus, mobile menu and footer. Plain data only (no functions, no
+ * React elements), so a server resolver can build it and hand it to the client
+ * components (`SiteHeader`, `MobileNavSheet`, `SiteFooter`), which only render.
+ *
+ * A link is declared once and referenced from every surface, so one change to
+ * the model changes the header, the mobile menu and the footer together.
  */
-export interface HeaderConfig {
-  logo: {
-    element: React.ReactNode;
-    /** Where the logo links. Omitted, the logo is not a link (a landing page that keeps the visitor on it). */
-    href?: string;
-  };
-  navigation?: {
-    items: NavigationItem[];
-    position?: 'left' | 'center' | 'right';
-  };
-  actions?: {
-    left?: React.ReactNode[];
-    right?: React.ReactNode[];
-    persistent?: React.ReactNode[];
-  };
-  mobile?: {
-    enabled: boolean;
-    menuIcon?: React.ReactNode;
-    closeIcon?: React.ReactNode;
-    onToggle?: () => void;
-    isOpen?: boolean;
-  };
-  mingo?: {
-    enabled?: boolean;
-    source?: string;
-    className?: string;
-    /** Server-configured Mingo identity glyph (same EntityIcon the chat
-     *  panel renders); omit to use the packaged fallback mark. */
-    icon?: React.ReactNode;
-    /** Server-configured assistant name for the wordmark/aria-label; omit
-     *  for the default "Mingo AI". */
-    label?: string;
-  };
-  /** Support-ticket alerts cell (`TicketAlertsButton`), rendered before
-   *  the Mingo launcher in the flush cell row. Attention-only: renders
-   *  nothing unless a `<TicketLiveProvider>` is mounted AND there are
-   *  unread support replies — declaring it is side-effect-free. */
-  tickets?: {
-    /** BASE path of the tickets surface (any nesting prefix allowed —
-     *  '/tickets', '/support/portal/tickets'). The cell builds the SSOT
-     *  deep link `<href>?ticket=<id>` for the newest-unread ticket. */
-    href: string;
-    /** Optional host navigation (router push) — receives the FULL
-     *  computed href. Defaults to `window.location.assign`. */
-    onClick?: (href: string) => void;
-  };
-  className?: string;
-  style?: React.CSSProperties;
-  autoHide?: boolean;
-  backgroundColor?: string; // ODS background color (e.g., 'bg-ods-card', 'bg-ods-accent')
+export interface NavLink {
+  id: string;
+  /** The label shown in menus and the footer. */
+  label: string;
+  /** Internal path, internal path with `#anchor`, or absolute URL. */
+  href: string;
+  /** One line shown under the label in mega menus and the mobile sheet. */
+  description?: string;
+  /** An `EntityIcon` glyph name. */
+  iconName?: string;
+  /**
+   * A server-configured icon (an agent's avatar: a packaged mark by name, or an
+   * uploaded image), in `EntityIcon`'s own shape. Drawn round, and it wins over
+   * `iconName`.
+   */
+  icon?: { name?: string | null; url?: string | null; props?: Record<string, unknown> | null };
+  /** "Chocolatey · Homebrew · WinGet"; rendered as "Built on ...". */
+  builtOn?: string;
+  /** Filled by the resolver, for labels such as "All {count} customer stories". */
+  count?: number;
+  /** Names a live counter the host supplies at render (`badges` prop). */
+  badgeKey?: string;
+  /** Set by the resolver, never by a config: the link leaves this site. */
+  external?: boolean;
+}
+
+export interface NavGroup {
+  id: string;
+  title?: string;
+  links: NavLink[];
 }
 
 /**
- * Configuration for the mobile navigation panel
+ * A featured customer story shown as a card beside a menu's columns: the
+ * record itself, drawn by the shared case study card.
  */
-export interface MobileNavConfig {
-  sections: Array<{
-    title?: string;
-    items: NavigationItem[];
-  }>;
-  footer?: React.ReactNode;
-  className?: string;
-  onClose?: () => void;
+export interface NavFeature {
+  id: string;
+  href: string;
+  study: CaseStudyCardData;
+}
+
+export interface NavMenu {
+  id: string;
+  label: string;
+  /** A menu with only `href` is a plain link. */
+  href?: string;
+  iconName?: string;
+  /** Path prefixes that mark this menu as the current section. */
+  match?: string[];
+  /** One column is a list; more than one makes a mega menu. */
+  columns?: NavGroup[];
+  /** Featured cards shown beside the columns. */
+  features?: NavFeature[];
+  /** The side list of a mega menu. */
+  sideLinks?: NavLink[];
+  sideTitle?: string;
+  /** Show the brand's social links under the menu's links. */
+  showSocial?: boolean;
+}
+
+export type SiteNavPrimaryCta = 'trial' | 'waitlist' | 'none' | { label: string; href: string };
+
+export interface SiteNav {
+  menus: NavMenu[];
+  /**
+   * The mobile sheet's groups, when they differ from `menus` (a column promoted
+   * to its own group). Omitted: the sheet uses `menus`.
+   */
+  mobileMenus?: NavMenu[];
+  footerColumns: NavGroup[];
+  signIn?: NavLink;
+  primaryCta: SiteNavPrimaryCta;
+  closingBand?: { heading: string; subheading: string; secondary?: NavLink };
+  legal: { company: string; notes: string[]; links: NavLink[] };
+  brand: { name: string; tagline: string; social: NavLink[]; statusUrl?: string };
 }
 
 /**

package/src/utils/index.ts

@@ -116,6 +116,7 @@ export * from './shell-utils';
 export * from './video-bite-id';
 // OS type utilities
 export * from './os-utils';
+export * from './visitor-os';
 // Phone utilities
 export * from './country-phone-utils';
 export * from './compliance-standards';

package/src/utils/source-icons.ts

@@ -40,6 +40,19 @@ export const SOURCE_ICON_NAMES: Record<string, string> = {
   podcasts: 'headphones',
   'customer-interviews': 'users',
   faqs: 'info',
+  // Not a chat source: listed so the site menus and the admin sidebar draw the
+  // media library with one glyph, from this registry like every other kind.
+  media: 'image',
+
+  // Admin sections that are not chat sources, and the case-study audiences:
+  // listed so every glyph a menu, a sidebar or a dashboard tile shows is named
+  // here and nowhere else.
+  campaigns: 'megaphone-01',
+  'contact-submissions': 'email',
+  'code-documentation': 'book-open',
+  'audience-msp': 'hierarchy-02',
+  'audience-mssp': 'shield-lock',
+  'audience-it-team': 'buildings',
 
   // Trust (single-record live source over the public Vanta projection)
   'trust-center': 'shield',

package/src/utils/visitor-os.ts

@@ -0,0 +1,84 @@
+/**
+ * THE detection of the system a visitor is on. One rule, read by everything
+ * that depends on it: which installer the desktop app's download offers, and
+ * which shortcut key a hint shows. Never test `navigator.platform` or a
+ * User-Agent anywhere else.
+ *
+ * Pure and server-safe: the server passes the request's User-Agent, the browser
+ * goes through `useVisitorOs` (hooks), which also passes the touch-point count.
+ */
+export type VisitorOs = 'mac' | 'windows' | 'linux' | 'ios' | 'android';
+
+/** The systems the desktop app installs on. */
+export const DESKTOP_OSES = ['mac', 'windows', 'linux'] as const;
+export type DesktopOs = (typeof DESKTOP_OSES)[number];
+
+export interface VisitorOsHints {
+  /**
+   * The platform the browser STATES through User-Agent Client Hints:
+   * `navigator.userAgentData.platform` in the browser, the `Sec-CH-UA-Platform`
+   * request header on the server (Chromium browsers send it on every request).
+   * It is the current standard and is read first: browsers are freezing the
+   * User-Agent string, so the hint is the value they keep accurate. Safari and
+   * Firefox send none, which is why the User-Agent stays the fallback.
+   */
+  platform?: string | null;
+  /**
+   * `navigator.maxTouchPoints`, when the caller is a browser. An iPad asks for
+   * the desktop site by default and then calls itself a Macintosh; a Macintosh
+   * with a touch screen does not exist, so touch points tell the two apart. The
+   * server has no such signal and reads that iPad as a Mac.
+   */
+  maxTouchPoints?: number;
+}
+
+/** Client Hints platform names (the header quotes them) to ours. Chrome OS runs Linux apps. */
+const HINT_PLATFORMS: Record<string, VisitorOs> = {
+  macos: 'mac',
+  windows: 'windows',
+  linux: 'linux',
+  'chrome os': 'linux',
+  'chromium os': 'linux',
+  android: 'android',
+  ios: 'ios',
+};
+
+/**
+ * The visitor's system, or null when nothing names one. Order: the Client Hints
+ * platform, then the User-Agent, with touch points separating an iPad from a Mac.
+ */
+export function detectVisitorOs(userAgent: string | null | undefined, hints: VisitorOsHints = {}): VisitorOs | null {
+  const touchMac = (os: VisitorOs) => (os === 'mac' && (hints.maxTouchPoints ?? 0) > 1 ? 'ios' : os);
+  const hinted = HINT_PLATFORMS[(hints.platform ?? '').replace(/"/g, '').trim().toLowerCase()];
+  if (hinted) return touchMac(hinted);
+
+  const ua = userAgent ?? '';
+  if (!ua) return null;
+  // Phones and tablets first: Android's User-Agent also says "Linux".
+  if (/iPhone|iPad|iPod/i.test(ua)) return 'ios';
+  if (/Android/i.test(ua)) return 'android';
+  if (/Windows NT|Win64|Win32/i.test(ua)) return 'windows';
+  if (/Macintosh|Mac OS X/i.test(ua)) return touchMac('mac');
+  if (/Linux|X11|CrOS/i.test(ua)) return 'linux';
+  return null;
+}
+
+/** The system as a desktop one, or null for a phone, a tablet or an unknown system. */
+export function desktopOsOf(os: VisitorOs | null): DesktopOs | null {
+  return os !== null && (DESKTOP_OSES as readonly string[]).includes(os) ? (os as DesktopOs) : null;
+}
+
+/** The desktop system a User-Agent comes from: `desktopOsOf(detectVisitorOs(...))`. */
+export function detectDesktopOs(userAgent: string | null | undefined, hints?: VisitorOsHints): DesktopOs | null {
+  return desktopOsOf(detectVisitorOs(userAgent, hints));
+}
+
+/** Apple systems use the Command key for shortcuts; every other system uses Control. */
+export function usesCommandKey(os: VisitorOs | null): boolean {
+  return os === 'mac' || os === 'ios';
+}
+
+/** A shortcut as its hint reads on the visitor's system: `⌘K` or `Ctrl K`. */
+export function shortcutLabel(os: VisitorOs | null, key: string): string {
+  return usesCommandKey(os) ? `⌘${key}` : `Ctrl ${key}`;
+}