Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Avoid architecture guesses in download CTAs (#3459)

mike-inkeep61190b0d3b4f
diff --git a/.changeset/architecture-safe-download-ctas.md b/.changeset/architecture-safe-download-ctas.md
new file mode 100644
index 000000000..03ffd3806
--- /dev/null
+++ b/.changeset/architecture-safe-download-ctas.md
@@ -0,0 +1,5 @@
+---
+'@inkeep/open-knowledge': patch
+---
+
+Windows and Linux download buttons on the marketing and docs sites now open the download picker instead of assuming an architecture. The picker page's primary button explicitly labels the architecture its convenient default build assumes.
diff --git a/docs/src/app/d/[encoded]/download/route.test.ts b/docs/src/app/d/[encoded]/download/route.test.ts
index 7ea3d3c41..0ebdb379b 100644
--- a/docs/src/app/d/[encoded]/download/route.test.ts
+++ b/docs/src/app/d/[encoded]/download/route.test.ts
@@ -39,38 +39,31 @@ function call(encoded: string, query = ''): Promise<Response> {
}
describe('GET /d/[encoded]/download', () => {
- test('valid share: 302 to the DMG, sets the pairing cookie, counts share-splash', async () => {
+ test('picker request carries a valid share to the architecture picker', async () => {
_viewKind = 'ok';
_lastCapture = null;
- const res = await call('valid-share');
+ const res = await call('valid-share', '?picker=1');
expect(res.status).toBe(302);
- expect(res.headers.get('location')).toBe(SPLASH_URL);
+ expect(res.headers.get('location')).toBe(
+ 'https://openknowledge.ai/download?utm_content=share-splash',
+ );
expect(res.headers.get('set-cookie')).toContain('ok-pending-share=valid-share');
- expect(_lastCapture?.event).toBe('dmg_downloaded');
- expect(_lastCapture?.properties?.channel).toBe('stable');
- // Server-authoritative: overrides the attribution() value.
- expect(_lastCapture?.properties?.utm_content).toBe('share-splash');
- expect(_lastCapture?.distinctId).toBe('splash-1');
- });
-
- test('invalid share: 302 with NO cookie but still counts the download', async () => {
- _viewKind = 'invalid';
- _lastCapture = null;
- const res = await call('bad-share');
- expect(res.status).toBe(302);
- expect(res.headers.get('location')).toBe(SPLASH_URL);
- expect(res.headers.get('set-cookie')).toBeNull();
- expect(_lastCapture?.event).toBe('dmg_downloaded');
- expect(_lastCapture?.properties?.utm_content).toBe('share-splash');
+ // Reaching the picker is not a download event.
+ expect(_lastCapture).toBeNull();
});
- test('unsupported-version share: no cookie, still counts', async () => {
- _viewKind = 'unsupported-version';
- _lastCapture = null;
- const res = await call('old-share');
- expect(res.status).toBe(302);
- expect(res.headers.get('set-cookie')).toBeNull();
- expect(_lastCapture?.event).toBe('dmg_downloaded');
+ test('invalid or unsupported picker request reaches the picker without a cookie', async () => {
+ for (const kind of ['invalid', 'unsupported-version'] as const) {
+ _viewKind = kind;
+ _lastCapture = null;
+ const res = await call(`${kind}-share`, '?picker=1');
+ expect(res.status).toBe(302);
+ expect(res.headers.get('location')).toBe(
+ 'https://openknowledge.ai/download?utm_content=share-splash',
+ );
+ expect(res.headers.get('set-cookie')).toBeNull();
+ expect(_lastCapture).toBeNull();
+ }
});
test('the full triple picks that exact build, cookie + count intact', async () => {
@@ -104,7 +97,7 @@ describe('GET /d/[encoded]/download', () => {
expect(_lastCapture?.properties).toMatchObject({ os: 'linux', arch: 'x64', format: 'deb' });
});
- test('an unrecognized ?os= falls back to the DMG', async () => {
+ test('an unrecognized ?os= retains the legacy macOS floor', async () => {
_viewKind = 'ok';
_lastCapture = null;
const res = await call('valid-share', '?os=beos');
@@ -126,12 +119,12 @@ describe('GET /d/[encoded]/download', () => {
}
});
- test('a prefetch still redirects (with cookie) but is NOT counted', async () => {
+ test('a concrete-build prefetch still redirects (with cookie) but is NOT counted', async () => {
_viewKind = 'ok';
_lastCapture = null;
_isPrefetch = true;
try {
- const res = await call('valid-share');
+ const res = await call('valid-share', '?os=macos&arch=arm64&format=dmg');
expect(res.status).toBe(302);
expect(res.headers.get('location')).toBe(SPLASH_URL);
expect(_lastCapture).toBeNull();
diff --git a/docs/src/app/d/[encoded]/download/route.ts b/docs/src/app/d/[encoded]/download/route.ts
index ada989df0..eda0d0e11 100644
--- a/docs/src/app/d/[encoded]/download/route.ts
+++ b/docs/src/app/d/[encoded]/download/route.ts
@@ -1,6 +1,6 @@
import { NextResponse } from 'next/server';
import { buildPendingShareCookie } from '@/lib/deferred-share';
-import { resolveTargetFromParams, targetById } from '@/lib/download-targets';
+import { DOWNLOAD_PAGE_HREF, resolveTargetFromParams, targetById } from '@/lib/download-targets';
import { buildSplashViewModel } from '@/lib/share-splash';
import { attribution, captureServerEvent, isPrefetchRequest, resolveDistinctId } from '@/lib/track';
@@ -8,11 +8,12 @@ import { attribution, captureServerEvent, isPrefetchRequest, resolveDistinctId }
* `GET /d/<encoded>/download` — the splash Download CTA target.
*
* Sets the pairing cookie carrying `<encoded>` (so the app's first launch can
- * redeem it) and 302s to the release asset named by `?os=&arch=&format=`,
- * defaulting to the macOS DMG. The assets are untouched — the carry lives
+ * redeem it) and 302s to the release asset named by `?os=&arch=&format=`.
+ * A query-less detected Windows/Linux click sets the cookie and continues to
+ * the architecture picker instead. The assets are untouched — the carry lives
* entirely in the receiver's browser, so it works the same on every platform.
- * That is why the splash's platform picker points every row back here rather
- * than at `/download/stable` or GitHub: any other target drops the share.
+ * That is why every concrete platform row points back here rather than at
+ * `/download/stable` or GitHub: any other target drops the share.
*
* The download must NEVER be blocked by the carry: an `<encoded>` that doesn't
* decode to a valid share still redirects to the asset, just without a cookie.
@@ -22,11 +23,23 @@ export async function GET(
{ params }: { params: Promise<{ encoded: string }> },
): Promise<NextResponse> {
const { encoded } = await params;
- const target =
- resolveTargetFromParams(new URL(request.url).searchParams) ?? targetById('macos-arm64');
- const response = NextResponse.redirect(target.assetUrl, 302);
-
+ const searchParams = new URL(request.url).searchParams;
+ const target = resolveTargetFromParams(searchParams);
const view = buildSplashViewModel(encoded);
+
+ // A detected Windows/Linux primary click reaches here with `picker=1` but no
+ // build triple. Preserve the pending share before sending the recipient to
+ // the architecture picker; explicit caret rows still name a concrete target.
+ if (searchParams.get('picker') === '1') {
+ const response = NextResponse.redirect(`${DOWNLOAD_PAGE_HREF}?utm_content=share-splash`, 302);
+ if (view.kind === 'ok') response.cookies.set(buildPendingShareCookie(encoded));
+ return response;
+ }
+
+ // Legacy/no-JS links omit the triple and retain the historical macOS floor.
+ const selectedTarget = target ?? targetById('macos-arm64');
+ const response = NextResponse.redirect(selectedTarget.assetUrl, 302);
+
if (view.kind === 'ok') {
response.cookies.set(buildPendingShareCookie(encoded));
}
@@ -40,9 +53,9 @@ export async function GET(
distinctId: resolveDistinctId(request),
properties: {
channel: 'stable',
- os: target.os,
- arch: target.arch,
- format: target.format,
+ os: selectedTarget.os,
+ arch: selectedTarget.arch,
+ format: selectedTarget.format,
...attribution(request),
utm_content: 'share-splash',
},
diff --git a/docs/src/app/d/[encoded]/splash-cta-cluster.tsx b/docs/src/app/d/[encoded]/splash-cta-cluster.tsx
index c7782b55c..847f8fef8 100644
--- a/docs/src/app/d/[encoded]/splash-cta-cluster.tsx
+++ b/docs/src/app/d/[encoded]/splash-cta-cluster.tsx
@@ -7,7 +7,7 @@ import { SplashButtonLabel, splashPrimaryButton } from './splash-buttons';
import { SplashDownloadSplitButton } from './splash-download-split-button';
interface SplashCtaClusterProps {
- /** Already carries the detected platform's `?os=&arch=&format=`. */
+ /** Direct build URL, or the query-less share route for Windows/Linux. */
downloadUrl: string;
/** Same route without a query, so the panel can mint one link per build. */
platformBaseUrl: string;
@@ -125,7 +125,7 @@ export function SplashCtaCluster({
<SplashButtonLabel>{attempting ? 'Opening…' : 'Open in desktop app'}</SplashButtonLabel>
</a>
- {/* Download + the secondary open-paths (the other builds, copyable CLI
+ {/* Download + the secondary open-paths (the explicit builds, copyable CLI
commands, GitHub) condensed into one segmented control.
fallbackCtaRef lands focus on the download segment when the
deep-link handoff times out. */}
diff --git a/docs/src/app/d/[encoded]/splash-cta-panel.test.ts b/docs/src/app/d/[encoded]/splash-cta-panel.test.ts
new file mode 100644
index 000000000..a3e26d172
--- /dev/null
+++ b/docs/src/app/d/[encoded]/splash-cta-panel.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, test, vi } from 'vitest';
+
+vi.mock('react', () => ({
+ useEffect: () => {},
+ useState: () => ['unknown', () => {}],
+ createElement: () => null,
+}));
+vi.mock('./splash-cta-cluster', () => ({ SplashCtaCluster: () => null }));
+
+import { splashPrimaryDownloadUrl } from './splash-cta-panel';
+
+const SHARE_ROUTE = '/d/encoded-share/download';
+
+describe('splashPrimaryDownloadUrl', () => {
+ test('requests the picker through the share route without choosing an architecture', () => {
+ expect(splashPrimaryDownloadUrl(SHARE_ROUTE, 'windows')).toBe(`${SHARE_ROUTE}?picker=1`);
+ expect(splashPrimaryDownloadUrl(SHARE_ROUTE, 'linux')).toBe(`${SHARE_ROUTE}?picker=1`);
+ });
+
+ test('keeps the sole macOS build and SSR floor on the share-carrying route', () => {
+ const mac = `${SHARE_ROUTE}?os=macos&arch=arm64&format=dmg`;
+ expect(splashPrimaryDownloadUrl(SHARE_ROUTE, 'macos')).toBe(mac);
+ expect(splashPrimaryDownloadUrl(SHARE_ROUTE, 'unknown')).toBe(mac);
+ });
+});
diff --git a/docs/src/app/d/[encoded]/splash-cta-panel.tsx b/docs/src/app/d/[encoded]/splash-cta-panel.tsx
index b6cd975af..a63674fd0 100644
--- a/docs/src/app/d/[encoded]/splash-cta-panel.tsx
+++ b/docs/src/app/d/[encoded]/splash-cta-panel.tsx
@@ -16,10 +16,11 @@ interface SplashCtaPanelProps {
/**
* Progressive-enhancement wrapper around the CTA cluster. The desktop app
* ships on macOS, Windows, and Linux, so every OS renders the same cluster
- * (deep link + segmented Download button whose panel carries the other builds,
- * the CLI commands, and GitHub). The SSR floor is the bare download route (the
- * mac DMG — the historical default); after hydration we classify the OS and
- * retarget the Download segment.
+ * (deep link + segmented Download button whose panel carries the explicit
+ * builds, the CLI commands, and GitHub). The SSR floor is the bare download
+ * route (the mac DMG — the historical default); after hydration we classify
+ * the OS and keep Windows/Linux on the share-carrying route without guessing
+ * until the recipient explicitly chooses a build from the adjacent caret.
*
* No-JS / pre-hydration: stays on the SSR floor; the server-rendered Download
* <a> and GitHub links work without JS (only the panel is JS-gated).
@@ -39,7 +40,7 @@ export function SplashCtaPanel({
return (
<SplashCtaCluster
- downloadUrl={`${downloadUrl}${splashDownloadQuery(os)}`}
+ downloadUrl={splashPrimaryDownloadUrl(downloadUrl, os)}
platformBaseUrl={downloadUrl}
detectedOs={os}
customSchemeUrl={customSchemeUrl}
@@ -49,3 +50,14 @@ export function SplashCtaPanel({
/>
);
}
+
+/**
+ * Windows/Linux request the picker through the share-carrying route, preserving
+ * its pending-share cookie without choosing an architecture. Unknown keeps the
+ * working no-JS macOS floor.
+ */
+export function splashPrimaryDownloadUrl(downloadUrl: string, os: DetectedOs): string {
+ return os === 'windows' || os === 'linux'
+ ? `${downloadUrl}?picker=1`
+ : `${downloadUrl}${splashDownloadQuery(os)}`;
+}
diff --git a/docs/src/app/d/[encoded]/splash-fallback-cta.tsx b/docs/src/app/d/[encoded]/splash-fallback-cta.tsx
index 45cd5bdeb..c52ade8a4 100644
--- a/docs/src/app/d/[encoded]/splash-fallback-cta.tsx
+++ b/docs/src/app/d/[encoded]/splash-fallback-cta.tsx
@@ -4,9 +4,8 @@ import { useEffect, useState } from 'react';
import {
classifyDownloadOs,
type DetectedOs,
- defaultTargetForOs,
+ downloadHrefForDetectedOs,
readPlatformInput,
- targetQuery,
} from '@/lib/download-targets';
import { SPLASH_INSTALL_COMMAND } from '@/lib/share-splash';
import { downloadRouteForCta } from '@/lib/site';
@@ -26,14 +25,15 @@ const FALLBACK_DOWNLOAD_URL = downloadRouteForCta('share-splash-fallback');
*
* It is the split button rather than a plain link because these visitors are
* no better at naming their own architecture than anyone else — the primary
- * segment follows the detected OS and the caret carries every other build plus
- * the npm path. There is no separate "Open with CLI" button beside it: that
- * button's panel could only offer a bare install with no share to open, and
+ * segment sends Windows/Linux to the picker and the caret carries every
+ * explicit build plus the npm path. There is no separate "Open with CLI"
+ * button beside it: that button's panel could only offer a bare install with
+ * no share to open, and
* the npm route already sits one click away in this caret.
*
* Mirrors SplashCtaPanel's progressive enhancement — SSR renders the macOS
- * floor and hydration retargets to the detected OS, so the link works with
- * scripting off.
+ * floor and hydration sends architecture-ambiguous platforms to the picker,
+ * so the link works with scripting off without guessing for Windows/Linux.
*/
export function SplashFallbackCta() {
const [os, setOs] = useState<DetectedOs>('unknown');
@@ -44,7 +44,7 @@ export function SplashFallbackCta() {
return (
<SplashDownloadSplitButton
- downloadUrl={`${FALLBACK_DOWNLOAD_URL}&${targetQuery(defaultTargetForOs(os))}`}
+ downloadUrl={downloadHrefForDetectedOs('share-splash-fallback', os)}
platformBaseUrl={FALLBACK_DOWNLOAD_URL}
detectedOs={os}
installCommand={SPLASH_INSTALL_COMMAND}
diff --git a/docs/src/components/docs-sidebar-cta.tsx b/docs/src/components/docs-sidebar-cta.tsx
index 4e115fd80..92f575194 100644
--- a/docs/src/components/docs-sidebar-cta.tsx
+++ b/docs/src/components/docs-sidebar-cta.tsx
@@ -18,10 +18,9 @@ const fullStars = new Intl.NumberFormat('en-US');
export function DocsSidebarCta({ stars }: { stars: number | null }) {
return (
<div className="flex gap-2">
- {/* Docs readers span platforms, so the primary segment follows the
- visitor's OS and the caret carries the rest. Unlike the old plain link
- to /download, this routes through the tracked redirect, so sidebar
- downloads are attributed rather than invisible. */}
+ {/* Docs readers span platforms, so OS detection names the platform but
+ never guesses a Windows/Linux architecture: the primary segment sends
+ those visitors to /download, while the caret carries explicit builds. */}
{/* The download flexes and the star keeps its natural size: the star's
width is driven by a live count we don't control, so it gets the space
it needs and the download absorbs whatever is left. */}
diff --git a/docs/src/components/download-split-button.tsx b/docs/src/components/download-split-button.tsx
index 35be7c884..3752c7d19 100644
--- a/docs/src/components/download-split-button.tsx
+++ b/docs/src/components/download-split-button.tsx
@@ -12,7 +12,7 @@ import {
import {
classifyDownloadOs,
type DetectedOs,
- defaultTargetForOs,
+ downloadHrefForDetectedOs,
downloadHrefForTarget,
downloadLabelForOs,
orderTargetsForOs,
@@ -32,9 +32,10 @@ interface DownloadSplitButtonProps {
}
/**
- * Download CTA that guesses right and never traps: the primary segment fires
- * the detected OS's default build, the caret opens every other published
- * build plus the browser/npm path.
+ * Download CTA that never guesses an architecture: the primary segment sends
+ * detected Windows and Linux visitors to the download picker, while macOS can
+ * use its sole published build directly. The caret keeps every explicit build
+ * plus the browser/npm path one click away.
*
* Server renders the neutral "Download" label pointing at the macOS floor, and
* hydration swaps in the detected OS. Labelling by OS only after detection
@@ -42,13 +43,13 @@ interface DownloadSplitButtonProps {
* macOS" flash on a Windows machine — and the pre-hydration href still works
* with JS off.
*
- * Every download link stays in the current tab. The redirect route ends at a
- * GitHub asset served `Content-Disposition: attachment`, so the browser starts
- * the download and abandons the navigation, leaving the page untouched.
- * Opening a tab instead would flash a blank window that then closes itself.
+ * Every destination stays in the current tab. A concrete build's redirect ends
+ * at a GitHub asset served `Content-Disposition: attachment`, so the browser
+ * starts the download and leaves the page untouched; Windows/Linux navigate to
+ * the picker normally.
*
- * Both segments are raw `<a>`/`<button>`, never `next/link`: the download
- * route is a 302 handler, so prefetching it would fire the redirect and
+ * Both segments are raw `<a>`/`<button>`, never `next/link`: the SSR href is a
+ * 302 handler, so prefetching it before OS detection would start a download and
* double-count.
*/
export function DownloadSplitButton({
@@ -62,7 +63,6 @@ export function DownloadSplitButton({
setOs(classifyDownloadOs(readPlatformInput()));
}, []);
- const primary = defaultTargetForOs(os);
const chrome = variant === 'compact' ? COMPACT : PILL;
const osLabel = downloadLabelForOs(os);
@@ -75,7 +75,7 @@ export function DownloadSplitButton({
className={cn('not-prose inline-flex items-stretch', chrome.group, className)}
>
<a
- href={downloadHrefForTarget(cta, primary)}
+ href={downloadHrefForDetectedOs(cta, os)}
// `noreferrer` is deliberately omitted: the Referer names the page the
// download came from, which is how the event attributes to a docs page
// rather than counting as direct traffic.
diff --git a/docs/src/components/download-text-link.tsx b/docs/src/components/download-text-link.tsx
index b4ddea819..51a2c9ecc 100644
--- a/docs/src/components/download-text-link.tsx
+++ b/docs/src/components/download-text-link.tsx
@@ -4,8 +4,8 @@ import { useEffect, useState } from 'react';
import {
classifyDownloadOs,
type DetectedOs,
- defaultTargetForOs,
- downloadHrefForTarget,
+ downloadHrefForDetectedOs,
+ downloadPageHrefForCta,
readPlatformInput,
} from '@/lib/download-targets';
import type { DownloadCta } from '@/lib/site';
@@ -25,7 +25,8 @@ interface DownloadTextLinkProps {
/**
* Prose-flow counterpart to the split button, for the places a download sits
* inside a sentence rather than standing on its own. Same detection and same
- * tracked redirect; no dropdown, because a menu can't hang off a run of text.
+ * architecture-safe destination; no dropdown, because a menu can't hang off a
+ * run of text.
*
* Reads "Download it" until the OS is known and "Download it for Windows"
* after, so the sentence is never wrong for the reader looking at it.
@@ -38,24 +39,26 @@ export function DownloadTextLink({ cta, className }: DownloadTextLinkProps) {
}, []);
const suffix = OS_NOUN[os];
+ const href = downloadHrefForDetectedOs(cta, os);
+ const pickerHref = downloadPageHrefForCta(cta);
return (
<>
- {/* Raw <a>, never next/link: the target is a 302 handler and prefetching
- it would fire the redirect. */}
- <a href={downloadHrefForTarget(cta, defaultTargetForOs(os))} className={className}>
+ {/* Raw <a>, never next/link: the SSR target is a 302 handler, and
+ prefetching it before OS detection would start a download. */}
+ <a href={href} className={className}>
Download it{suffix ? ` ${suffix}` : ''}
</a>
- {/* A detected OS is still a guess, and this sentence has no dropdown to
- fall back on — without a way out, anyone we guessed wrong for is
- stuck. */}
- <span className="text-slide-muted"> · </span>
- <a href={ALL_PLATFORMS_HREF} className={className}>
- More platforms
- </a>
+ {/* macOS and the neutral SSR floor still point to a concrete build, so
+ keep the picker escape hatch. Windows/Linux already land there. */}
+ {href === pickerHref ? null : (
+ <>
+ <span className="text-slide-muted"> · </span>
+ <a href={pickerHref} className={className}>
+ More platforms
+ </a>
+ </>
+ )}
</>
);
}
-
-/** The picker page, which lists every build plus the npm/web-app path. */
-const ALL_PLATFORMS_HREF = '/download';
diff --git a/docs/src/lib/download-targets.test.ts b/docs/src/lib/download-targets.test.ts
index d1f12bd2b..01c739ff7 100644
--- a/docs/src/lib/download-targets.test.ts
+++ b/docs/src/lib/download-targets.test.ts
@@ -2,8 +2,10 @@ import { describe, expect, test } from 'vitest';
import {
classifyDownloadOs,
type DetectedOs,
+ DOWNLOAD_PAGE_HREF,
DOWNLOAD_TARGETS,
defaultTargetForOs,
+ downloadHrefForDetectedOs,
downloadHrefForTarget,
downloadLabelForOs,
orderTargetsForOs,
@@ -87,6 +89,24 @@ describe('downloadLabelForOs', () => {
});
});
+describe('downloadHrefForDetectedOs', () => {
+ test('sends Windows and Linux to the production picker without losing attribution', () => {
+ const expected = `${DOWNLOAD_PAGE_HREF}?utm_content=docs-sidebar`;
+ expect(downloadHrefForDetectedOs('docs-sidebar', 'windows')).toBe(expected);
+ expect(downloadHrefForDetectedOs('docs-sidebar', 'linux')).toBe(expected);
+ expect(DOWNLOAD_PAGE_HREF).toBe('https://openknowledge.ai/download');
+ });
+
+ test('keeps the sole macOS build and the working SSR floor direct', () => {
+ expect(downloadHrefForDetectedOs('docs-sidebar', 'macos')).toBe(
+ '/download/stable?utm_content=docs-sidebar&os=macos&arch=arm64&format=dmg',
+ );
+ expect(downloadHrefForDetectedOs('docs-sidebar', 'unknown')).toBe(
+ '/download/stable?utm_content=docs-sidebar&os=macos&arch=arm64&format=dmg',
+ );
+ });
+});
+
describe('downloadHrefForTarget', () => {
test('routes through the tracked redirect carrying both the CTA and the build', () => {
const href = downloadHrefForTarget('docs-sidebar', defaultTargetForOs('linux'));
diff --git a/docs/src/lib/download-targets.ts b/docs/src/lib/download-targets.ts
index 19d052dfd..04d80aab0 100644
--- a/docs/src/lib/download-targets.ts
+++ b/docs/src/lib/download-targets.ts
@@ -4,17 +4,15 @@
*
* Two rules shape everything here:
*
- * 1. **Platform is detectable; architecture is not.** `navigator` reliably
- * names the OS and nothing else. Apple freezes the macOS UA to "Intel Mac
- * OS X" on Apple Silicon too, UA Client Hints are Chromium-only and
- * misreport under Rosetta, and Windows/Linux expose no trustworthy arch
- * signal at all. So detection picks the OS, a hardcoded guess picks the
- * arch for the primary click, and every other build stays one click away in
- * the dropdown.
- * 2. **Clicks flow through the tracked redirect, never straight to GitHub.**
- * Call sites build hrefs with {@link downloadHrefForTarget}; the
+ * 1. **Platform is broadly detectable; architecture is an enhancement.**
+ * Chromium can expose architecture and bitness through high-entropy Client
+ * Hints, but availability is not universal. Docs CTAs therefore route
+ * Windows/Linux visitors to the picker, which owns any refined default.
+ * 2. **Build clicks flow through the tracked redirect, never straight to
+ * GitHub.** Explicit build links use {@link downloadHrefForTarget}; the
* `/download/stable` route resolves the asset and counts the download.
- * Linking an asset URL directly loses the event.
+ * Picker navigation is not a download, so it is counted only after the
+ * visitor chooses a build there.
*/
import {
LINUX_DEB_ARM64_URL,
@@ -129,10 +127,11 @@ export const DOWNLOAD_TARGETS: readonly DownloadTarget[] = [
] as const;
/**
- * What the primary button downloads once an OS is detected. x64 wins on
- * Windows and deb-x64 on Linux because those cover the overwhelming majority
- * of desktops; a wrong guess costs one dropdown click, and offering no default
- * costs every visitor one.
+ * The default build when a caller explicitly needs one. Windows and Linux use
+ * x64 (and Linux uses .deb), but ordinary detected-OS CTAs do not fire these
+ * guesses directly — {@link downloadHrefForDetectedOs} routes those visitors
+ * to the picker. The defaults remain useful on the picker itself and for
+ * backwards-compatible redirect resolution.
*/
const DEFAULT_TARGET_BY_OS: Record<DownloadOs, DownloadTargetId> = {
macos: 'macos-arm64',
@@ -147,6 +146,20 @@ const DEFAULT_TARGET_BY_OS: Record<DownloadOs, DownloadTargetId> = {
*/
const FALLBACK_TARGET_ID: DownloadTargetId = 'macos-arm64';
+/**
+ * Production picker host. Absolute so a standalone docs deployment cannot
+ * intercept `/download` with its legacy macOS redirect.
+ */
+const DOWNLOAD_PAGE_ORIGIN = 'https://openknowledge.ai';
+
+/** Picker page used when OS detection cannot safely select an architecture. */
+export const DOWNLOAD_PAGE_HREF = `${DOWNLOAD_PAGE_ORIGIN}/download`;
+
+/** Preserve the originating CTA across the picker hop. */
+export function downloadPageHrefForCta(cta: DownloadCta): string {
+ return `${DOWNLOAD_PAGE_HREF}?utm_content=${encodeURIComponent(cta)}`;
+}
+
/**
* Where the "run it in your browser" dropdown row points. Also the Intel-Mac
* answer — there is no Intel DMG, so the npm CLI is the only path for those
@@ -165,7 +178,7 @@ export function targetById(id: DownloadTargetId): DownloadTarget {
return target;
}
-/** The build the primary button fires for a detected OS. */
+/** The default build for an OS when a caller intentionally needs one. */
export function defaultTargetForOs(os: DetectedOs): DownloadTarget {
return targetById(os === 'unknown' ? FALLBACK_TARGET_ID : DEFAULT_TARGET_BY_OS[os]);
}
@@ -258,6 +271,16 @@ export function downloadHrefForTarget(cta: DownloadCta, target: DownloadTarget):
return `${downloadRouteForCta(cta)}&${targetQuery(target)}`;
}
+/**
+ * Default href for an OS-detected CTA. Architecture hints are not universal,
+ * so Windows and Linux visitors choose on the download page. macOS still has
+ * one published build; unknown keeps the working SSR floor.
+ */
+export function downloadHrefForDetectedOs(cta: DownloadCta, os: DetectedOs): string {
+ if (os === 'windows' || os === 'linux') return downloadPageHrefForCta(cta);
+ return downloadHrefForTarget(cta, defaultTargetForOs(os));
+}
+
/**
* Resolve the target a redirect route was asked for. Returns null when the
* triple names no published build — including the no-params case, which is