fix(web): never state the placeholder version on the what's-new dialog

Review catch (nettee, #6163): `useAppVersion()` reads /api/version at runtime,
so it necessarily boots on `APP_VERSION_PLACEHOLDER` and resolves a round-trip
later. This dialog rendered as soon as /api/whats-new resolved and printed the
hook unconditionally — so a highlights fetch that won that race painted
"Open Design 0.0.0 is here" on first frame. An invented version string, on the
one surface this PR exists to make truthful. The new suite could not see it
because it mocked the hook to an already-resolved value.

Fixed by falling back rather than gating the whole render: gating would delay
the dialog behind a second round-trip on slow networks, while the highlights
document already carries the running version in its `version` field — the
daemon stamps it for display (see contracts/api/whats-new.ts), which is what
fed the old bottom-right card's eyebrow. So `statedAppVersion()` prefers the
resolved hook, falls back to the document, and returns null when neither can
name one; on null the dialog waits, because highlights are worth nothing under
a headline that lies. The same derived value feeds the title AND every
`app_version` prop, so analytics cannot ship the placeholder either.

`APP_VERSION_PLACEHOLDER` moves out of ./provider into a new leaf
analytics/app-version.ts alongside an `isResolvedAppVersion()` predicate, so a
surface that must not PRINT a placeholder can test for it without importing the
analytics client. The provider keeps its own use of the constant.

Regression tests, red before this commit (`.red-evidence-version-race.txt`
reproduces nettee's exact string, `expected 'Open Design 0.0.0 is here…' not to
contain '0.0.0'`): the placeholder never paints while /api/version is in
flight, it never reaches the surface-view analytics, the title switches to the
running version once the hook resolves, and a document with no usable version
waits instead of inventing one. The suite's provider mock is now a mutable
holder so both sides of the race are reachable.

Also caught by this PR's own source guard: quoting the literal in a docblock
tripped it, so the comment names the constant instead.

Author: lefarcen

apps/web/src/analytics/app-version.ts

@@ -0,0 +1,24 @@
+// The app version's placeholder identity, split out of ./provider so surfaces
+// that must not RENDER a placeholder can test for it without importing the
+// analytics client.
+//
+// `useAppVersion()` reads the daemon-pinned version from /api/version at
+// runtime, so it necessarily starts on a placeholder and resolves one round-trip
+// later. Analytics tolerates that by awaiting the shared fetch before capture
+// (see `resolveAppVersionForCapture`); UI cannot await, so any surface that
+// prints the version must ask whether it has resolved yet.
+
+export const APP_VERSION_PLACEHOLDER = '0.0.0';
+
+/**
+ * Whether an app version is safe to show a user as fact.
+ *
+ * False for the pre-resolution placeholder and for anything blank, so a caller
+ * can pick another real source (or wait) instead of stating a version nobody
+ * reported.
+ */
+export function isResolvedAppVersion(version: string | null | undefined): boolean {
+  if (version == null) return false;
+  const trimmed = version.trim();
+  return trimmed.length > 0 && trimmed !== APP_VERSION_PLACEHOLDER;
+}

apps/web/src/analytics/provider.tsx

@@ -27,6 +27,7 @@ import {
   setAnalyticsUserId,
   setConfigureGlobals,
 } from './client';
+import { APP_VERSION_PLACEHOLDER } from './app-version';
 import { patchExceptionTrackingAppVersion } from './error-tracking';
 import type { AnalyticsConfigureGlobals } from '@open-design/contracts/analytics';
 import {
@@ -92,7 +93,6 @@ function isSameOriginApiCall(url: unknown): boolean {
   }
 }
 
-const APP_VERSION_PLACEHOLDER = '0.0.0';
 let runtimeAppVersion: string | null = null;
 let runtimeAppVersionPromise: Promise<string | null> | null = null;
 

apps/web/src/components/WhatsNewPopup.tsx

@@ -12,6 +12,7 @@ import {
   whatsNewNotesFromBody,
 } from '../lib/whats-new';
 import { useAnalytics, useAppVersion } from '../analytics/provider';
+import { isResolvedAppVersion } from '../analytics/app-version';
 import { trackWhatsNewPopupClick, trackWhatsNewPopupSurfaceView } from '../analytics/events';
 import styles from './WhatsNewPopup.module.css';
 
@@ -31,9 +32,33 @@ import styles from './WhatsNewPopup.module.css';
 // Fallback for the CTA when the highlight document omits an explicit link.
 const RELEASES_INDEX_URL = 'https://github.com/nexu-io/open-design/releases';
 
+/**
+ * The version this dialog is allowed to state, or null when nothing real can
+ * name one yet.
+ *
+ * `useAppVersion()` resolves one /api/version round-trip after mount, and
+ * /api/whats-new can win that race — so reading the hook unconditionally would
+ * paint `APP_VERSION_PLACEHOLDER` on first frame, i.e. exactly the invented
+ * version this surface exists to stop telling. Until the hook resolves we state
+ * the highlights document's own `version`, which the daemon stamps with the
+ * running version for display (see contracts/api/whats-new.ts): a second real
+ * source, not a second guess. If neither has landed the dialog waits — the
+ * highlights are worth nothing if the headline above them is a lie.
+ */
+function statedAppVersion(hookVersion: string, documentVersion: string): string | null {
+  if (isResolvedAppVersion(hookVersion)) return hookVersion.trim();
+  if (isResolvedAppVersion(documentVersion)) return documentVersion.trim();
+  return null;
+}
+
 type CardModel = {
   /** Highlight identity — recorded as "seen" so the dialog shows once per id. */
   id: string;
+  /**
+   * The running version as stamped on the highlights document. Stands in for
+   * `useAppVersion()` until that resolves (see `statedAppVersion`).
+   */
+  documentVersion: string;
   /** The release headline from the highlights document; labels the bullets. */
   headline: string;
   /** Release highlights, one row per line of the document's body. */
@@ -48,7 +73,7 @@ type CardModel = {
 export function WhatsNewPopup({ active }: { active: boolean }) {
   const { t, locale } = useI18n();
   const analytics = useAnalytics();
-  const appVersion = useAppVersion();
+  const hookAppVersion = useAppVersion();
   const [card, setCard] = useState<CardModel | null>(null);
   const surfaceTrackedRef = useRef(false);
   // Flips only once a decision is actually REACHED, never merely when a fetch
@@ -57,6 +82,7 @@ export function WhatsNewPopup({ active }: { active: boolean }) {
   // guard down so the next Home activation retries, instead of the teardown
   // re-arming a start-time guard and permanently swallowing the dialog.
   const decisionMadeRef = useRef(false);
+  const appVersion = card == null ? null : statedAppVersion(hookAppVersion, card.documentVersion);
 
   useEffect(() => {
     if (!active || decisionMadeRef.current) return;
@@ -72,6 +98,7 @@ export function WhatsNewPopup({ active }: { active: boolean }) {
       const localized = localizedWhatsNewContent(info.content, locale);
       setCard({
         id: info.id,
+        documentVersion: info.version,
         headline: localized.title,
         notes: whatsNewNotesFromBody(localized.body),
         imageUrl: info.content.imageUrl ?? null,
@@ -87,7 +114,7 @@ export function WhatsNewPopup({ active }: { active: boolean }) {
   }, [active]);
 
   useEffect(() => {
-    if (!active || card == null || surfaceTrackedRef.current) return;
+    if (!active || card == null || appVersion == null || surfaceTrackedRef.current) return;
     surfaceTrackedRef.current = true;
     trackWhatsNewPopupSurfaceView(analytics.track, {
       page_name: 'home',
@@ -102,7 +129,7 @@ export function WhatsNewPopup({ active }: { active: boolean }) {
   // focus-trapping modal cannot receive a stray Escape aimed at other UI, so
   // dismissal is always deliberate here.
   const dismiss = useCallback(() => {
-    if (card == null) return;
+    if (card == null || appVersion == null) return;
     markWhatsNewSeen(card.id);
     trackWhatsNewPopupClick(analytics.track, {
       page_name: 'home',
@@ -115,7 +142,7 @@ export function WhatsNewPopup({ active }: { active: boolean }) {
   }, [analytics.track, appVersion, card]);
 
   const openLink = useCallback(() => {
-    if (card == null) return;
+    if (card == null || appVersion == null) return;
     markWhatsNewSeen(card.id);
     trackWhatsNewPopupClick(analytics.track, {
       page_name: 'home',
@@ -128,7 +155,9 @@ export function WhatsNewPopup({ active }: { active: boolean }) {
     setCard(null);
   }, [analytics.track, appVersion, card]);
 
-  if (!active || card == null) return null;
+  // `appVersion == null` means neither the hook nor the document can name a
+  // version yet; the dialog waits rather than titling itself with a guess.
+  if (!active || card == null || appVersion == null) return null;
 
   const dialog = (
     <Dialog

apps/web/tests/components/WhatsNewPopup.test.tsx

@@ -34,12 +34,18 @@ vi.mock('../../src/providers/registry', () => ({
   openExternalUrl: vi.fn(),
 }));
 
+// `useAppVersion()` is asynchronous in production: it boots on a placeholder and
+// only becomes the running version once /api/version resolves. Tests drive that
+// through this mutable holder so both sides of the race are reachable.
+const appVersion = vi.hoisted(() => ({ current: '0.16.1' }));
+const track = vi.hoisted(() => vi.fn());
+
 vi.mock('../../src/analytics/provider', () => ({
-  useAnalytics: () => ({ track: vi.fn() }),
+  useAnalytics: () => ({ track }),
   // The running version the daemon reports. Deliberately different from the
   // highlight payload's `version` field so the suite can tell which one the
   // dialog renders.
-  useAppVersion: () => '0.16.1',
+  useAppVersion: () => appVersion.current,
 }));
 
 const RUNNING_APP_VERSION = '0.16.1';
@@ -79,6 +85,7 @@ afterEach(() => {
 beforeEach(() => {
   // A highlight id the user has not seen yet → decision resolves to "show".
   window.localStorage.setItem(WHATS_NEW_LAST_SEEN_STORAGE_KEY, 'highlight-0-15-0');
+  appVersion.current = RUNNING_APP_VERSION;
 });
 
 describe('WhatsNewPopup fetch/show lifecycle', () => {
@@ -168,6 +175,85 @@ describe('WhatsNewPopup fetch/show lifecycle', () => {
   });
 });
 
+// /api/version and /api/whats-new are independent round-trips, and
+// `useAppVersion()` deliberately boots on the '0.0.0' placeholder until the
+// former lands (see analytics/app-version.ts). A highlights fetch that wins
+// that race must never make this dialog state the placeholder — that is the
+// exact invented version the surface exists to stop telling.
+describe('WhatsNewPopup version resolution', () => {
+  const PLACEHOLDER_VERSION = '0.0.0';
+
+  beforeEach(() => {
+    appVersion.current = PLACEHOLDER_VERSION;
+    mockedFetchWhatsNew.mockResolvedValue(SHOW_PAYLOAD);
+  });
+
+  it('never paints the placeholder while /api/version is still in flight', async () => {
+    renderCard(true);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('whats-new-popup')).toBeTruthy();
+    });
+    expect(screen.getByTestId('whats-new-popup').textContent).not.toContain(PLACEHOLDER_VERSION);
+    // The daemon stamps the highlights document with the running version for
+    // exactly this display purpose, so it is a real source to name meanwhile.
+    expect(screen.getByText(`Open Design ${SHOW_PAYLOAD.version} is here`)).toBeTruthy();
+  });
+
+  it('keeps the placeholder out of the surface-view analytics too', async () => {
+    renderCard(true);
+
+    await waitFor(() => {
+      expect(track).toHaveBeenCalled();
+    });
+    const versions = track.mock.calls
+      .map(([, props]) => (props as { app_version?: string } | undefined)?.app_version)
+      .filter((value): value is string => typeof value === 'string');
+    expect(versions.length).toBeGreaterThan(0);
+    expect(versions).not.toContain(PLACEHOLDER_VERSION);
+  });
+
+  it('switches to the running version once /api/version resolves', async () => {
+    const view = renderCard(true);
+
+    await waitFor(() => {
+      expect(screen.getByText(`Open Design ${SHOW_PAYLOAD.version} is here`)).toBeTruthy();
+    });
+
+    appVersion.current = RUNNING_APP_VERSION;
+    view.rerender(
+      <I18nProvider>
+        <WhatsNewPopup active />
+      </I18nProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText(`Open Design ${RUNNING_APP_VERSION} is here`)).toBeTruthy();
+    });
+    expect(screen.queryByText(`Open Design ${SHOW_PAYLOAD.version} is here`)).toBeNull();
+  });
+
+  it('waits instead of inventing one when neither source can name a version', async () => {
+    mockedFetchWhatsNew.mockResolvedValue({ ...SHOW_PAYLOAD, version: '  ' });
+
+    const view = renderCard(true);
+    await act(async () => {});
+    expect(screen.queryByTestId('whats-new-popup')).toBeNull();
+
+    // …and appears as soon as the running version lands, rather than being
+    // permanently swallowed.
+    appVersion.current = RUNNING_APP_VERSION;
+    view.rerender(
+      <I18nProvider>
+        <WhatsNewPopup active />
+      </I18nProvider>,
+    );
+    await waitFor(() => {
+      expect(screen.getByText(`Open Design ${RUNNING_APP_VERSION} is here`)).toBeTruthy();
+    });
+  });
+});
+
 describe('WhatsNewPopup content', () => {
   beforeEach(() => {
     mockedFetchWhatsNew.mockResolvedValue(SHOW_PAYLOAD);