@hraness/design-kit 0.31.1

package/src/plain-site.css

@@ -0,0 +1,397 @@
+@import "./site-shell.css";
+
+/**
+ * Plain site theme
+ *
+ * An opt-in document grammar for personal sites, open-source project pages,
+ * and quiet documentation. Color appearance remains owned by `data-theme`;
+ * this layer owns measure, typography, spacing, links, and minimal chrome.
+ */
+
+:root:has(> body.plain-site) {
+  background: #ffffff;
+  overflow-x: clip;
+  scrollbar-gutter: stable;
+}
+
+.plain-site {
+  --plain-link-target-min: 0px;
+  --plain-shell-measure: 34rem;
+  --plain-shell-gutter: 1.25rem;
+  --plain-background: #ffffff;
+  --plain-foreground: #171717;
+  --plain-link: #2457a6;
+  --plain-line: #d8d8d8;
+  --plain-muted: #666666;
+  --plain-surface: #f4f4f4;
+  --plain-syntax-keyword: #785f28;
+  --plain-syntax-string: #2d6a42;
+  --plain-syntax-number: #9f3631;
+  --plain-syntax-name: #0d61ac;
+
+  background: var(--plain-background);
+  color: var(--plain-foreground);
+  font-family: var(--font-text, var(--ui-font-sans, ui-sans-serif, system-ui, sans-serif));
+  font-size: 1rem;
+  line-height: var(--hraness-type-reading-leading, 1.7);
+  margin: 0;
+  overflow-x: clip;
+}
+
+:root[data-theme="dark"]:has(> body.plain-site) {
+  background: #151515;
+}
+
+:root[data-theme="dark"] .plain-site,
+.plain-site[data-theme="dark"] {
+  --plain-background: #151515;
+  --plain-foreground: #f2f2f2;
+  --plain-link: #8ab4ed;
+  --plain-line: #484848;
+  --plain-muted: #b6b6b6;
+  --plain-surface: #222222;
+  --plain-syntax-keyword: #c9ad74;
+  --plain-syntax-string: #76b38e;
+  --plain-syntax-number: #e18982;
+  --plain-syntax-name: #6aa9ed;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]):has(> body.plain-site) {
+    background: #151515;
+  }
+
+  :root:not([data-theme]) > .plain-site {
+    --plain-background: #151515;
+    --plain-foreground: #f2f2f2;
+    --plain-link: #8ab4ed;
+    --plain-line: #484848;
+    --plain-muted: #b6b6b6;
+    --plain-surface: #222222;
+    --plain-syntax-keyword: #c9ad74;
+    --plain-syntax-string: #76b38e;
+    --plain-syntax-number: #e18982;
+    --plain-syntax-name: #6aa9ed;
+  }
+}
+
+/* An explicit palette supplies the same semantic colors as application surfaces.
+ * Match the neutral dark and no-script root fallback specificity so this later
+ * bridge owns the aliases. Resolve them on each plain surface so nested palette
+ * boundaries retain their own colors, including forced-color system roles. */
+:root[data-palette]:has(> body.plain-site) {
+  background: var(--background, Canvas);
+}
+[data-palette][data-palette] .plain-site,
+.plain-site[data-palette][data-palette] {
+  --plain-background: var(--background, Canvas);
+  --plain-foreground: var(--foreground, CanvasText);
+  --plain-link: var(--primary, LinkText);
+  --plain-line: color-mix(in oklch, var(--foreground, CanvasText) 14%, var(--background, Canvas));
+  --plain-muted: var(--muted, CanvasText);
+  --plain-surface: var(--surface, Canvas);
+  --plain-syntax-keyword: var(--warning, CanvasText);
+  --plain-syntax-string: var(--success, CanvasText);
+  --plain-syntax-number: var(--danger, CanvasText);
+  --plain-syntax-name: var(--info, CanvasText);
+}
+
+.plain-site .syntax-code {
+  --syntax-comment: var(--plain-muted);
+  --syntax-keyword: var(--plain-syntax-keyword);
+  --syntax-string: var(--plain-syntax-string);
+  --syntax-number: var(--plain-syntax-number);
+  --syntax-name: var(--plain-syntax-name);
+  --syntax-sign: var(--plain-muted);
+}
+
+.plain-site *,
+.plain-site *::before,
+.plain-site *::after {
+  box-sizing: border-box;
+}
+
+:where(.plain-header a, .plain-page a, .plain-footer a) {
+  color: var(--plain-link);
+  overflow-wrap: anywhere;
+  text-decoration: none;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 0.15em;
+}
+
+:where(
+  .plain-header a:is(:hover, :focus-visible),
+  .plain-page a:is(:hover, :focus-visible),
+  .plain-footer a:is(:hover, :focus-visible)
+) {
+  text-decoration: underline;
+}
+
+.plain-site :where(
+  .plain-header a:focus-visible,
+  .plain-page a:focus-visible,
+  .plain-footer a:focus-visible
+) {
+  border-radius: 1px;
+  outline: 1px dotted currentColor;
+  outline-offset: 3px;
+}
+
+.plain-site :where(
+  .plain-header a:focus:not(:focus-visible),
+  .plain-page a:focus:not(:focus-visible),
+  .plain-footer a:focus:not(:focus-visible)
+) {
+  outline: none;
+}
+
+.plain-site ::selection {
+  background: color-mix(in srgb, var(--plain-link) 20%, transparent);
+  color: var(--plain-foreground);
+}
+
+.plain-page {
+  inline-size: 100%;
+  margin: clamp(3.5rem, 12vh, 7rem) auto;
+  max-width: var(--plain-shell-measure);
+  padding-inline: var(--plain-shell-gutter);
+}
+
+.plain-header {
+  border: 0;
+  inline-size: 100%;
+  padding: 0;
+}
+
+.plain-header__inner {
+  --plain-header-block-padding: 1.15rem;
+
+  align-items: center;
+  border-bottom: 1px solid var(--plain-line);
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.75rem 1.5rem;
+  inline-size: 100%;
+  justify-content: space-between;
+  margin-inline: auto;
+  max-width: var(--plain-shell-measure);
+  padding-top: max(
+    var(--plain-header-block-padding),
+    env(safe-area-inset-top)
+  );
+  padding-right: max(var(--plain-shell-gutter), env(safe-area-inset-right));
+  padding-bottom: var(--plain-header-block-padding);
+  padding-left: max(var(--plain-shell-gutter), env(safe-area-inset-left));
+}
+
+.plain-wordmark {
+  align-items: center;
+  color: var(--plain-foreground);
+  display: inline-flex;
+  flex: 1 1 auto;
+  font: inherit;
+  font-weight: 700;
+  letter-spacing: 0;
+  min-block-size: var(--plain-link-target-min);
+  min-inline-size: var(--plain-link-target-min);
+  overflow-wrap: anywhere;
+  text-decoration: none;
+  text-transform: none;
+}
+
+.plain-nav,
+.plain-footer__links {
+  align-items: center;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.35rem 0.85rem;
+}
+
+.plain-nav {
+  flex: 0 1 auto;
+  justify-content: flex-end;
+  margin-inline-start: auto;
+  max-inline-size: 100%;
+  min-inline-size: 0;
+}
+
+.plain-nav a,
+.plain-footer__links a {
+  align-items: center;
+  color: var(--plain-muted);
+  display: inline-flex;
+  font: inherit;
+  font-size: 0.9rem;
+  font-weight: 400;
+  letter-spacing: 0;
+  min-block-size: var(--plain-link-target-min);
+  min-inline-size: var(--plain-link-target-min);
+  padding: 0;
+  text-transform: none;
+}
+
+.plain-page :where(h1, h2, h3, p, ul, ol, pre, figure) {
+  font-size: inherit;
+}
+
+.plain-page :where(h1, h2, h3) {
+  font-family: var(--font-heading, var(--font-text, ui-sans-serif, system-ui, sans-serif));
+  line-height: var(--hraness-type-heading-leading, 1.2);
+  letter-spacing: -.02em;
+  text-wrap: balance;
+}
+
+.plain-page h1 {
+  font-size: clamp(1.75rem, 1.3rem + 1.8vw, 2.5rem);
+  font-weight: 700;
+  margin: 0 0 1rem;
+}
+
+.plain-page > p,
+.plain-muted {
+  color: var(--plain-muted);
+}
+
+.plain-page > p {
+  margin: 0;
+  text-wrap: pretty;
+}
+
+.plain-page section {
+  margin-top: 2rem;
+}
+
+.plain-page h2 {
+  font-size: 1.25rem;
+  font-weight: 700;
+  margin: 0 0 0.3rem;
+}
+
+.plain-page section > p {
+  margin: 0;
+}
+
+.plain-page section > p + p {
+  margin-top: 1rem;
+}
+
+.plain-links {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.plain-links li {
+  margin: 0.1rem 0;
+}
+
+.plain-links a {
+  display: inline-block;
+  min-height: 1.5rem;
+  min-width: 1.5rem;
+}
+
+.plain-code {
+  color: var(--plain-foreground);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: var(--hraness-type-code-size, .9rem);
+  line-height: 1.55;
+  margin: 0;
+  max-inline-size: 100%;
+  overflow-x: auto;
+  overflow-wrap: normal;
+  padding-block: 0.75rem;
+  tab-size: 2;
+  white-space: pre;
+}
+
+.plain-code code {
+  font: inherit;
+}
+
+.plain-footer {
+  --background: var(--plain-background);
+  --foreground: var(--plain-foreground);
+  --focus: var(--plain-link);
+  --line: var(--plain-line);
+  --muted: var(--plain-muted);
+  --secondary: var(--plain-surface);
+  --secondary-foreground: var(--plain-foreground);
+  --surface: var(--plain-background);
+  --surface-raised: var(--plain-surface);
+
+  align-items: center;
+  border-top: 1px solid var(--plain-line);
+  color: var(--plain-muted);
+  display: flex;
+  flex: 0 0 auto;
+  flex-wrap: wrap;
+  gap: 1rem;
+  inline-size: 100%;
+  justify-content: space-between;
+  margin: 0 auto;
+  max-width: var(--plain-shell-measure);
+  overflow: clip;
+  padding-top: 1.25rem;
+  padding-right: max(var(--plain-shell-gutter), env(safe-area-inset-right));
+  padding-bottom: max(1.25rem, env(safe-area-inset-bottom));
+  padding-left: max(var(--plain-shell-gutter), env(safe-area-inset-left));
+}
+
+.plain-site main:has(> .design-gallery[data-design-gallery-nested="true"]) {
+  padding-inline: max(var(--plain-shell-gutter), var(--space-6));
+}
+
+.plain-footer p {
+  margin: 0;
+}
+
+.plain-footer :where(a) {
+  align-items: center;
+  color: inherit;
+  display: inline-flex;
+  min-block-size: var(--plain-link-target-min);
+  min-inline-size: var(--plain-link-target-min);
+}
+
+@media (max-width: 42rem) {
+  .plain-header__inner {
+    --plain-header-block-padding: 0.65rem;
+
+    gap: 0.35rem 0.75rem;
+  }
+
+  .plain-wordmark {
+    flex-basis: min(11rem, 100%);
+  }
+}
+
+@media (pointer: coarse) {
+  .plain-site {
+    --plain-link-target-min: var(--interactive-target-min, 48px);
+  }
+}
+
+:root[data-verification-pointer="coarse"] .plain-site {
+  --plain-link-target-min: var(--interactive-target-min, 48px);
+}
+
+@media (max-width: 420px) {
+  .plain-site {
+    --plain-shell-gutter: 1rem;
+  }
+
+  .plain-page {
+    margin-block: 2.5rem;
+  }
+}
+
+@media (forced-colors: active) {
+  .plain-header__inner {
+    border-bottom: 1px solid CanvasText;
+  }
+
+  .plain-footer {
+    border-top: 1px solid CanvasText;
+  }
+}

package/src/platforms.ts

@@ -0,0 +1,151 @@
+/*
+ * Operating-system platforms for install commands and "Runs on" rows: known
+ * ids, their display names, monochrome marks, and client-side detection.
+ * Framework-neutral and side-effect free; React presentation lives in
+ * `react/platform-icons.tsx` and `react/platform-install.tsx`.
+ */
+
+/** Platforms with a registered mark and display name. */
+export const knownPlatformIds = ["macos", "linux", "windows"] as const;
+export type KnownPlatformId = (typeof knownPlatformIds)[number];
+
+/**
+ * A platform id. Known ids get a mark and a default label; any other
+ * lowercase slug (`"freebsd"`, `"docker"`) renders the neutral terminal mark.
+ */
+export type PlatformId = KnownPlatformId | (string & {});
+
+/** Ids detection can report. `ios`, `android`, and `chromeos` are never install targets by default. */
+export type DetectedPlatform = KnownPlatformId | "ios" | "android" | "chromeos";
+
+export interface PlatformMark {
+  /** The single `<path d>` drawn in a 24x24 box with `fill="currentColor"`. */
+  readonly path: string;
+  readonly viewBox: "0 0 24 24";
+}
+
+const platformIdPattern = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/u;
+
+/** True for a lowercase slug usable as a platform id and in element ids. */
+export function isPlatformId(value: unknown): value is PlatformId {
+  return typeof value === "string" && platformIdPattern.test(value);
+}
+
+export function isKnownPlatformId(value: unknown): value is KnownPlatformId {
+  return typeof value === "string" && (knownPlatformIds as readonly string[]).includes(value);
+}
+
+const platformLabels: Readonly<Record<KnownPlatformId, string>> = {
+  linux: "Linux",
+  macos: "macOS",
+  windows: "Windows",
+};
+
+/** The display name for a known platform; unknown ids return themselves. */
+export function platformLabel(id: PlatformId): string {
+  return isKnownPlatformId(id) ? platformLabels[id] : id;
+}
+
+// Apple and Linux (Tux) paths are Simple Icons 16.33.0, CC0-1.0, unmodified;
+// see vendor/platform-marks/UPSTREAM.md. The four-pane window and the
+// terminal fallback are original geometry for this package.
+const marks: Readonly<Record<KnownPlatformId | "terminal", PlatformMark>> = {
+  macos: {
+    viewBox: "0 0 24 24",
+    path: "M12.152 6.896c-.948 0-2.415-1.078-3.96-1.04-2.04.027-3.91 1.183-4.961 3.014-2.117 3.675-.546 9.103 1.519 12.09 1.013 1.454 2.208 3.09 3.792 3.039 1.52-.065 2.09-.987 3.935-.987 1.831 0 2.35.987 3.96.948 1.637-.026 2.676-1.48 3.676-2.948 1.156-1.688 1.636-3.325 1.662-3.415-.039-.013-3.182-1.221-3.22-4.857-.026-3.04 2.48-4.494 2.597-4.559-1.429-2.09-3.623-2.324-4.39-2.376-2-.156-3.675 1.09-4.61 1.09zM15.53 3.83c.843-1.012 1.4-2.427 1.245-3.83-1.207.052-2.662.805-3.532 1.818-.78.896-1.454 2.338-1.273 3.714 1.338.104 2.715-.688 3.559-1.701",
+  },
+  linux: {
+    viewBox: "0 0 24 24",
+    path: "M12.504 0c-.155 0-.315.008-.48.021-4.226.333-3.105 4.807-3.17 6.298-.076 1.092-.3 1.953-1.05 3.02-.885 1.051-2.127 2.75-2.716 4.521-.278.832-.41 1.684-.287 2.489a.424.424 0 00-.11.135c-.26.268-.45.6-.663.839-.199.199-.485.267-.797.4-.313.136-.658.269-.864.68-.09.189-.136.394-.132.602 0 .199.027.4.055.536.058.399.116.728.04.97-.249.68-.28 1.145-.106 1.484.174.334.535.47.94.601.81.2 1.91.135 2.774.6.926.466 1.866.67 2.616.47.526-.116.97-.464 1.208-.946.587-.003 1.23-.269 2.26-.334.699-.058 1.574.267 2.577.2.025.134.063.198.114.333l.003.003c.391.778 1.113 1.132 1.884 1.071.771-.06 1.592-.536 2.257-1.306.631-.765 1.683-1.084 2.378-1.503.348-.199.629-.469.649-.853.023-.4-.2-.811-.714-1.376v-.097l-.003-.003c-.17-.2-.25-.535-.338-.926-.085-.401-.182-.786-.492-1.046h-.003c-.059-.054-.123-.067-.188-.135a.357.357 0 00-.19-.064c.431-1.278.264-2.55-.173-3.694-.533-1.41-1.465-2.638-2.175-3.483-.796-1.005-1.576-1.957-1.56-3.368.026-2.152.236-6.133-3.544-6.139zm.529 3.405h.013c.213 0 .396.062.584.198.19.135.33.332.438.533.105.259.158.459.166.724 0-.02.006-.04.006-.06v.105a.086.086 0 01-.004-.021l-.004-.024a1.807 1.807 0 01-.15.706.953.953 0 01-.213.335.71.71 0 00-.088-.042c-.104-.045-.198-.064-.284-.133a1.312 1.312 0 00-.22-.066c.05-.06.146-.133.183-.198.053-.128.082-.264.088-.402v-.02a1.21 1.21 0 00-.061-.4c-.045-.134-.101-.2-.183-.333-.084-.066-.167-.132-.267-.132h-.016c-.093 0-.176.03-.262.132a.8.8 0 00-.205.334 1.18 1.18 0 00-.09.4v.019c.002.089.008.179.02.267-.193-.067-.438-.135-.607-.202a1.635 1.635 0 01-.018-.2v-.02a1.772 1.772 0 01.15-.768c.082-.22.232-.406.43-.533a.985.985 0 01.594-.2zm-2.962.059h.036c.142 0 .27.048.399.135.146.129.264.288.344.465.09.199.14.4.153.667v.004c.007.134.006.2-.002.266v.08c-.03.007-.056.018-.083.024-.152.055-.274.135-.393.2.012-.09.013-.18.003-.267v-.015c-.012-.133-.04-.2-.082-.333a.613.613 0 00-.166-.267.248.248 0 00-.183-.064h-.021c-.071.006-.13.04-.186.132a.552.552 0 00-.12.27.944.944 0 00-.023.33v.015c.012.135.037.2.08.334.046.134.098.2.166.268.01.009.02.018.034.024-.07.057-.117.07-.176.136a.304.304 0 01-.131.068 2.62 2.62 0 01-.275-.402 1.772 1.772 0 01-.155-.667 1.759 1.759 0 01.08-.668 1.43 1.43 0 01.283-.535c.128-.133.26-.2.418-.2zm1.37 1.706c.332 0 .733.065 1.216.399.293.2.523.269 1.052.468h.003c.255.136.405.266.478.399v-.131a.571.571 0 01.016.47c-.123.31-.516.643-1.063.842v.002c-.268.135-.501.333-.775.465-.276.135-.588.292-1.012.267a1.139 1.139 0 01-.448-.067 3.566 3.566 0 01-.322-.198c-.195-.135-.363-.332-.612-.465v-.005h-.005c-.4-.246-.616-.512-.686-.71-.07-.268-.005-.47.193-.6.224-.135.38-.271.483-.336.104-.074.143-.102.176-.131h.002v-.003c.169-.202.436-.47.839-.601.139-.036.294-.065.466-.065zm2.8 2.142c.358 1.417 1.196 3.475 1.735 4.473.286.534.855 1.659 1.102 3.024.156-.005.33.018.513.064.646-1.671-.546-3.467-1.089-3.966-.22-.2-.232-.335-.123-.335.59.534 1.365 1.572 1.646 2.757.13.535.16 1.104.021 1.67.067.028.135.06.205.067 1.032.534 1.413.938 1.23 1.537v-.043c-.06-.003-.12 0-.18 0h-.016c.151-.467-.182-.825-1.065-1.224-.915-.4-1.646-.336-1.77.465-.008.043-.013.066-.018.135-.068.023-.139.053-.209.064-.43.268-.662.669-.793 1.187-.13.533-.17 1.156-.205 1.869v.003c-.02.334-.17.838-.319 1.35-1.5 1.072-3.58 1.538-5.348.334a2.645 2.645 0 00-.402-.533 1.45 1.45 0 00-.275-.333c.182 0 .338-.03.465-.067a.615.615 0 00.314-.334c.108-.267 0-.697-.345-1.163-.345-.467-.931-.995-1.788-1.521-.63-.4-.986-.87-1.15-1.396-.165-.534-.143-1.085-.015-1.645.245-1.07.873-2.11 1.274-2.763.107-.065.037.135-.408.974-.396.751-1.14 2.497-.122 3.854a8.123 8.123 0 01.647-2.876c.564-1.278 1.743-3.504 1.836-5.268.048.036.217.135.289.202.218.133.38.333.59.465.21.201.477.335.876.335.039.003.075.006.11.006.412 0 .73-.134.997-.268.29-.134.52-.334.74-.4h.005c.467-.135.835-.402 1.044-.7zm2.185 8.958c.037.6.343 1.245.882 1.377.588.134 1.434-.333 1.791-.765l.211-.01c.315-.007.577.01.847.268l.003.003c.208.199.305.53.391.876.085.4.154.78.409 1.066.486.527.645.906.636 1.14l.003-.007v.018l-.003-.012c-.015.262-.185.396-.498.595-.63.401-1.746.712-2.457 1.57-.618.737-1.37 1.14-2.036 1.191-.664.053-1.237-.2-1.574-.898l-.005-.003c-.21-.4-.12-1.025.056-1.69.176-.668.428-1.344.463-1.897.037-.714.076-1.335.195-1.814.12-.465.308-.797.641-.984l.045-.022zm-10.814.049h.01c.053 0 .105.005.157.014.376.055.706.333 1.023.752l.91 1.664.003.003c.243.533.754 1.064 1.189 1.637.434.598.77 1.131.729 1.57v.006c-.057.744-.48 1.148-1.125 1.294-.645.135-1.52.002-2.395-.464-.968-.536-2.118-.469-2.857-.602-.369-.066-.61-.2-.723-.4-.11-.2-.113-.602.123-1.23v-.004l.002-.003c.117-.334.03-.752-.027-1.118-.055-.401-.083-.71.043-.94.16-.334.396-.4.69-.533.294-.135.64-.202.915-.47h.002v-.002c.256-.268.445-.601.668-.838.19-.201.38-.336.663-.336zm7.159-9.074c-.435.201-.945.535-1.488.535-.542 0-.97-.267-1.28-.466-.154-.134-.28-.268-.373-.335-.164-.134-.144-.333-.074-.333.109.016.129.134.199.2.096.066.215.2.36.333.292.2.68.467 1.167.467.485 0 1.053-.267 1.398-.466.195-.135.445-.334.648-.467.156-.136.149-.267.279-.267.128.016.034.134-.147.332a8.097 8.097 0 01-.69.468zm-1.082-1.583V5.64c-.006-.02.013-.042.029-.05.074-.043.18-.027.26.004.063 0 .16.067.15.135-.006.049-.085.066-.135.066-.055 0-.092-.043-.141-.068-.052-.018-.146-.008-.163-.065zm-.551 0c-.02.058-.113.049-.166.066-.047.025-.086.068-.14.068-.05 0-.13-.02-.136-.068-.01-.066.088-.133.15-.133.08-.031.184-.047.259-.005.019.009.036.03.03.05v.02h.003z",
+  },
+  windows: {
+    viewBox: "0 0 24 24",
+    path: "M1.5 1.5h10v10h-10zM12.5 1.5h10v10h-10zM1.5 12.5h10v10h-10zM12.5 12.5h10v10h-10z",
+  },
+  terminal: {
+    viewBox: "0 0 24 24",
+    path: "M4 3h16a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2zm0 2v14h16V5zm2.3 3.3 1.4-1.4 4.1 4.1-4.1 4.1-1.4-1.4 2.7-2.7zM12 15h6v2h-6z",
+  },
+};
+
+/** The mark for a platform; ids without a registered mark get the neutral terminal glyph. */
+export function platformMark(id: PlatformId): PlatformMark {
+  return isKnownPlatformId(id) ? marks[id] : marks.terminal;
+}
+
+/**
+ * Reads the visitor's operating system from a `navigator`-shaped value.
+ * Prefers User-Agent Client Hints (`userAgentData.platform`), then the
+ * user-agent string, then the legacy `platform` field. Returns `null` when
+ * nothing is recognized. Never throws, whatever the input.
+ */
+export function detectPlatform(navigatorLike: unknown): DetectedPlatform | null {
+  if (typeof navigatorLike !== "object" || navigatorLike === null) return null;
+  const record = navigatorLike as Record<string, unknown>;
+  let hinted: string | undefined;
+  try {
+    const data = record.userAgentData;
+    if (typeof data === "object" && data !== null) {
+      const platform = (data as Record<string, unknown>).platform;
+      if (typeof platform === "string") hinted = platform;
+    }
+  } catch {
+    hinted = undefined;
+  }
+  const fromHint = hinted === undefined ? null : classifyHint(hinted);
+  if (fromHint !== null) return fromHint;
+  const userAgent = stringField(record, "userAgent");
+  const fromAgent = userAgent === undefined ? null : classifyUserAgent(userAgent);
+  if (fromAgent !== null) return fromAgent;
+  const legacy = stringField(record, "platform");
+  return legacy === undefined ? null : classifyUserAgent(legacy);
+}
+
+function stringField(record: Record<string, unknown>, key: string): string | undefined {
+  try {
+    const value = record[key];
+    return typeof value === "string" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function classifyHint(platform: string): DetectedPlatform | null {
+  switch (platform.trim().toLowerCase()) {
+    case "macos": return "macos";
+    case "windows": return "windows";
+    case "linux": return "linux";
+    case "chrome os":
+    case "chromeos": return "chromeos";
+    case "android": return "android";
+    case "ios": return "ios";
+    default: return null;
+  }
+}
+
+function classifyUserAgent(userAgent: string): DetectedPlatform | null {
+  // Order matters: Android agents also say Linux, iPadOS and iOS agents say
+  // "like Mac OS X", and ChromeOS agents say X11.
+  if (/Windows|Win(?:32|64)\b/u.test(userAgent)) return "windows";
+  if (/iPhone|iPad|iPod/u.test(userAgent)) return "ios";
+  if (/Android/u.test(userAgent)) return "android";
+  if (/CrOS/u.test(userAgent)) return "chromeos";
+  if (/Mac OS X|Macintosh|MacIntel|\bMac\b/u.test(userAgent)) return "macos";
+  if (/Linux|X11/u.test(userAgent)) return "linux";
+  return null;
+}
+
+/**
+ * Chooses which of `available` to show for a detected platform: the exact
+ * id, ChromeOS falls back to `linux`, and anything else (including no
+ * detection) returns `null` so callers keep their default.
+ */
+export function matchDetectedPlatform(
+  detected: DetectedPlatform | null,
+  available: readonly PlatformId[],
+): PlatformId | null {
+  if (detected === null) return null;
+  if (available.includes(detected)) return detected;
+  if (detected === "chromeos" && available.includes("linux")) return "linux";
+  return null;
+}