@skyhook-io/radar-app 1.16.1 → 1.16.3

package/src/components/whats-new/WhatsNew.test.ts

@@ -1,50 +1,125 @@
 import { describe, expect, it } from 'vitest'
 import { Megaphone } from 'lucide-react'
-import { nextSeenVersion, whatsNewToShow } from './WhatsNew'
-import { latestReleaseNotesFor, releaseLine, RELEASE_NOTES, releaseNotesFor, type ReleaseNotes } from './releaseNotes'
+import { nextSeenVersion, whatsNewToOpen } from './WhatsNew'
+import {
+  AUTO_OPEN_SCORE,
+  composeReleaseNotes,
+  latestReleaseNotesFor,
+  MAX_CARDS,
+  MAX_LINES,
+  releaseLine,
+  RELEASE_NOTES,
+  releaseNotesFor,
+  unreadReleases,
+  type ReleaseNotes,
+} from './releaseNotes'
 import { compareVersions } from '../../utils/version'
 
-const entry = (version: string): ReleaseNotes => ({
+const highlight = (id: string, importance: number) => ({ id, icon: Megaphone, title: id, description: 'd', importance })
+
+const entry = (version: string, importances: number[] = [9, 9, 9], improvements: string[] = []): ReleaseNotes => ({
   version,
-  releaseUrl: 'https://github.com/skyhook-io/radar/releases',
-  highlights: [{ id: 'x', icon: Megaphone, title: 'X', description: 'Y' }],
-  improvements: [],
+  highlights: importances.map((importance, i) => highlight(`${version}-${i}`, importance)),
+  improvements,
 })
 
 const catalog = [entry('v1.15.0'), entry('v2.0.0')]
 
-const show = (current: string, lastSeen: string | null, prior = true) =>
-  whatsNewToShow(current, lastSeen, prior, catalog)?.version ?? null
+const unread = (current: string, lastSeen: string | null, prior = true, list = catalog) =>
+  unreadReleases(current, lastSeen, prior, list).map(n => n.version)
 
-describe('whatsNewToShow', () => {
-  it('shows when the notes are newer than the last version seen', () => {
-    expect(show('v2.0.0', 'v1.15.0')).toBe('v2.0.0')
-    expect(show('v2.0.0', 'v2.0.0')).toBeNull()
-    expect(show('2.0.0', 'v2.0.0')).toBeNull()
+describe('unreadReleases', () => {
+  it('lists the releases after the last one seen, newest first', () => {
+    expect(unread('v2.0.0', 'v1.14.0')).toEqual(['v2.0.0', 'v1.15.0'])
+    expect(unread('v2.0.0', 'v1.15.0')).toEqual(['v2.0.0'])
+    expect(unread('v2.0.0', 'v2.0.0')).toEqual([])
+    expect(unread('2.0.0', 'v2.0.0')).toEqual([])
   })
 
-  it('shows the newest earlier notes when the running release has none of its own', () => {
-    expect(show('v1.15.1', 'v1.14.1')).toBe('v1.15.0')
-    expect(show('v2.3.4', 'v1.15.2')).toBe('v2.0.0')
+  it('covers a patch of a release with notes, and nothing above the running version', () => {
+    expect(unread('v1.15.1', 'v1.14.1')).toEqual(['v1.15.0'])
+    expect(unread('v2.3.4', 'v1.15.2')).toEqual(['v2.0.0'])
   })
 
-  it('stays closed once a later release was seen, including after a downgrade', () => {
-    expect(show('v1.15.2', 'v1.15.1')).toBeNull()
-    expect(show('v1.15.0', 'v2.0.0')).toBeNull()
+  it('is empty once a later release was seen, including after a downgrade', () => {
+    expect(unread('v1.15.2', 'v1.15.1')).toEqual([])
+    expect(unread('v1.15.0', 'v2.0.0')).toEqual([])
   })
 
-  it('stays closed on a fresh install, and shows for installs that predate the seen record', () => {
-    expect(show('v2.0.0', null, false)).toBeNull()
-    expect(show('v2.0.0', null, true)).toBe('v2.0.0')
+  it('is empty on a fresh install, and covers everything for installs that predate the seen record', () => {
+    expect(unread('v2.0.0', null, false)).toEqual([])
+    expect(unread('v2.0.0', null, true)).toEqual(['v2.0.0', 'v1.15.0'])
   })
 
   it('treats a record that is not a version as an install with nothing seen', () => {
-    expect(show('v2.0.0', 'vdev', false)).toBe('v2.0.0')
+    expect(unread('v2.0.0', 'vdev', false)).toEqual(['v2.0.0', 'v1.15.0'])
+  })
+
+  it('is empty when no notes exist at or below the running version', () => {
+    expect(unread('v1.14.9', 'v1.14.0')).toEqual([])
+    expect(unread('dev', 'v1.14.1')).toEqual([])
+  })
+
+  it('orders by version whatever the catalog order', () => {
+    expect(unread('v2.0.0', null, true, [entry('v1.15.0'), entry('v2.0.0'), entry('v1.16.0')])).toEqual(['v2.0.0', 'v1.16.0', 'v1.15.0'])
+  })
+})
+
+describe('composeReleaseNotes', () => {
+  it('ranks highlights by importance, weighting older releases down', () => {
+    const notes = composeReleaseNotes([entry('v1.17.0', [6]), entry('v1.16.0', [9]), entry('v1.15.0', [10])])
+    expect(notes.highlights.map(h => [h.id, h.score])).toEqual([
+      ['v1.16.0-0', 6.75],
+      ['v1.17.0-0', 6],
+      ['v1.15.0-0', 5],
+    ])
+  })
+
+  it('breaks ties toward the newer release, then the authored order', () => {
+    const notes = composeReleaseNotes([entry('v1.16.0', [3, 6]), entry('v1.15.0', [8])])
+    expect(notes.highlights.map(h => h.id)).toEqual(['v1.16.0-1', 'v1.15.0-0', 'v1.16.0-0'])
+  })
+
+  it('keeps the authored order of a single release with equal importance', () => {
+    expect(composeReleaseNotes([entry('v1.16.0', [5, 5, 5])]).highlights.map(h => h.id)).toEqual(['v1.16.0-0', 'v1.16.0-1', 'v1.16.0-2'])
+  })
+
+  it('shows at most three releases and says when older ones were left out', () => {
+    const four = [entry('v1.18.0'), entry('v1.17.0'), entry('v1.16.0'), entry('v1.15.0')]
+    const notes = composeReleaseNotes(four)
+    expect(notes.versions).toEqual(['v1.18.0', 'v1.17.0', 'v1.16.0'])
+    expect(notes.complete).toBe(false)
+    expect(notes.highlights.some(h => h.version === 'v1.15.0')).toBe(false)
+    expect(composeReleaseNotes(four.slice(0, 3)).complete).toBe(true)
+  })
+
+  it('turns highlights past the cards into lines ahead of the improvements, within the line cap', () => {
+    const notes = composeReleaseNotes([
+      entry('v1.16.0', [7, 7, 7, 7, 7, 2], ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']),
+      entry('v1.15.0', [1], ['old']),
+    ])
+    expect(notes.highlights).toHaveLength(MAX_CARDS)
+    expect(notes.lines).toHaveLength(MAX_LINES)
+    expect(notes.lines.slice(0, 2).map(l => l.text)).toEqual(['v1.16.0-5', 'v1.15.0-0'])
+    expect(notes.lines.map(l => l.text)).not.toContain('old')
+  })
+
+  it('scores the dialog by the cards it shows', () => {
+    expect(composeReleaseNotes([entry('v1.16.0', [4, 4, 4, 4, 4, 10])]).score).toBe(10 + 4 * 4)
+  })
+})
+
+describe('whatsNewToOpen', () => {
+  it('opens when the unseen releases show enough, and not for a quiet release', () => {
+    const list = [entry('v1.15.0', [9, 8, 7, 7, 7]), entry('v1.16.0', [6, 5, 4])]
+    expect(whatsNewToOpen('v1.15.0', 'v1.14.1', true, list)?.score).toBe(38)
+    expect(whatsNewToOpen('v1.16.0', 'v1.15.0', true, list)).toBeNull()
+    expect(whatsNewToOpen('v1.16.0', 'v1.14.1', true, list)?.score).toBeGreaterThanOrEqual(AUTO_OPEN_SCORE)
   })
 
-  it('stays closed when no notes exist at or below the running version', () => {
-    expect(show('v1.14.9', 'v1.14.0')).toBeNull()
-    expect(show('dev', 'v1.14.1')).toBeNull()
+  it('stays closed when nothing is unseen', () => {
+    expect(whatsNewToOpen('v2.0.0', 'v2.0.0', true, catalog)).toBeNull()
+    expect(whatsNewToOpen('v2.0.0', null, false, catalog)).toBeNull()
   })
 })
 
@@ -91,13 +166,17 @@ describe('the shipped catalog', () => {
     expect(new Set(versions).size).toBe(versions.length)
     for (const notes of RELEASE_NOTES) {
       expect(notes.version, notes.version).toMatch(/^v\d+\.\d+\.\d+$/)
-      expect(notes.highlights.length, `${notes.version} needs a lead highlight`).toBeGreaterThan(0)
+      expect(notes.highlights.length, `${notes.version} needs a highlight`).toBeGreaterThan(0)
       expect(new Set(notes.highlights.map(h => h.id)).size, `${notes.version} highlight ids`).toBe(notes.highlights.length)
+      expect(new Set(notes.improvements).size, `${notes.version} improvements`).toBe(notes.improvements.length)
+      const top = notes.highlights.reduce((best, h) => (h.importance > best.importance ? h : best))
       for (const h of notes.highlights) {
+        expect(h.description.length, `${notes.version}/${h.id}: description fits a card`).toBeLessThanOrEqual(150)
+        if (h.leadDescription) expect(h.id, `${notes.version}/${h.id}: only the release's top highlight can lead`).toBe(top.id)
+        expect(Number.isInteger(h.importance) && h.importance >= 1 && h.importance <= 10, `${notes.version}/${h.id}: importance is 1-10`).toBe(true)
         expect(!!h.path === !!h.cta, `${notes.version}/${h.id}: path and cta go together`).toBe(true)
         if (h.path) expect(h.path, `${notes.version}/${h.id}`).toMatch(/^\//)
       }
-      expect(notes.releaseUrl, notes.version).toMatch(/^https:\/\//)
     }
   })
 })

package/src/components/whats-new/WhatsNew.tsx

@@ -7,33 +7,42 @@ import { DialogPortal } from '@skyhook-io/k8s-ui'
 import { getApiBase } from '../../api/config'
 import { markWhatsNewSeen, useCapabilities, useWhatsNewState, type WhatsNewState } from '../../api/client'
 import { compareVersions } from '../../utils/version'
-import { latestReleaseNotesFor, releaseLine, releaseNotesFor, RELEASE_NOTES, type HighlightTone, type ReleaseHighlight, type ReleaseNotes } from './releaseNotes'
+import {
+  AUTO_OPEN_SCORE,
+  CHANGELOG_URL,
+  composeReleaseNotes,
+  latestReleaseNotesFor,
+  releaseLine,
+  releaseNotesFor,
+  RELEASE_NOTES,
+  unreadReleases,
+  type ComposedHighlight,
+  type ComposedNotes,
+  type ReleaseNotes,
+} from './releaseNotes'
 import type { UsageDataStatus } from '../../api/usage-data'
 import { UsageDataAsk } from '../usage-data/UsageDataAsk'
 
 const LAST_SEEN_KEY = 'radar-whats-new-seen'
 const PREVIEW_PARAM = 'whats-new'
+const PREVIEW_FROM_PARAM = 'whats-new-from'
 export const SHOW_WHATS_NEW_EVENT = 'radar:show-whats-new'
 
 /**
- * The notes to open automatically, if any: the newest release at or below the
- * running version that is newer than what was last seen. A fresh install has
- * nothing to compare against and sees nothing; an install that predates the
- * seen record sees the notes once.
+ * The notes to open automatically, if any: the unseen releases, composed, when
+ * what they'd show is worth an interruption. Unseen notes below the bar stay
+ * behind the nav rail's unread dot.
  */
-export function whatsNewToShow(
+export function whatsNewToOpen(
   currentVersion: string,
   lastSeen: string | null,
   priorInstall: boolean,
   catalog: ReleaseNotes[] = RELEASE_NOTES,
-): ReleaseNotes | null {
-  const notes = latestReleaseNotesFor(currentVersion, catalog)
-  if (!notes) return null
-  // A record that isn't a version (a development build's) proves an install
-  // but says nothing about which notes were seen.
-  const newer = lastSeen === null ? null : compareVersions(notes.version, lastSeen)
-  if (newer === null) return lastSeen !== null || priorInstall ? notes : null
-  return newer > 0 ? notes : null
+): ComposedNotes | null {
+  const unread = unreadReleases(currentVersion, lastSeen, priorInstall, catalog)
+  if (unread.length === 0) return null
+  const notes = composeReleaseNotes(unread)
+  return notes.score >= AUTO_OPEN_SCORE ? notes : null
 }
 
 /**
@@ -120,9 +129,21 @@ interface WhatsNewProps {
   usageData?: UsageDataStatus
 }
 
+interface DialogView {
+  notes: ComposedNotes
+  /** The last version the user saw notes for, when this view covers what came after it. */
+  since: string | null
+  /** The version the notes bring the user up to. */
+  to: string
+  /** Closing records `to` as seen; previews record nothing. */
+  acknowledges: boolean
+}
+
 /**
- * Opens once after Radar is upgraded to a version that has release notes.
- * `?whats-new` (or `?whats-new=v1.15.0`) opens it on demand for previews.
+ * Opens after an upgrade when the releases the user hasn't seen have enough to
+ * show; otherwise the nav rail's unread dot carries them.
+ * `?whats-new` (or `?whats-new=v1.15.0`) opens it on demand for previews, and
+ * `&whats-new-from=v1.14.0` previews it as composed for an upgrade from that version.
  */
 export function WhatsNew({ onNavigate, usageData }: WhatsNewProps) {
   const { data: capabilities } = useCapabilities()
@@ -131,9 +152,9 @@ export function WhatsNew({ onNavigate, usageData }: WhatsNewProps) {
   const { data: state } = useWhatsNewState(!!capabilities && !isCloud)
   const queryClient = useQueryClient()
   const [searchParams, setSearchParams] = useSearchParams()
-  const [notes, setNotes] = useState<ReleaseNotes | null>(null)
+  // Fixed while open, so an acknowledgment from another tab can't reshuffle what's being read.
+  const [view, setView] = useState<DialogView | null>(null)
   const [open, setOpen] = useState(false)
-  const [previousVersion, setPreviousVersion] = useState<string | null>(null)
   // In-cluster only; undefined when browser storage is unavailable.
   const [browserLastSeen, setBrowserLastSeen] = useState(readBrowserLastSeen)
   const decidedRef = useRef(false)
@@ -142,6 +163,7 @@ export function WhatsNew({ onNavigate, usageData }: WhatsNewProps) {
 
   const currentVersion = state?.currentVersion
   const previewParam = searchParams.get(PREVIEW_PARAM)
+  const previewFrom = searchParams.get(PREVIEW_FROM_PARAM)
   // One authority per install: the server record for a personal install, this
   // browser's storage for a shared one. undefined = nothing can be recorded.
   const lastSeen = !state ? undefined : state.storage === 'server' ? state.seenVersion ?? null : browserLastSeen
@@ -154,10 +176,12 @@ export function WhatsNew({ onNavigate, usageData }: WhatsNewProps) {
     return () => window.removeEventListener('storage', onStorage)
   }, [])
 
-  const recordSeen = useCallback((s: WhatsNewState, seen: string | null) => {
-    const next = nextSeenVersion(s.currentVersion, seen)
+  // Records the version a dialog was opened for, not the running one: the
+  // server can be upgraded while the dialog is open.
+  const recordSeen = useCallback((version: string, storage: WhatsNewState['storage'], seen: string | null) => {
+    const next = nextSeenVersion(version, seen)
     if (next === null) return
-    if (s.storage === 'browser') {
+    if (storage === 'browser') {
       writeBrowserLastSeen(next)
       setBrowserLastSeen(readBrowserLastSeen())
       return
@@ -174,59 +198,70 @@ export function WhatsNew({ onNavigate, usageData }: WhatsNewProps) {
     )
   }, [queryClient])
 
+  const show = useCallback((next: DialogView) => {
+    setView(next)
+    setOpen(true)
+  }, [])
+
   useEffect(() => {
     if (previewParam === null) return
-    const preview = releaseNotesFor(previewParam) ?? latestReleaseNotesFor(currentVersion) ?? RELEASE_NOTES[0]
-    if (!preview) return
-    setPreviousVersion(null)
-    setNotes(preview)
-    setOpen(true)
-  }, [previewParam, currentVersion])
+    const target = releaseNotesFor(previewParam)?.version ?? currentVersion ?? RELEASE_NOTES[0]?.version
+    if (!target) return
+    const upgrade = previewFrom ? unreadReleases(target, previewFrom, true) : []
+    if (upgrade.length > 0) {
+      show({ notes: composeReleaseNotes(upgrade), since: previewFrom, to: target, acknowledges: false })
+      return
+    }
+    const single = releaseNotesFor(previewParam) ?? latestReleaseNotesFor(currentVersion) ?? RELEASE_NOTES[0]
+    if (single) show({ notes: composeReleaseNotes([single]), since: null, to: single.version, acknowledges: false })
+  }, [previewParam, previewFrom, currentVersion, show])
 
   useEffect(() => {
     if (!state || lastSeen === undefined || previewParam !== null || decidedRef.current) return
     decidedRef.current = true
-    const due = whatsNewToShow(state.currentVersion, lastSeen, priorInstall)
+    const due = whatsNewToOpen(state.currentVersion, lastSeen, priorInstall)
     // Only on Home: someone arriving on a deep link came for that page, often
     // mid-incident. Elsewhere the nav rail's unread dot carries the notes.
     if (due && (pathname === '/' || pathname === '/home')) {
-      setPreviousVersion(lastSeen)
-      setNotes(due)
-      setOpen(true)
-    } else if (!due && lastSeen === null) {
-      recordSeen(state, lastSeen)
+      show({ notes: due, since: lastSeen, to: state.currentVersion, acknowledges: true })
+    } else if (lastSeen === null && unreadReleases(state.currentVersion, lastSeen, priorInstall).length === 0) {
+      // A fresh install: start the record, so the next upgrade has something to compare against.
+      recordSeen(state.currentVersion, state.storage, lastSeen)
     }
   // Decided once, when the state loads; the preview param is handled above.
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [state?.currentVersion, state?.storage])
 
   const available = !!state && !isCloud && !!latestReleaseNotesFor(state.currentVersion)
-  const unread = available && lastSeen !== undefined && !!whatsNewToShow(state.currentVersion, lastSeen, priorInstall)
+  const unread = available && lastSeen !== undefined && unreadReleases(state.currentVersion, lastSeen, priorInstall).length > 0
   useEffect(() => { publishStatus({ available, unread }) }, [available, unread])
   useEffect(() => () => publishStatus(NO_STATUS), [])
 
   useEffect(() => {
     const handler = () => {
-      const latest = latestReleaseNotesFor(currentVersion) ?? RELEASE_NOTES[0]
-      if (!latest) return
-      setPreviousVersion(null)
-      setNotes(latest)
-      setOpen(true)
+      if (!currentVersion) return
+      const pending = lastSeen === undefined ? [] : unreadReleases(currentVersion, lastSeen, priorInstall)
+      if (pending.length > 0) {
+        show({ notes: composeReleaseNotes(pending), since: lastSeen ?? null, to: currentVersion, acknowledges: true })
+        return
+      }
+      const latest = latestReleaseNotesFor(currentVersion)
+      if (latest) show({ notes: composeReleaseNotes([latest]), since: null, to: currentVersion, acknowledges: true })
     }
     window.addEventListener(SHOW_WHATS_NEW_EVENT, handler)
     return () => window.removeEventListener(SHOW_WHATS_NEW_EVENT, handler)
-  }, [currentVersion])
+  }, [currentVersion, lastSeen, priorInstall, show])
 
   const close = useCallback(() => {
     setOpen(false)
-    // A preview of another release acknowledges nothing about this one.
-    if (state && lastSeen !== undefined && notes && notes === latestReleaseNotesFor(state.currentVersion)) recordSeen(state, lastSeen)
-    if (searchParams.has(PREVIEW_PARAM)) {
+    if (view?.acknowledges && state && lastSeen !== undefined) recordSeen(view.to, state.storage, lastSeen)
+    if (searchParams.has(PREVIEW_PARAM) || searchParams.has(PREVIEW_FROM_PARAM)) {
       const next = new URLSearchParams(searchParams)
       next.delete(PREVIEW_PARAM)
+      next.delete(PREVIEW_FROM_PARAM)
       setSearchParams(next, { replace: true })
     }
-  }, [state, lastSeen, notes, recordSeen, searchParams, setSearchParams])
+  }, [state, lastSeen, view, recordSeen, searchParams, setSearchParams])
 
   const go = useCallback((path: string) => {
     close()
@@ -242,12 +277,12 @@ export function WhatsNew({ onNavigate, usageData }: WhatsNewProps) {
 
   return (
     <DialogPortal open={open} onClose={close} ariaLabelledBy={titleId} className="w-[760px] max-w-[calc(100vw-2rem)] max-h-[min(840px,calc(100vh-4rem))] flex flex-col overflow-hidden rounded-xl">
-      {notes && (
+      {view && (
         <WhatsNewContent
           titleId={titleId}
-          notes={notes}
-          previousVersion={previousVersion}
-          currentVersion={currentVersion}
+          notes={view.notes}
+          since={view.since}
+          to={view.to}
           onClose={close}
           onNavigate={go}
           ask={<UsageDataAsk usageData={usageData} onReadMore={readAboutUsageData} />}
@@ -259,10 +294,11 @@ export function WhatsNew({ onNavigate, usageData }: WhatsNewProps) {
 
 interface WhatsNewContentProps {
   titleId?: string
-  notes: ReleaseNotes
-  previousVersion?: string | null
-  /** The running version, which can be newer than the release the notes are for. */
-  currentVersion?: string
+  notes: ComposedNotes
+  /** The last version the user saw notes for, when the notes cover what came after it. */
+  since?: string | null
+  /** The version the notes bring the user up to, which can be newer than the releases they cover. */
+  to?: string
   onClose: () => void
   onNavigate: (path: string) => void
   // Rendered between the notes and the footer, outside the scroll area so it
@@ -270,10 +306,24 @@ interface WhatsNewContentProps {
   ask?: ReactNode
 }
 
-export function WhatsNewContent({ titleId, notes, previousVersion, currentVersion, onClose, onNavigate, ask }: WhatsNewContentProps) {
+function isVersion(version: string | null | undefined): version is string {
+  return !!version && compareVersions(version, version) !== null
+}
+
+export function WhatsNewContent({ titleId, notes, since, to: toVersion, onClose, onNavigate, ask }: WhatsNewContentProps) {
   const [lead, ...rest] = notes.highlights
-  const to = currentVersion ? normalize(currentVersion) : notes.version
-  const from = previousVersion && normalize(previousVersion) !== to ? normalize(previousVersion) : null
+  const newest = notes.versions[0]
+  const mixed = notes.versions.length > 1
+  const to = isVersion(toVersion) ? normalize(toVersion) : newest
+  const from = isVersion(since) && normalize(since) !== to ? normalize(since) : null
+  // Older releases than the dialog covers were left out, so "since" would overpromise.
+  const title = !mixed
+    ? <>What's new in Radar <span className="font-mono">{releaseLine(newest)}</span></>
+    : from && notes.complete
+      ? <>What's new since Radar <span className="font-mono">{releaseLine(from)}</span></>
+      : <>Recent highlights in Radar</>
+  // Only releases older than the newest are tagged: the heading already names it.
+  const olderTag = (version: string) => mixed && version !== newest ? releaseLine(version) : null
 
   return (
     <>
@@ -284,17 +334,16 @@ export function WhatsNewContent({ titleId, notes, previousVersion, currentVersio
           </div>
           <div className="min-w-0">
             <h2 id={titleId} className="text-lg font-semibold text-theme-text-primary leading-tight">
-              What's new in Radar <span className="font-mono">{releaseLine(notes.version)}</span>
+              {title}
             </h2>
             {from ? (
               <p className="flex flex-wrap items-center gap-1.5 mt-1.5 text-xs text-theme-text-tertiary">
-                <span>You just updated</span>
                 <span className="font-mono px-1.5 py-0.5 rounded bg-theme-elevated text-theme-text-secondary">{from}</span>
                 <ArrowRight className="w-3 h-3" aria-label="to" />
                 <span className="font-mono px-1.5 py-0.5 rounded bg-accent-muted text-accent-text">{to}</span>
               </p>
             ) : (
-              <p className="mt-1 text-xs text-theme-text-tertiary">Highlights from this release</p>
+              <p className="mt-1 text-xs text-theme-text-tertiary">{mixed ? 'Highlights from recent releases' : 'Highlights from this release'}</p>
             )}
           </div>
         </div>
@@ -313,29 +362,35 @@ export function WhatsNewContent({ titleId, notes, previousVersion, currentVersio
         <ul className="grid grid-cols-1 sm:grid-cols-2 gap-2">
           {lead && (
             <li className="sm:col-span-2">
-              <HighlightCard item={lead} lead onNavigate={onNavigate} />
+              <HighlightCard item={lead} lead tag={olderTag(lead.version)} onNavigate={onNavigate} />
             </li>
           )}
           {rest.map((item, i) => (
             // An odd card out spans the row instead of leaving a hole beside it.
-            <li key={item.id} className={clsx(rest.length % 2 === 1 && i === rest.length - 1 && 'sm:col-span-2')}>
-              <HighlightCard item={item} onNavigate={onNavigate} />
+            <li key={`${item.version}/${item.id}`} className={clsx(rest.length % 2 === 1 && i === rest.length - 1 && 'sm:col-span-2')}>
+              <HighlightCard item={item} tone={TONE_TILES[i % TONE_TILES.length]} tag={olderTag(item.version)} onNavigate={onNavigate} />
             </li>
           ))}
         </ul>
 
-        {notes.improvements.length > 0 && (
+        {notes.lines.length > 0 && (
           <div className="mt-4">
             <h3 className="text-xs font-medium uppercase tracking-wide text-theme-text-tertiary mb-2">
-              Also in this release
+              {mixed ? 'Also new' : 'Also in this release'}
             </h3>
             <ul className="grid grid-cols-1 sm:grid-cols-2 gap-x-6 gap-y-1">
-              {notes.improvements.map(line => (
-                <li key={line} className="flex gap-2 text-xs text-theme-text-secondary leading-relaxed">
-                  <Check className="w-3.5 h-3.5 mt-px text-accent shrink-0" aria-hidden />
-                  {line}
-                </li>
-              ))}
+              {notes.lines.map(line => {
+                const tag = olderTag(line.version)
+                return (
+                  <li key={`${line.version}/${line.text}`} className="flex gap-2 text-xs text-theme-text-secondary leading-relaxed">
+                    <Check className="w-3.5 h-3.5 mt-px text-accent shrink-0" aria-hidden />
+                    <span>
+                      {line.text}
+                      {tag && <span className="ml-1.5 font-mono text-[11px] text-theme-text-tertiary">{tag}</span>}
+                    </span>
+                  </li>
+                )
+              })}
             </ul>
           </div>
         )}
@@ -343,15 +398,15 @@ export function WhatsNewContent({ titleId, notes, previousVersion, currentVersio
 
       {ask}
 
-      <div className="flex items-center justify-between gap-3 px-6 py-3 border-t border-theme-border bg-theme-base/60">
+      <div className="flex items-center justify-end gap-2 px-6 py-3 border-t border-theme-border bg-theme-base/60">
         <a
-          href={notes.releaseUrl}
+          href={CHANGELOG_URL}
           target="_blank"
           rel="noopener noreferrer"
-          className="inline-flex items-center gap-1 text-xs text-theme-text-secondary hover:text-theme-text-primary hover:underline"
+          className="inline-flex items-center gap-1.5 rounded-lg border border-theme-border px-4 py-1.5 text-sm font-medium text-theme-text-secondary hover:bg-theme-hover hover:text-theme-text-primary"
         >
-          Full release notes
-          <ExternalLink className="w-3 h-3" aria-hidden />
+          Full changelog
+          <ExternalLink className="w-3.5 h-3.5" aria-hidden />
         </a>
         <button type="button" onClick={onClose} className="btn-brand px-4 py-1.5 text-sm font-medium rounded-lg">
           Got it
@@ -361,17 +416,21 @@ export function WhatsNewContent({ titleId, notes, previousVersion, currentVersio
   )
 }
 
-// Literal class strings so Tailwind keeps them.
-const TONE_TILE: Record<HighlightTone, string> = {
-  violet: 'bg-violet-500/10 text-violet-600 dark:text-violet-400',
-  teal: 'bg-teal-500/10 text-teal-600 dark:text-teal-400',
-  emerald: 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
-  indigo: 'bg-indigo-500/10 text-indigo-600 dark:text-indigo-400',
-}
-
-function HighlightCard({ item, lead = false, onNavigate }: {
-  item: ReleaseHighlight
+// By position, not by release, so cards mixed from several releases never
+// repeat a color. Literal class strings so Tailwind keeps them.
+const TONE_TILES = [
+  'bg-violet-500/10 text-violet-600 dark:text-violet-400',
+  'bg-teal-500/10 text-teal-600 dark:text-teal-400',
+  'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+  'bg-indigo-500/10 text-indigo-600 dark:text-indigo-400',
+]
+
+function HighlightCard({ item, lead = false, tone, tag, onNavigate }: {
+  item: ComposedHighlight
   lead?: boolean
+  tone?: string
+  /** The release an older highlight came from, when the dialog mixes releases. */
+  tag?: string | null
   onNavigate: (path: string) => void
 }) {
   const Icon = item.icon
@@ -386,16 +445,17 @@ function HighlightCard({ item, lead = false, onNavigate }: {
     <>
       <span className={clsx(
         'flex items-center justify-center shrink-0 rounded-lg',
-        lead ? 'w-10 h-10 bg-accent text-white' : clsx('w-8 h-8', item.tone ? TONE_TILE[item.tone] : 'bg-accent-muted text-accent'),
+        lead ? 'w-10 h-10 bg-accent text-white' : clsx('w-8 h-8', tone ?? 'bg-accent-muted text-accent'),
       )}>
         <Icon className={lead ? 'w-5 h-5' : 'w-4 h-4'} aria-hidden />
       </span>
       <span className="block min-w-0 flex-1">
         <span className={clsx('block font-medium text-theme-text-primary leading-snug', lead ? 'text-base' : 'text-sm')}>
           {item.title}
+          {tag && <span className="ml-1.5 font-mono font-normal text-[11px] text-theme-text-tertiary">{tag}</span>}
         </span>
         <span id={descriptionId} className={clsx('block mt-0.5 text-theme-text-secondary leading-relaxed', lead ? 'text-sm' : 'text-xs')}>
-          {item.description}
+          {lead ? item.leadDescription ?? item.description : item.description}
         </span>
         {actionable && (
           <span className="inline-flex items-center gap-1 mt-1.5 text-xs font-medium text-accent-text group-hover:underline">