@retiregolden/planner-ui 0.1.0

package/src/planner/ComparePlansPage.tsx

@@ -0,0 +1,219 @@
+/**
+ * Cross-plan compare: load two independent saved plans and show headline
+ * deterministic results side by side. This intentionally complements
+ * Scenarios, which compares variants inside one plan.
+ */
+
+import { useEffect, useMemo, useState } from 'react'
+import { Link } from 'react-router-dom'
+
+import { listUserPlanSummaries, loadPlan, type PlanSummary } from '../data/planStore'
+import type { Plan } from '@retiregolden/engine/model/plan'
+import type { ProjectionSummary } from '@retiregolden/engine/projection/compare'
+import { fmtMoneyCompact } from './format'
+import { projectPlan, type ProjectionView } from './useProjection'
+
+interface ComparedPlan {
+  plan: Plan
+  view: ProjectionView
+}
+
+function resultLabel(summary: ProjectionSummary, endYear: number): string {
+  return summary.depletionYear === null ? `Full plan through ${endYear}` : `Depletes in ${summary.depletionYear}`
+}
+
+function primaryAgeIn(plan: Plan, year: number | null): string {
+  if (year === null) return '—'
+  const dobYear = Number(plan.household.people[0]?.dob.slice(0, 4))
+  return Number.isFinite(dobYear) ? String(year - dobYear) : '—'
+}
+
+function deltaClass(value: number): string | undefined {
+  if (Math.abs(value) < 0.5) return undefined
+  return value > 0 ? 'delta-pos' : 'delta-neg'
+}
+
+function moneyDelta(value: number): string {
+  const sign = value > 0 ? '+' : ''
+  return `${sign}${fmtMoneyCompact(value)}`
+}
+
+function MetricRow({
+  label,
+  a,
+  b,
+  delta,
+  higherIsGood = true,
+}: {
+  label: string
+  a: string
+  b: string
+  delta?: number
+  higherIsGood?: boolean
+}) {
+  const adjustedDelta = delta === undefined ? undefined : higherIsGood ? delta : -delta
+  return (
+    <tr>
+      <th>{label}</th>
+      <td>{a}</td>
+      <td>{b}</td>
+      <td className={adjustedDelta === undefined ? undefined : deltaClass(adjustedDelta)}>
+        {delta === undefined ? '—' : moneyDelta(delta)}
+      </td>
+    </tr>
+  )
+}
+
+export function ComparePlansPage() {
+  const [summaries, setSummaries] = useState<PlanSummary[] | null>(null)
+  const [leftId, setLeftId] = useState('')
+  const [rightId, setRightId] = useState('')
+  const [left, setLeft] = useState<ComparedPlan | null>(null)
+  const [right, setRight] = useState<ComparedPlan | null>(null)
+  const [notice, setNotice] = useState<string | null>(null)
+
+  useEffect(() => {
+    void listUserPlanSummaries().then((items) => {
+      setSummaries(items)
+      setLeftId(items[0]?.id ?? '')
+      setRightId(items.find((p) => p.id !== items[0]?.id)?.id ?? '')
+    })
+  }, [])
+
+  useEffect(() => {
+    let cancelled = false
+    async function loadCompared(id: string, setter: (plan: ComparedPlan | null) => void) {
+      if (!id) {
+        setter(null)
+        return
+      }
+      const r = await loadPlan(id)
+      if (cancelled) return
+      if (r.ok) setter({ plan: r.plan, view: projectPlan(r.plan) })
+      else {
+        setter(null)
+        setNotice(`Could not load one of those plans (${r.reason}).`)
+      }
+    }
+    void loadCompared(leftId, setLeft)
+    void loadCompared(rightId, setRight)
+    return () => {
+      cancelled = true
+    }
+  }, [leftId, rightId])
+
+  const options = summaries ?? []
+  const canCompare = left !== null && right !== null && left.plan.id !== right.plan.id
+  const rows = useMemo(() => {
+    if (!canCompare) return []
+    const l = left.view.summary
+    const r = right.view.summary
+    return [
+      {
+        label: 'Ending net worth',
+        a: fmtMoneyCompact(l.endingNetWorth),
+        b: fmtMoneyCompact(r.endingNetWorth),
+        delta: r.endingNetWorth - l.endingNetWorth,
+      },
+      {
+        label: 'Ending investable',
+        a: fmtMoneyCompact(l.endingInvestable),
+        b: fmtMoneyCompact(r.endingInvestable),
+        delta: r.endingInvestable - l.endingInvestable,
+      },
+      {
+        label: 'After-tax estate',
+        a: fmtMoneyCompact(l.endingAfterTaxEstate),
+        b: fmtMoneyCompact(r.endingAfterTaxEstate),
+        delta: r.endingAfterTaxEstate - l.endingAfterTaxEstate,
+      },
+      {
+        label: 'Success % (deterministic)',
+        a: l.depletionYear === null ? '100%' : '0%',
+        b: r.depletionYear === null ? '100%' : '0%',
+      },
+      {
+        label: 'Depletion age (primary)',
+        a: primaryAgeIn(left.plan, l.depletionYear),
+        b: primaryAgeIn(right.plan, r.depletionYear),
+      },
+      {
+        label: 'Lifetime tax + penalties',
+        a: fmtMoneyCompact(l.lifetimeTaxesAndPenalties),
+        b: fmtMoneyCompact(r.lifetimeTaxesAndPenalties),
+        delta: r.lifetimeTaxesAndPenalties - l.lifetimeTaxesAndPenalties,
+        higherIsGood: false,
+      },
+    ]
+  }, [canCompare, left, right])
+
+  return (
+    <section className="page planner-shell" style={{ textAlign: 'left' }}>
+      <div className="results-toolbar">
+        <Link to="/" className="btn btn-secondary btn-small">
+          Back to plans
+        </Link>
+      </div>
+      <h1>Compare plans</h1>
+      <p className="lede">
+        Compare two saved plans side by side. Use this for A/B planning after duplicating a plan, or for year-over-year
+        tracking across independently saved plans.
+      </p>
+      {notice ? <div className="callout callout--warn">{notice}</div> : null}
+      {summaries === null ? (
+        <div className="skeleton" style={{ height: '8rem' }} aria-label="Loading plans" />
+      ) : summaries.length < 2 ? (
+        <div className="empty-state">
+          <h2>Two plans are needed</h2>
+          <p>Duplicate an existing plan or create another plan before comparing.</p>
+        </div>
+      ) : (
+        <>
+          <div className="card compare-selectors">
+            <label>
+              Plan A
+              <select value={leftId} onChange={(e) => setLeftId(e.target.value)}>
+                {options.map((s) => (
+                  <option key={s.id} value={s.id}>{s.name}</option>
+                ))}
+              </select>
+            </label>
+            <label>
+              Plan B
+              <select value={rightId} onChange={(e) => setRightId(e.target.value)}>
+                {options.map((s) => (
+                  <option key={s.id} value={s.id}>{s.name}</option>
+                ))}
+              </select>
+            </label>
+          </div>
+          {!canCompare ? (
+            <div className="callout callout--info">Choose two different plans to compare.</div>
+          ) : (
+            <div className="year-table-wrap">
+              <table className="year-table compare-table">
+                <thead>
+                  <tr>
+                    <th>Metric</th>
+                    <th>{left.plan.name}</th>
+                    <th>{right.plan.name}</th>
+                    <th>Plan B − Plan A</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr>
+                    <th>Money lasts</th>
+                    <td>{resultLabel(left.view.summary, left.view.result.endYear)}</td>
+                    <td>{resultLabel(right.view.summary, right.view.result.endYear)}</td>
+                    <td>—</td>
+                  </tr>
+                  {rows.map((row) => <MetricRow key={row.label} {...row} />)}
+                </tbody>
+              </table>
+            </div>
+          )}
+        </>
+      )}
+    </section>
+  )
+}

package/src/planner/DisclaimerPage.tsx

@@ -0,0 +1,88 @@
+/** The full disclaimer, linked from the navigation and the plan picker. */
+
+import { Link } from 'react-router-dom'
+
+import { PARAMETER_DATA_AS_OF, PARAMETER_DATA_BASIS } from '@retiregolden/engine/params'
+import { ProvenancePanel } from './ProvenancePanel'
+
+export function DisclaimerPage() {
+  return (
+    <article className="page" style={{ maxWidth: '46rem', margin: '0 auto', textAlign: 'left' }}>
+      <h1>Disclaimer</h1>
+      <p className="lede">Please read this before relying on anything RetireGolden shows you.</p>
+
+      <h2>Educational use only</h2>
+      <p>
+        RetireGolden is an educational modeling tool. It is <strong>not</strong> tax advice, legal advice, investment
+        advice, accounting advice, insurance advice, or medical advice, and nothing it produces creates an
+        advisor–client relationship of any kind. Decisions about retirement, Social Security claiming, Roth
+        conversions, withdrawals, healthcare coverage, or anything else with real-world consequences should be made
+        with qualified professionals who know your full situation.
+      </p>
+
+      <h2>Models are simplifications</h2>
+      <ul>
+        <li>Projections depend entirely on your inputs and assumptions. Small changes in returns, inflation, or longevity produce very different outcomes.</li>
+        <li>Monte Carlo success rates are statistics about a simplified model, not probabilities about your actual life.</li>
+        <li>The tax engine covers common federal rules (brackets, Social Security taxation, capital-gains stacking, RMDs, IRMAA, ACA credits) at planning precision — not return-filing precision. State income tax models each state's brackets, standard deduction, Social Security treatment, and major retirement-income exclusions, with a flat-rate override for corrections; credits, local/city taxes, and income-tested exclusions are simplified or omitted. Many real-world provisions are approximated.</li>
+        <li>Life-expectancy estimates are population statistics with coarse lifestyle adjustments — they say nothing certain about any individual.</li>
+        <li>Historical market data in the bootstrap models is approximate and the past does not predict the future.</li>
+      </ul>
+
+      <h2>Rules change</h2>
+      <p>
+        Tax law, contribution limits, Medicare premiums, ACA subsidies, and Social Security rules change frequently —
+        sometimes retroactively. Parameter tables here are updated on a best-effort basis and may be out of date or
+        wrong. Verify any number that matters against official sources (irs.gov, ssa.gov, medicare.gov,
+        healthcare.gov).
+      </p>
+      <p>
+        <strong>Tax data as of {PARAMETER_DATA_AS_OF}</strong>, reflecting {PARAMETER_DATA_BASIS}. Figures for later
+        years carry these rules forward (so bracket creep is modeled, but scheduled future rate changes are not) until
+        the next refresh.
+      </p>
+
+      <h2>Where the numbers come from</h2>
+      <p>
+        These are the defaults the engine applies. They are summaries at planning precision — see each linked source
+        for the authoritative figures. For the harnesses that check the engine itself against independent
+        implementations, see <Link to="/how-tested">How RetireGolden is tested</Link>.
+      </p>
+      <ProvenancePanel />
+
+      <h2>Your data stays with you</h2>
+      <p>
+        RetireGolden has no server-side storage and no accounts. Everything you enter lives only in this browser
+        (IndexedDB and localStorage) and is never transmitted anywhere. That also means <strong>we cannot recover it</strong>:
+        clearing your browser data, switching devices, or using the "Clear all data" button erases it permanently.
+        Download a plan backup from the planner home if you want to keep or move your plans.
+      </p>
+
+      <h2>No warranty</h2>
+      <p>
+        The software is provided "as is", without warranty of any kind, express or implied, including fitness for a
+        particular purpose. Calculations may contain errors. You bear all responsibility for decisions made using
+        this tool.
+      </p>
+
+      <h2>Software license &amp; third-party notices</h2>
+      <p>
+        RetireGolden is free and open-source software, licensed under the{' '}
+        <a href="https://www.gnu.org/licenses/agpl-3.0.html" target="_blank" rel="noopener noreferrer">
+          GNU Affero General Public License v3.0 (AGPL-3.0)
+        </a>
+        . © 2026 RetireGolden, LLC. "RetireGolden" and the RetireGolden logo are trademarks of RetireGolden, LLC.
+        The source code is available on{' '}
+        <a href="https://github.com/RetireGolden/RetireGolden" target="_blank" rel="noopener noreferrer">
+          GitHub
+        </a>
+        . It bundles third-party packages (React, Recharts, HiGHS-WASM, Zod, and their dependencies) distributed
+        under their respective permissive licenses — see the{' '}
+        <a href="/THIRD-PARTY-NOTICES.txt" target="_blank" rel="noopener noreferrer">
+          full third-party notices
+        </a>
+        .
+      </p>
+    </article>
+  )
+}

package/src/planner/HowTestedPage.tsx

@@ -0,0 +1,159 @@
+/**
+ * "How RetireGolden is tested" (trust-and-transparency-layer, step 5): the
+ * in-app validation story — one auditable ledger, external-oracle golden
+ * suites, the independent-optimizer parity harness, the asset-location
+ * invariance guarantee, and the simplifications stated as plainly as the
+ * strengths. Harness counts are derived from the source tree at build time
+ * (`import.meta.glob` keys), so they cannot go stale.
+ */
+
+import { Link } from 'react-router-dom'
+
+// Sibling-workspace globs (engine, app harness tests) resolve when this file
+// is built inside the RetireGolden monorepo — retiregolden.app's build. In an
+// external consumer of the published package they match nothing (the tarball
+// ships without test files), so the counts degrade to zero rather than lie.
+/** Suites checked against third-party implementations that share no code with RetireGolden. */
+const EXTERNAL_ORACLE_SUITES = Object.keys(
+  import.meta.glob(['../**/*.external.golden.test.ts', '../../../engine/src/**/*.external.golden.test.ts']),
+)
+/** All golden suites (fixed expected-value fixtures), external and internal. */
+const GOLDEN_SUITES = Object.keys(
+  import.meta.glob(['../**/*.golden.test.ts', '../../../engine/src/**/*.golden.test.ts']),
+)
+/** Every automated test file in the source tree (planner-ui + engine + app harness). */
+const ALL_TEST_FILES = Object.keys(
+  import.meta.glob([
+    '../**/*.test.{ts,tsx}',
+    '../../../engine/src/**/*.test.ts',
+    '../../../../app/src/**/*.test.{ts,tsx}',
+  ]),
+)
+
+/** "federalTaxSocialSecurity.external.golden.test.ts" → "federal tax social security". */
+function suiteName(path: string): string {
+  const base = path.split('/').pop()!.replace(/\.external\.golden\.test\.ts$/, '')
+  return base.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase()
+}
+
+// True when built inside the RetireGolden monorepo (retiregolden.app). A
+// build from the published tarball has no test files to count, and a trust
+// page must not report zeros as if the suites didn't exist — so counts and
+// the pinned-suite list degrade to count-free prose plus a pointer at the
+// upstream tree where they are derived.
+const HAS_SUITE_DATA = ALL_TEST_FILES.length > 0
+
+export function HowTestedPage() {
+  return (
+    <article className="page" style={{ maxWidth: '46rem', margin: '0 auto', textAlign: 'left' }}>
+      <h1>How RetireGolden is tested</h1>
+      <p className="lede">
+        Retirement tools notoriously disagree — the same plan can score 60% in one tool and 90% in another, and most
+        tools won't show you why. RetireGolden's answer is to show its work: what the engine computes, what it's checked
+        against, and what it deliberately simplifies.
+      </p>
+
+      <h2>One auditable ledger</h2>
+      <p>
+        Every result — the success rate, the conversion recommendation, the "how much can I spend?" answer — comes from
+        a single year-by-year ledger you can open and read on the Results page (or download as CSV). There is no
+        separate "estimate" engine: Monte Carlo, the optimizer, and the reports all price against the same exact
+        projection. If two numbers in RetireGolden ever disagree, that's a bug, not a methodology difference.
+      </p>
+
+      <h2>Checked against independent implementations</h2>
+      <p>
+        {HAS_SUITE_DATA ? `${EXTERNAL_ORACLE_SUITES.length} external-oracle` : 'External-oracle'} golden suites pin
+        RetireGolden's calculations to third-party references that share no code with it:
+      </p>
+      <ul>
+        <li>
+          <strong>Federal &amp; state taxes</strong> — golden cases cross-checked against independent open tax engines
+          (PolicyEngine-US and PSLmodels Tax-Calculator), covering brackets, Social Security taxability, and
+          capital-gains stacking.
+        </li>
+        <li>
+          <strong>Medicare/IRMAA, ACA, and RMDs</strong> — checked against the published CMS premium tables, the IRS
+          applicable-percentage schedule, and the Pub 590-B life-expectancy tables.
+        </li>
+        <li>
+          <strong>Social Security</strong> — benefit computation and claiming math validated against the SSA's
+          published rules (bend points, actuarial factors, family maximums, survivor limits).
+        </li>
+      </ul>
+      {HAS_SUITE_DATA && (
+        <p className="muted small">
+          Suites currently pinned: {EXTERNAL_ORACLE_SUITES.map(suiteName).join(' · ')}.
+        </p>
+      )}
+      <p>
+        The Roth-conversion optimizer additionally runs through a <strong>parity harness</strong>: a shared fixture
+        matrix is solved both by RetireGolden and by an independent open-source conversion optimizer (pinned version),
+        and both tools' schedules are priced on RetireGolden's own exact ledger. As of July 2026 the harness passes on
+        every fixture, with RetireGolden's schedules ahead on projected after-tax estate. It re-runs on a maintenance
+        cadence.
+      </p>
+
+      <h2>Recommendations are arbitrated, not trusted</h2>
+      <p>
+        No recommendation reaches you straight from a solver. Candidate schedules — including simple strategies like
+        bracket-fill — are re-run through your full projection and ranked in a tournament; the winner must beat the
+        alternatives on the exact ledger, and the "Why this recommendation?" panel on the optimizer page shows you the
+        beaten alternatives and their dollar margins.
+      </p>
+
+      <h2>Asset-location invariance, proven</h2>
+      <p>
+        A known six-figure bug class in conversion tools: quietly assuming Roth dollars are invested more aggressively
+        than traditional dollars, so "conversion benefit" is really a hidden allocation change. RetireGolden holds
+        portfolio-wide asset allocation constant across account types, and a dedicated fixture suite
+        (<code>assetLocationInvariance</code>) proves it: a tax-free conversion between identically-allocated accounts
+        leaves every year's totals identical to the dollar, the entire estate benefit of a conversion is the tax term,
+        and conversion candidates can never smuggle in an allocation change. If you deliberately allocate accounts
+        differently, the engine prices that too — visibly, as your explicit setting.
+      </p>
+
+      <h2>Golden suites and regression gates</h2>
+      <p>
+        {HAS_SUITE_DATA ? (
+          <>
+            {GOLDEN_SUITES.length} golden suites hold fixed expected values for the tax engine, RMDs, Social Security,
+            and full-plan projections, out of {ALL_TEST_FILES.length} automated test files overall.
+          </>
+        ) : (
+          <>
+            Golden suites hold fixed expected values for the tax engine, RMDs, Social Security, and full-plan
+            projections.
+          </>
+        )}{' '}
+        A deterministic case runner replays the whole example-plan library and diffs engine output on every change, so
+        unintended result drift is caught before it ships. New engine features land behind no-op defaults, guarded by
+        "feature-off is byte-identical" regressions.
+      </p>
+      {!HAS_SUITE_DATA && (
+        <p className="muted small">
+          Suite counts and names are derived from the RetireGolden source tree at build time; this build was produced
+          outside that tree, so they aren't shown here. The live suites are public at{' '}
+          <a href="https://github.com/RetireGolden/RetireGolden">github.com/RetireGolden/RetireGolden</a>.
+        </p>
+      )}
+
+      <h2>What RetireGolden deliberately simplifies</h2>
+      <p>Honest scope beats false precision. RetireGolden is planning-grade, not filing-grade:</p>
+      <ul>
+        <li>The optimizer's in-solve model uses documented simplifications (for example, a single long-term-gains rate inside the solve); recommendations are then re-priced and validated on the exact ledger before you see them.</li>
+        <li>Future-year tax parameters beyond published law are stand-ins: current rules carry forward with bracket indexation, but scheduled or speculative future law changes are not modeled.</li>
+        <li>AMT is a planning screen, not a filing computation; per-lot basis and many credit phase-outs are simplified by design.</li>
+        <li>Monte Carlo success rates are statistics about a simplified model of your plan — not probabilities about your actual life.</li>
+      </ul>
+
+      <h2>Where the inputs come from</h2>
+      <p>
+        Every tax and benefit parameter cites its source — see the{' '}
+        <Link to="/disclaimer">full provenance table on the Disclaimer page</Link>. Inside a plan, the assumptions card
+        enumerates every live assumption with its provenance and a copy-export, so you can replicate a run in another
+        tool and see exactly why the answers differ.
+      </p>
+    </article>
+  )
+}

package/src/planner/LiveStatus.tsx

@@ -0,0 +1,15 @@
+/**
+ * A visually hidden ARIA live region. Rendering a new `message` (different text
+ * content) prompts assistive tech to announce it; identical re-renders stay
+ * silent, so it will not double-announce on unrelated re-renders. Keep the
+ * component mounted (render it with an empty message rather than conditionally)
+ * so the region exists before its text first changes — some screen readers skip
+ * the announcement otherwise. Use `assertive` for errors that should interrupt.
+ */
+export function LiveStatus({ message, assertive = false }: { message: string; assertive?: boolean }) {
+  return (
+    <span className="sr-only" role={assertive ? 'alert' : 'status'} aria-live={assertive ? 'assertive' : 'polite'}>
+      {message}
+    </span>
+  )
+}

package/src/planner/LongevityModal.tsx

@@ -0,0 +1,55 @@
+/**
+ * Life-expectancy questionnaire in a modal, seeded from the person's profile.
+ * On completion the wizard's planning age is applied straight to the plan —
+ * the standalone /longevity page is no longer part of the main navigation.
+ */
+
+import { useCallback } from 'react'
+
+import { LongevityWizard } from '../longevity/LongevityWizard'
+import { loadLongevity, loadLongevityPartner } from '../longevity/storage'
+import type { Person } from '@retiregolden/engine/model/plan'
+import { Modal } from './Modal'
+
+export interface LongevityModalProps {
+  person: Person
+  /** 0 = primary slot, 1 = partner slot (matches the questionnaire's storage). */
+  personIndex: number
+  onApply: (planningAge: number) => void
+  onClose: () => void
+}
+
+function ageToday(dob: string): number {
+  const y = Number(dob.slice(0, 4))
+  const m = Number(dob.slice(5, 7))
+  const now = new Date()
+  let age = now.getFullYear() - y
+  if (now.getMonth() + 1 < m) age -= 1
+  return Math.min(110, Math.max(18, age))
+}
+
+export function LongevityModal({ person, personIndex, onApply, onClose }: LongevityModalProps) {
+  const target = personIndex === 0 ? 'primary' : 'partner'
+
+  const handleComplete = useCallback(() => {
+    const saved = personIndex === 0 ? loadLongevity() : loadLongevityPartner()
+    if (saved) {
+      onApply(Math.min(120, Math.max(60, Math.round(saved.result.illustrativePlanningAge))))
+    }
+    onClose()
+  }, [personIndex, onApply, onClose])
+
+  return (
+    <Modal title={`Estimate planning age — ${person.name}`} onClose={onClose} width="40rem">
+      <p className="card-hint">
+        A short questionnaire combining a Social Security period life table with conservative lifestyle adjustments.
+        The result becomes {person.name}'s planning age; you can still override it afterwards.
+      </p>
+      <LongevityWizard
+        initialAnswers={{ age: ageToday(person.dob), sex: person.sex }}
+        storageTarget={target}
+        onComplete={handleComplete}
+      />
+    </Modal>
+  )
+}

package/src/planner/Modal.tsx

@@ -0,0 +1,97 @@
+/** Accessible modal dialog: backdrop + Escape close, focus moved on open. */
+
+import { useEffect, useRef, type ReactNode, type RefObject } from 'react'
+
+export interface ModalProps {
+  title: string
+  onClose: () => void
+  children: ReactNode
+  /** Max width CSS value (default 36rem). */
+  width?: string
+  /** Element to focus when the dialog opens (defaults to the panel itself). */
+  initialFocus?: RefObject<HTMLElement | null>
+}
+
+export function Modal({ title, onClose, children, width, initialFocus }: ModalProps) {
+  const panelRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const previouslyFocused = document.activeElement as HTMLElement | null
+    ;(initialFocus?.current ?? panelRef.current)?.focus()
+
+    const focusable = () =>
+      Array.from(
+        panelRef.current?.querySelectorAll<HTMLElement>(
+          'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
+        ) ?? [],
+      ).filter((el) => el.offsetParent !== null || el === document.activeElement)
+
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        onClose()
+        return
+      }
+      if (e.key !== 'Tab') return
+      // Keep Tab focus cycling within the dialog.
+      const items = focusable()
+      if (items.length === 0) {
+        e.preventDefault()
+        panelRef.current?.focus()
+        return
+      }
+      const first = items[0]!
+      const last = items[items.length - 1]!
+      const active = document.activeElement
+      if (e.shiftKey && (active === first || active === panelRef.current)) {
+        e.preventDefault()
+        last.focus()
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+    window.addEventListener('keydown', onKey)
+    const prevOverflow = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+    return () => {
+      window.removeEventListener('keydown', onKey)
+      document.body.style.overflow = prevOverflow
+      // Return focus to whatever opened the dialog.
+      previouslyFocused?.focus?.()
+    }
+  }, [onClose, initialFocus])
+
+  return (
+    <div className="modal-backdrop" onMouseDown={(e) => e.target === e.currentTarget && onClose()}>
+      <div
+        className="modal-panel"
+        role="dialog"
+        aria-modal="true"
+        aria-label={title}
+        tabIndex={-1}
+        ref={panelRef}
+        style={width ? { maxWidth: width } : undefined}
+      >
+        <div className="modal-head">
+          <h2>{title}</h2>
+          <button type="button" className="btn-ghost modal-close" onClick={onClose} aria-label="Close dialog">
+            <svg
+              viewBox="0 0 24 24"
+              width="16"
+              height="16"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              aria-hidden="true"
+            >
+              <line x1="6" y1="6" x2="18" y2="18" />
+              <line x1="18" y1="6" x2="6" y2="18" />
+            </svg>
+          </button>
+        </div>
+        <div className="modal-body">{children}</div>
+      </div>
+    </div>
+  )
+}