fix(docs): match agent and JRE downloads to system architecture

docs/app/[lang]/drivers/DriversClient.tsx

@@ -4,7 +4,7 @@ import { useEffect, useMemo, useRef, useState } from "react";
 import { useParams } from "next/navigation";
 import { LandingNav } from "@/components/landing/LandingNav";
 import { LandingSelect } from "@/components/landing/LandingSelect";
-import { downloadLinksFor, formatSize, platformLabels, type AgentDownloadCatalog, type AgentRegistry, type DownloadSource, type JreDisplayEntry, type NativeAgentDisplayEntry, type OfflineBundleEntry } from "@/lib/agentRegistry";
+import { downloadLinksFor, formatSize, platformLabels, selectNativeAgentPlatform, type AgentDownloadCatalog, type AgentRegistry, type DownloadSource, type JreDisplayEntry, type NativeAgentDisplayEntry, type OfflineBundleEntry } from "@/lib/agentRegistry";
 import { assembleCustomBundle, buildCustomBundleOptions, cnbMirrorUrl, computeBundlePlan, CUSTOM_BUNDLE_PLATFORMS, proxyUrl, resolveBundleJre, type BundleProgress } from "@/lib/agentBundle";
 import { Archive, Cpu, Database, Download, ListChecks, Plug, Search, Terminal, X } from "lucide-react";
 import { resolveLang, type DocsLang } from "@/lib/i18n";
@@ -223,6 +223,7 @@ export function DriversClient({ initialCatalog, initialRegistry }: { initialCata
   const [activeTab, setActiveTab] = useState<ActiveTab>("bundles");
   const [searchQuery, setSearchQuery] = useState("");
   const [selectedNativePlatforms, setSelectedNativePlatforms] = useState<Record<string, string>>({});
+  const nativePlatformTouchedRef = useRef(new Set<string>());
 
   const [bundlePlatform, setBundlePlatform] = useState("windows-x64");
   const [detectedPlatform, setDetectedPlatform] = useState<string | null>(null);
@@ -266,15 +267,15 @@ export function DriversClient({ initialCatalog, initialRegistry }: { initialCata
       const next = { ...current };
       let changed = false;
       for (const group of nativeGroups) {
-        if (group.options.length === 0) continue;
-        if (!next[group.key] || !group.options.some((option) => option.platformKey === next[group.key])) {
-          next[group.key] = group.options[0].platformKey;
+        const platform = selectNativeAgentPlatform(group.options, detectedPlatform, next[group.key], nativePlatformTouchedRef.current.has(group.key));
+        if (platform && platform !== next[group.key]) {
+          next[group.key] = platform;
           changed = true;
         }
       }
       return changed ? next : current;
     });
-  }, [nativeGroups]);
+  }, [nativeGroups, detectedPlatform]);
 
   const filteredNativeGroups = useMemo(
     () =>
@@ -824,7 +825,10 @@ export function DriversClient({ initialCatalog, initialRegistry }: { initialCata
                               <LandingSelect
                                 value={selectedAgent.platformKey}
                                 options={group.options.map((option) => ({ value: option.platformKey, label: option.platformLabel }))}
-                                onChange={(platformKey) => setSelectedNativePlatforms((current) => ({ ...current, [group.key]: platformKey }))}
+                                onChange={(platformKey) => {
+                                  nativePlatformTouchedRef.current.add(group.key);
+                                  setSelectedNativePlatforms((current) => ({ ...current, [group.key]: platformKey }));
+                                }}
                                 ariaLabel={`${group.label}: ${t.platform}`}
                                 className="min-w-[190px] max-[760px]:w-full"
                               />
@@ -864,6 +868,7 @@ export function DriversClient({ initialCatalog, initialRegistry }: { initialCata
                             <td className="min-w-0 px-5 py-3 font-medium text-landing-ink max-[760px]:px-0">
                               <div className="flex min-w-0 items-center gap-2">
                                 <span className="min-w-0 truncate">{j.platformLabel}</span>
+                                {j.platformKey === detectedPlatform && <span className="shrink-0 rounded-[5px] border border-landing-green/35 bg-landing-green/10 px-1.5 py-0.5 text-[11px] font-[650] text-landing-green">{t.currentPlatform}</span>}
                                 <span className="hidden shrink-0 rounded-[5px] border border-landing-green/35 bg-landing-green/10 px-1.5 py-0.5 font-mono text-[11px] text-landing-green max-[760px]:inline">JRE {j.jreKey}</span>
                               </div>
                             </td>

docs/lib/agentRegistry.test.ts

@@ -1,13 +1,40 @@
 import assert from "node:assert/strict";
 import { afterEach, test, vi } from "vitest";
 import driverVersions from "../../agents/versions.json";
-import { buildAgentDownloadCatalog, buildDriverEntries, buildNativeAgentEntries, downloadLinksFor, formatSize } from "./agentRegistry";
+import { buildAgentDownloadCatalog, buildDriverEntries, buildNativeAgentEntries, downloadLinksFor, formatSize, selectNativeAgentPlatform } from "./agentRegistry";
 import { fetchAgentDownloadCatalog } from "./agentRegistrySource";
 
 afterEach(() => {
   vi.restoreAllMocks();
 });
 
+const availablePlatforms = ["linux-aarch64", "linux-x64", "macos-aarch64", "macos-x64", "windows-aarch64", "windows-x64"].map((platformKey) => ({ platformKey }));
+
+for (const { platformKey } of availablePlatforms) {
+  test(`native Agent defaults to the detected ${platformKey} platform`, () => {
+    assert.equal(selectNativeAgentPlatform(availablePlatforms, platformKey), platformKey);
+  });
+}
+
+test("async ARM refinement updates the automatic default", () => {
+  const initial = selectNativeAgentPlatform(availablePlatforms, "macos-x64");
+  assert.equal(selectNativeAgentPlatform(availablePlatforms, "macos-aarch64", initial), "macos-aarch64");
+});
+
+test("async refinement preserves a platform selected manually for another machine", () => {
+  assert.equal(selectNativeAgentPlatform(availablePlatforms, "macos-aarch64", "windows-x64", true), "windows-x64");
+  assert.equal(selectNativeAgentPlatform(availablePlatforms, "macos-aarch64", "macos-x64", true), "macos-x64");
+});
+
+test("unsupported and unknown platforms fall back to an available artifact", () => {
+  const windowsOnly = [{ platformKey: "windows-x64" }];
+  assert.equal(selectNativeAgentPlatform(windowsOnly, "macos-aarch64"), "windows-x64");
+  assert.equal(selectNativeAgentPlatform(availablePlatforms, null), "linux-aarch64");
+  assert.equal(selectNativeAgentPlatform(availablePlatforms, "unknown"), "linux-aarch64");
+  assert.equal(selectNativeAgentPlatform(availablePlatforms, "windows-x64", "removed-platform", true), "windows-x64");
+  assert.equal(selectNativeAgentPlatform([], "macos-aarch64"), undefined);
+});
+
 test("offline download catalog includes the JDBC plugin ZIP", () => {
   const catalog = buildAgentDownloadCatalog([]);
 

docs/lib/agentRegistry.ts

@@ -74,6 +74,11 @@ export interface NativeAgentDisplayEntry {
   info: ArtifactInfo;
 }
 
+export function selectNativeAgentPlatform(options: ReadonlyArray<Pick<NativeAgentDisplayEntry, "platformKey">>, detectedPlatform: string | null, selectedPlatform?: string, manuallySelected = false): string | undefined {
+  if (manuallySelected && options.some((option) => option.platformKey === selectedPlatform)) return selectedPlatform;
+  return options.find((option) => option.platformKey === detectedPlatform)?.platformKey ?? options[0]?.platformKey;
+}
+
 export interface JdbcPluginDownloadEntry {
   label: string;
   filename: string;