@better-forge/ui 0.1.0 → 0.1.1

package/src/components/SsoConfirmation.tsx

@@ -1,96 +1,96 @@
-import { useCallback, useEffect, useRef, useState } from 'react'
-import { getCurrentUser, type ApiError } from '../api/client'
-import { storageKey, uiConfig } from '../config'
-import { Alert } from './ui'
-
-/** The confirmation popup reports on this channel. Some providers cut `window.opener`, so no postMessage. */
-export const ssoConfirmChannel = (): string => storageKey('sso-confirm')
-const ssoConfirmUrl = () => `${uiConfig().apiBase}/auth/oidc/confirm`
-// The server-side flow expires after 10 minutes, so a popup left open longer cannot succeed.
-const SSO_CONFIRM_TIMEOUT_MS = 10 * 60 * 1000
-
-type ConfirmOutcome = 'ok' | 'failed' | 'blocked' | 'cancelled'
-
-const OUTCOME_MESSAGES: Record<Exclude<ConfirmOutcome, 'ok'>, string> = {
-  failed: 'The single sign-on confirmation did not succeed. Try again.',
-  blocked: 'The browser blocked the sign-in window. Allow pop-ups for this site and try again.',
-  cancelled: 'The single sign-on confirmation was cancelled.',
-}
-
-/** True when the session signed in with SSO, so sensitive actions are confirmed there instead of with a password. */
-export function isSsoSession(): boolean {
-  return getCurrentUser()?.authMethod === 'oidc'
-}
-
-/** True when the API refused an action until the SSO session is confirmed at the identity provider. */
-export function isSsoConfirmationRequired(error: unknown): boolean {
-  return (error as Partial<ApiError> | null)?.code === 'SSO_CONFIRMATION_REQUIRED'
-}
-
-function openSsoConfirmation(): { result: Promise<ConfirmOutcome>; cancel: () => void } {
-  const popup = window.open(ssoConfirmUrl(), ssoConfirmChannel(), 'popup,width=520,height=720')
-  if (!popup) return { result: Promise.resolve('blocked'), cancel: () => {} }
-  let finish: (outcome: ConfirmOutcome) => void = () => {}
-  const result = new Promise<ConfirmOutcome>((resolve) => {
-    const channel = new BroadcastChannel(ssoConfirmChannel())
-    const timer = setTimeout(() => finish('failed'), SSO_CONFIRM_TIMEOUT_MS)
-    finish = (outcome) => {
-      channel.close()
-      clearTimeout(timer)
-      resolve(outcome)
-    }
-    channel.onmessage = (event: MessageEvent<{ ok?: boolean }>) => finish(event.data?.ok === true ? 'ok' : 'failed')
-  })
-  return {
-    result,
-    cancel: () => {
-      finish('cancelled')
-      try { popup.close() } catch { /* already closed or no longer ours */ }
-    },
-  }
-}
-
-/**
- * Runs sensitive API calls of an SSO session. When the API asks for a confirmation, `run` opens the identity
- * provider in a popup right away and repeats the call once it succeeds; otherwise it throws with the reason.
- * The popup follows the user's click within one API round trip, which browsers still count as user-initiated.
- */
-export function useSsoConfirmation() {
-  const [waiting, setWaiting] = useState(false)
-  const cancelRef = useRef<(() => void) | null>(null)
-  useEffect(() => () => cancelRef.current?.(), [])
-
-  const run = useCallback(async <T,>(action: () => Promise<T>): Promise<T> => {
-    try {
-      return await action()
-    } catch (error) {
-      if (!isSsoConfirmationRequired(error)) throw error
-      const { result, cancel } = openSsoConfirmation()
-      cancelRef.current = cancel
-      setWaiting(true)
-      const outcome = await result
-      cancelRef.current = null
-      setWaiting(false)
-      if (outcome !== 'ok') throw new Error(OUTCOME_MESSAGES[outcome], { cause: error })
-      return action()
-    }
-  }, [])
-
-  const cancel = useCallback(() => cancelRef.current?.(), [])
-  return { run, waiting, cancel }
-}
-
-export type SsoConfirmationState = ReturnType<typeof useSsoConfirmation>
-
-/** Takes the place of a "current password" field in an SSO session: a note, or the popup's progress. */
-export function SsoConfirmationNote({ confirmation }: { confirmation: Pick<SsoConfirmationState, 'waiting' | 'cancel'> }) {
-  if (!confirmation.waiting) {
-    return <p className="text-xs" style={{ color: 'var(--m3-secondary)' }}>You signed in with single sign-on, so no password is needed. You may be asked to sign in again in a pop-up window.</p>
-  }
-  return (
-    <Alert tone="info" title="Confirm it's you">
-      <p>Sign in again with your identity provider in the pop-up window. This continues once you are done.</p>
-      <button type="button" className="btn btn-secondary btn-sm mt-3" onClick={confirmation.cancel}>Cancel</button>
-    </Alert>
-  )
-}
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { getCurrentUser, type ApiError } from '../api/client'
+import { storageKey, uiConfig } from '../config'
+import { Alert } from './ui'
+
+/** The confirmation popup reports on this channel. Some providers cut `window.opener`, so no postMessage. */
+export const ssoConfirmChannel = (): string => storageKey('sso-confirm')
+const ssoConfirmUrl = () => `${uiConfig().apiBase}/auth/oidc/confirm`
+// The server-side flow expires after 10 minutes, so a popup left open longer cannot succeed.
+const SSO_CONFIRM_TIMEOUT_MS = 10 * 60 * 1000
+
+type ConfirmOutcome = 'ok' | 'failed' | 'blocked' | 'cancelled'
+
+const OUTCOME_MESSAGES: Record<Exclude<ConfirmOutcome, 'ok'>, string> = {
+  failed: 'The single sign-on confirmation did not succeed. Try again.',
+  blocked: 'The browser blocked the sign-in window. Allow pop-ups for this site and try again.',
+  cancelled: 'The single sign-on confirmation was cancelled.',
+}
+
+/** True when the session signed in with SSO, so sensitive actions are confirmed there instead of with a password. */
+export function isSsoSession(): boolean {
+  return getCurrentUser()?.authMethod === 'oidc'
+}
+
+/** True when the API refused an action until the SSO session is confirmed at the identity provider. */
+export function isSsoConfirmationRequired(error: unknown): boolean {
+  return (error as Partial<ApiError> | null)?.code === 'SSO_CONFIRMATION_REQUIRED'
+}
+
+function openSsoConfirmation(): { result: Promise<ConfirmOutcome>; cancel: () => void } {
+  const popup = window.open(ssoConfirmUrl(), ssoConfirmChannel(), 'popup,width=520,height=720')
+  if (!popup) return { result: Promise.resolve('blocked'), cancel: () => {} }
+  let finish: (outcome: ConfirmOutcome) => void = () => {}
+  const result = new Promise<ConfirmOutcome>((resolve) => {
+    const channel = new BroadcastChannel(ssoConfirmChannel())
+    const timer = setTimeout(() => finish('failed'), SSO_CONFIRM_TIMEOUT_MS)
+    finish = (outcome) => {
+      channel.close()
+      clearTimeout(timer)
+      resolve(outcome)
+    }
+    channel.onmessage = (event: MessageEvent<{ ok?: boolean }>) => finish(event.data?.ok === true ? 'ok' : 'failed')
+  })
+  return {
+    result,
+    cancel: () => {
+      finish('cancelled')
+      try { popup.close() } catch { /* already closed or no longer ours */ }
+    },
+  }
+}
+
+/**
+ * Runs sensitive API calls of an SSO session. When the API asks for a confirmation, `run` opens the identity
+ * provider in a popup right away and repeats the call once it succeeds; otherwise it throws with the reason.
+ * The popup follows the user's click within one API round trip, which browsers still count as user-initiated.
+ */
+export function useSsoConfirmation() {
+  const [waiting, setWaiting] = useState(false)
+  const cancelRef = useRef<(() => void) | null>(null)
+  useEffect(() => () => cancelRef.current?.(), [])
+
+  const run = useCallback(async <T,>(action: () => Promise<T>): Promise<T> => {
+    try {
+      return await action()
+    } catch (error) {
+      if (!isSsoConfirmationRequired(error)) throw error
+      const { result, cancel } = openSsoConfirmation()
+      cancelRef.current = cancel
+      setWaiting(true)
+      const outcome = await result
+      cancelRef.current = null
+      setWaiting(false)
+      if (outcome !== 'ok') throw new Error(OUTCOME_MESSAGES[outcome], { cause: error })
+      return action()
+    }
+  }, [])
+
+  const cancel = useCallback(() => cancelRef.current?.(), [])
+  return { run, waiting, cancel }
+}
+
+export type SsoConfirmationState = ReturnType<typeof useSsoConfirmation>
+
+/** Takes the place of a "current password" field in an SSO session: a note, or the popup's progress. */
+export function SsoConfirmationNote({ confirmation }: { confirmation: Pick<SsoConfirmationState, 'waiting' | 'cancel'> }) {
+  if (!confirmation.waiting) {
+    return <p className="text-xs" style={{ color: 'var(--m3-secondary)' }}>You signed in with single sign-on, so no password is needed. You may be asked to sign in again in a pop-up window.</p>
+  }
+  return (
+    <Alert tone="info" title="Confirm it's you">
+      <p>Sign in again with your identity provider in the pop-up window. This continues once you are done.</p>
+      <button type="button" className="btn btn-secondary btn-sm mt-3" onClick={confirmation.cancel}>Cancel</button>
+    </Alert>
+  )
+}

package/src/components/VaultTypePicker.tsx

@@ -1,131 +1,131 @@
-import { useEffect, useId, useRef, useState } from 'react'
-import { uiConfig } from '../config'
-
-export type VaultTypeValue = 'local' | 'hashicorp'
-
-/** Only a local vault stores values; every external vault holds references to secrets kept in the provider. */
-export const isReferenceVault = (type: VaultTypeValue): boolean => type !== 'local'
-
-/** Icon per vault type, shared by the picker and the vault list so they always match. */
-export const VAULT_TYPE_ICONS: Record<VaultTypeValue, string> = { local: 'storage', hashicorp: 'vpn_key' }
-
-interface VaultTypeOption {
-  value: VaultTypeValue | null
-  label: string
-  hint: string
-  icon: string
-}
-
-/** Vault types in picker order; entries with a null value are announced but cannot be selected yet. */
-const vaultTypeOptions = (): VaultTypeOption[] => [
-  { value: 'local', label: 'Local', hint: `Encrypted in the ${uiConfig().texts.appName} database`, icon: VAULT_TYPE_ICONS.local },
-  { value: 'hashicorp', label: 'HashiCorp Vault', hint: 'Read secrets from your own HashiCorp Vault', icon: VAULT_TYPE_ICONS.hashicorp },
-  { value: null, label: 'Azure Key Vault', hint: 'Coming soon', icon: 'cloud' },
-  { value: null, label: 'GCP Secret Manager', hint: 'Coming soon', icon: 'cloud' },
-  { value: null, label: 'AWS Secrets Manager', hint: 'Coming soon', icon: 'cloud' },
-]
-
-interface Props {
-  value: VaultTypeValue
-  onChange: (type: VaultTypeValue) => void
-}
-
-function TypeIcon({ icon }: { icon: string }) {
-  return (
-    <span className="flex-none w-8 h-8 rounded-lg grid place-items-center" style={{ background: 'var(--admin-icon-container)', color: 'var(--admin-icon-color)' }}>
-      <span className="material-symbols-outlined" aria-hidden="true" style={{ fontSize: 20 }}>{icon}</span>
-    </span>
-  )
-}
-
-/** Vault type list in the same dropdown style as the other type pickers. */
-export function VaultTypePicker({ value, onChange }: Props) {
-  const [open, setOpen] = useState(false)
-  const rootRef = useRef<HTMLDivElement>(null)
-  const buttonRef = useRef<HTMLButtonElement>(null)
-  const labelId = useId()
-  const buttonId = useId()
-  const selected = vaultTypeOptions().find((t) => t.value === value)!
-
-  useEffect(() => {
-    if (!open) return
-    function onPointerDown(e: MouseEvent) {
-      if (!rootRef.current?.contains(e.target as Node)) setOpen(false)
-    }
-    function onKeyDown(e: KeyboardEvent) {
-      if (e.key !== 'Escape') return
-      e.stopPropagation()
-      setOpen(false)
-      buttonRef.current?.focus()
-    }
-    document.addEventListener('mousedown', onPointerDown)
-    document.addEventListener('keydown', onKeyDown, true)
-    return () => {
-      document.removeEventListener('mousedown', onPointerDown)
-      document.removeEventListener('keydown', onKeyDown, true)
-    }
-  }, [open])
-
-  function pick(option: VaultTypeOption) {
-    if (!option.value) return
-    setOpen(false)
-    buttonRef.current?.focus()
-    if (option.value !== value) onChange(option.value)
-  }
-
-  return (
-    <div ref={rootRef} className="relative">
-      <span id={labelId} className="block font-mono text-xs uppercase tracking-wider mb-2" style={{ color: 'var(--m3-secondary)' }}>Type</span>
-      <button
-        ref={buttonRef}
-        id={buttonId}
-        type="button"
-        aria-haspopup="listbox"
-        aria-expanded={open}
-        aria-labelledby={`${labelId} ${buttonId}`}
-        onClick={() => setOpen((o) => !o)}
-        className="w-full flex items-center gap-3 text-left rounded-xl px-3 py-2 focus-ring"
-        style={{ background: 'var(--m3-surface-container-lowest)', border: '1px solid var(--m3-outline-variant)', color: 'var(--m3-on-surface)' }}
-      >
-        <TypeIcon icon={selected.icon} />
-        <span className="min-w-0 flex-1">
-          <span className="block text-sm font-semibold">{selected.label}</span>
-          <span className="block text-xs truncate" style={{ color: 'var(--m3-secondary)' }}>{selected.hint}</span>
-        </span>
-        <span className="material-symbols-outlined" aria-hidden="true" style={{ color: 'var(--m3-secondary)' }}>unfold_more</span>
-      </button>
-
-      {open && (
-        <div
-          className="absolute z-10 left-0 right-0 mt-1.5 rounded-xl overflow-hidden shadow-xl"
-          style={{ background: 'var(--m3-surface-container-low)', border: '1px solid var(--m3-outline-variant)' }}
-        >
-          <div role="listbox" aria-labelledby={labelId} className="max-h-72 overflow-auto p-1.5">
-            {vaultTypeOptions().map((t) => {
-              const disabled = t.value === null
-              const isSelected = t.value === value
-              return (
-                <button
-                  key={t.label}
-                  type="button"
-                  role="option"
-                  aria-selected={isSelected}
-                  aria-disabled={disabled}
-                  onClick={() => pick(t)}
-                  className={`w-full flex items-center gap-3 text-left rounded-lg px-2 py-1.5 focus-ring ${disabled ? 'opacity-40 cursor-not-allowed' : 'hover:bg-[var(--m3-surface-container)]'} ${isSelected ? 'selection-active' : ''}`}
-                  style={{ border: '1px solid transparent' }}
-                >
-                  <TypeIcon icon={t.icon} />
-                  <span className="min-w-0 flex-1">
-                    <span className="block text-sm font-semibold">{t.label}</span>
-                    <span className="block text-xs truncate opacity-75">{t.hint}</span>
-                  </span>
-                </button>
-              )
-            })}
-          </div>
-        </div>
-      )}
-    </div>
-  )
-}
+import { useEffect, useId, useRef, useState } from 'react'
+import { uiConfig } from '../config'
+
+export type VaultTypeValue = 'local' | 'hashicorp'
+
+/** Only a local vault stores values; every external vault holds references to secrets kept in the provider. */
+export const isReferenceVault = (type: VaultTypeValue): boolean => type !== 'local'
+
+/** Icon per vault type, shared by the picker and the vault list so they always match. */
+export const VAULT_TYPE_ICONS: Record<VaultTypeValue, string> = { local: 'storage', hashicorp: 'vpn_key' }
+
+interface VaultTypeOption {
+  value: VaultTypeValue | null
+  label: string
+  hint: string
+  icon: string
+}
+
+/** Vault types in picker order; entries with a null value are announced but cannot be selected yet. */
+const vaultTypeOptions = (): VaultTypeOption[] => [
+  { value: 'local', label: 'Local', hint: `Encrypted in the ${uiConfig().texts.appName} database`, icon: VAULT_TYPE_ICONS.local },
+  { value: 'hashicorp', label: 'HashiCorp Vault', hint: 'Read secrets from your own HashiCorp Vault', icon: VAULT_TYPE_ICONS.hashicorp },
+  { value: null, label: 'Azure Key Vault', hint: 'Coming soon', icon: 'cloud' },
+  { value: null, label: 'GCP Secret Manager', hint: 'Coming soon', icon: 'cloud' },
+  { value: null, label: 'AWS Secrets Manager', hint: 'Coming soon', icon: 'cloud' },
+]
+
+interface Props {
+  value: VaultTypeValue
+  onChange: (type: VaultTypeValue) => void
+}
+
+function TypeIcon({ icon }: { icon: string }) {
+  return (
+    <span className="flex-none w-8 h-8 rounded-lg grid place-items-center" style={{ background: 'var(--admin-icon-container)', color: 'var(--admin-icon-color)' }}>
+      <span className="material-symbols-outlined" aria-hidden="true" style={{ fontSize: 20 }}>{icon}</span>
+    </span>
+  )
+}
+
+/** Vault type list in the same dropdown style as the other type pickers. */
+export function VaultTypePicker({ value, onChange }: Props) {
+  const [open, setOpen] = useState(false)
+  const rootRef = useRef<HTMLDivElement>(null)
+  const buttonRef = useRef<HTMLButtonElement>(null)
+  const labelId = useId()
+  const buttonId = useId()
+  const selected = vaultTypeOptions().find((t) => t.value === value)!
+
+  useEffect(() => {
+    if (!open) return
+    function onPointerDown(e: MouseEvent) {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false)
+    }
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key !== 'Escape') return
+      e.stopPropagation()
+      setOpen(false)
+      buttonRef.current?.focus()
+    }
+    document.addEventListener('mousedown', onPointerDown)
+    document.addEventListener('keydown', onKeyDown, true)
+    return () => {
+      document.removeEventListener('mousedown', onPointerDown)
+      document.removeEventListener('keydown', onKeyDown, true)
+    }
+  }, [open])
+
+  function pick(option: VaultTypeOption) {
+    if (!option.value) return
+    setOpen(false)
+    buttonRef.current?.focus()
+    if (option.value !== value) onChange(option.value)
+  }
+
+  return (
+    <div ref={rootRef} className="relative">
+      <span id={labelId} className="block font-mono text-xs uppercase tracking-wider mb-2" style={{ color: 'var(--m3-secondary)' }}>Type</span>
+      <button
+        ref={buttonRef}
+        id={buttonId}
+        type="button"
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        aria-labelledby={`${labelId} ${buttonId}`}
+        onClick={() => setOpen((o) => !o)}
+        className="w-full flex items-center gap-3 text-left rounded-xl px-3 py-2 focus-ring"
+        style={{ background: 'var(--m3-surface-container-lowest)', border: '1px solid var(--m3-outline-variant)', color: 'var(--m3-on-surface)' }}
+      >
+        <TypeIcon icon={selected.icon} />
+        <span className="min-w-0 flex-1">
+          <span className="block text-sm font-semibold">{selected.label}</span>
+          <span className="block text-xs truncate" style={{ color: 'var(--m3-secondary)' }}>{selected.hint}</span>
+        </span>
+        <span className="material-symbols-outlined" aria-hidden="true" style={{ color: 'var(--m3-secondary)' }}>unfold_more</span>
+      </button>
+
+      {open && (
+        <div
+          className="absolute z-10 left-0 right-0 mt-1.5 rounded-xl overflow-hidden shadow-xl"
+          style={{ background: 'var(--m3-surface-container-low)', border: '1px solid var(--m3-outline-variant)' }}
+        >
+          <div role="listbox" aria-labelledby={labelId} className="max-h-72 overflow-auto p-1.5">
+            {vaultTypeOptions().map((t) => {
+              const disabled = t.value === null
+              const isSelected = t.value === value
+              return (
+                <button
+                  key={t.label}
+                  type="button"
+                  role="option"
+                  aria-selected={isSelected}
+                  aria-disabled={disabled}
+                  onClick={() => pick(t)}
+                  className={`w-full flex items-center gap-3 text-left rounded-lg px-2 py-1.5 focus-ring ${disabled ? 'opacity-40 cursor-not-allowed' : 'hover:bg-[var(--m3-surface-container)]'} ${isSelected ? 'selection-active' : ''}`}
+                  style={{ border: '1px solid transparent' }}
+                >
+                  <TypeIcon icon={t.icon} />
+                  <span className="min-w-0 flex-1">
+                    <span className="block text-sm font-semibold">{t.label}</span>
+                    <span className="block text-xs truncate opacity-75">{t.hint}</span>
+                  </span>
+                </button>
+              )
+            })}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/WhatsNew.tsx

@@ -1,84 +1,84 @@
-import { safeLocalStorage } from '@better-forge/contracts'
-import { storageKey } from '../config'
-import { parseChangelog, releasesBetween, summarizeRelease, type ReleaseItem, type ReleaseNotes } from '../lib/changelog'
-import { ModalFooter, ModalHeader, ModalShell } from './ModalShell'
-
-const seenKey = (userId: number) => storageKey(`whatsnew-seen-${userId}`)
-
-/** Remembers that this user has seen the notes up to `version`. */
-export function markWhatsNewSeen(userId: number, version: string): void {
-  safeLocalStorage.set(seenKey(userId), version) // blocked storage: the notes may show again next visit
-}
-
-/**
- * Releases this user has not seen yet. A user with no record (new, or from before this existed) is only
- * marked as up to date, so the first run shows nothing.
- */
-export function pendingWhatsNew(userId: number, changelog: string, current: string): ReleaseNotes[] {
-  try {
-    const seen = safeLocalStorage.get(seenKey(userId))
-    if (seen === null) {
-      markWhatsNewSeen(userId, current)
-      return []
-    }
-    return releasesBetween(parseChangelog(changelog), seen, current).filter((release) => release.groups.length > 0)
-  } catch {
-    return []
-  }
-}
-
-const plural = (count: number, one: string, many: string) => `${count} ${count === 1 ? one : many}`
-
-/** Opening one section closes the others (shared `name`), so the dialog keeps its size. */
-function Section({ title, items, defaultOpen }: { title: string; items: ReleaseItem[]; defaultOpen?: boolean }) {
-  return (
-    <details name="whats-new-sections" open={defaultOpen} className="group rounded-xl" style={{ border: '1px solid var(--m3-outline-variant)' }}>
-      <summary className="flex items-center justify-between gap-2 px-4 py-3 cursor-pointer list-none [&::-webkit-details-marker]:hidden font-headline font-semibold text-sm" style={{ color: 'var(--m3-on-surface)' }}>
-        <span>{title} <span className="font-mono text-xs" style={{ color: 'var(--m3-outline)' }}>({items.length})</span></span>
-        <span aria-hidden="true" className="material-symbols-outlined transition-transform group-open:rotate-180" style={{ fontSize: '20px' }}>expand_more</span>
-      </summary>
-      <ul className="space-y-2 px-4 pb-3 overflow-y-auto" style={{ maxHeight: '40vh' }}>
-        {items.map((item) => (
-          <li key={item.title + item.summary} className="font-sans text-sm" style={{ color: 'var(--m3-on-surface)' }}>
-            {item.title && <span className="font-bold">{item.title}. </span>}{item.summary}
-          </li>
-        ))}
-      </ul>
-    </details>
-  )
-}
-
-/**
- * The newest release as collapsible sections (the first one with entries open, empty ones left out), earlier ones in one line each.
- * Only one section is open at a time, so the dialog stays small however many entries a release has.
- */
-export function WhatsNew({ releases, onClose, docsUrl }: { releases: ReleaseNotes[]; onClose: () => void; docsUrl: string }) {
-  const [latest, ...earlier] = releases.map(summarizeRelease)
-  const sections = [
-    { title: 'New', items: latest!.added },
-    { title: 'Changed', items: latest!.changed },
-    { title: 'Fixes', items: latest!.fixed },
-  ].filter((section) => section.items.length > 0)
-  return (
-    <ModalShell onClose={onClose} label="What's new">
-      <div className="w-full max-w-lg rounded-2xl" style={{ background: 'var(--m3-surface-container-low)', border: '1px solid var(--m3-outline-variant)' }}>
-        <ModalHeader icon="celebration" title={`What's new in ${latest!.version}`} onClose={onClose} />
-        <div className="p-6 space-y-3">
-          {sections.map((section, index) => <Section key={section.title} title={section.title} items={section.items} defaultOpen={index === 0} />)}
-          {earlier.length > 0 && (
-            <p className="font-sans text-sm pt-1" style={{ color: 'var(--m3-secondary)' }}>
-              Earlier: {earlier.map((release) => `${release.version} (${[
-                release.added.length > 0 && `${release.added.length} new`,
-                release.changed.length > 0 && plural(release.changed.length, 'change', 'changes'),
-                release.fixed.length > 0 && plural(release.fixed.length, 'fix', 'fixes'),
-              ].filter(Boolean).join(', ')})`).join(' · ')}
-            </p>
-          )}
-        </div>
-        <ModalFooter start={<a href={`${docsUrl}/changelog/`} target="_blank" rel="noopener" className="btn btn-secondary">Full changelog</a>}>
-          <button type="button" onClick={onClose} className="btn btn-primary">Got it</button>
-        </ModalFooter>
-      </div>
-    </ModalShell>
-  )
-}
+import { safeLocalStorage } from '@better-forge/contracts'
+import { storageKey } from '../config'
+import { parseChangelog, releasesBetween, summarizeRelease, type ReleaseItem, type ReleaseNotes } from '../lib/changelog'
+import { ModalFooter, ModalHeader, ModalShell } from './ModalShell'
+
+const seenKey = (userId: number) => storageKey(`whatsnew-seen-${userId}`)
+
+/** Remembers that this user has seen the notes up to `version`. */
+export function markWhatsNewSeen(userId: number, version: string): void {
+  safeLocalStorage.set(seenKey(userId), version) // blocked storage: the notes may show again next visit
+}
+
+/**
+ * Releases this user has not seen yet. A user with no record (new, or from before this existed) is only
+ * marked as up to date, so the first run shows nothing.
+ */
+export function pendingWhatsNew(userId: number, changelog: string, current: string): ReleaseNotes[] {
+  try {
+    const seen = safeLocalStorage.get(seenKey(userId))
+    if (seen === null) {
+      markWhatsNewSeen(userId, current)
+      return []
+    }
+    return releasesBetween(parseChangelog(changelog), seen, current).filter((release) => release.groups.length > 0)
+  } catch {
+    return []
+  }
+}
+
+const plural = (count: number, one: string, many: string) => `${count} ${count === 1 ? one : many}`
+
+/** Opening one section closes the others (shared `name`), so the dialog keeps its size. */
+function Section({ title, items, defaultOpen }: { title: string; items: ReleaseItem[]; defaultOpen?: boolean }) {
+  return (
+    <details name="whats-new-sections" open={defaultOpen} className="group rounded-xl" style={{ border: '1px solid var(--m3-outline-variant)' }}>
+      <summary className="flex items-center justify-between gap-2 px-4 py-3 cursor-pointer list-none [&::-webkit-details-marker]:hidden font-headline font-semibold text-sm" style={{ color: 'var(--m3-on-surface)' }}>
+        <span>{title} <span className="font-mono text-xs" style={{ color: 'var(--m3-outline)' }}>({items.length})</span></span>
+        <span aria-hidden="true" className="material-symbols-outlined transition-transform group-open:rotate-180" style={{ fontSize: '20px' }}>expand_more</span>
+      </summary>
+      <ul className="space-y-2 px-4 pb-3 overflow-y-auto" style={{ maxHeight: '40vh' }}>
+        {items.map((item) => (
+          <li key={item.title + item.summary} className="font-sans text-sm" style={{ color: 'var(--m3-on-surface)' }}>
+            {item.title && <span className="font-bold">{item.title}. </span>}{item.summary}
+          </li>
+        ))}
+      </ul>
+    </details>
+  )
+}
+
+/**
+ * The newest release as collapsible sections (the first one with entries open, empty ones left out), earlier ones in one line each.
+ * Only one section is open at a time, so the dialog stays small however many entries a release has.
+ */
+export function WhatsNew({ releases, onClose, docsUrl }: { releases: ReleaseNotes[]; onClose: () => void; docsUrl: string }) {
+  const [latest, ...earlier] = releases.map(summarizeRelease)
+  const sections = [
+    { title: 'New', items: latest!.added },
+    { title: 'Changed', items: latest!.changed },
+    { title: 'Fixes', items: latest!.fixed },
+  ].filter((section) => section.items.length > 0)
+  return (
+    <ModalShell onClose={onClose} label="What's new">
+      <div className="w-full max-w-lg rounded-2xl" style={{ background: 'var(--m3-surface-container-low)', border: '1px solid var(--m3-outline-variant)' }}>
+        <ModalHeader icon="celebration" title={`What's new in ${latest!.version}`} onClose={onClose} />
+        <div className="p-6 space-y-3">
+          {sections.map((section, index) => <Section key={section.title} title={section.title} items={section.items} defaultOpen={index === 0} />)}
+          {earlier.length > 0 && (
+            <p className="font-sans text-sm pt-1" style={{ color: 'var(--m3-secondary)' }}>
+              Earlier: {earlier.map((release) => `${release.version} (${[
+                release.added.length > 0 && `${release.added.length} new`,
+                release.changed.length > 0 && plural(release.changed.length, 'change', 'changes'),
+                release.fixed.length > 0 && plural(release.fixed.length, 'fix', 'fixes'),
+              ].filter(Boolean).join(', ')})`).join(' · ')}
+            </p>
+          )}
+        </div>
+        <ModalFooter start={<a href={`${docsUrl}/changelog/`} target="_blank" rel="noopener" className="btn btn-secondary">Full changelog</a>}>
+          <button type="button" onClick={onClose} className="btn btn-primary">Got it</button>
+        </ModalFooter>
+      </div>
+    </ModalShell>
+  )
+}