@retiregolden/planner-ui 0.2.0 → 0.3.0

package/README.md

@@ -130,6 +130,14 @@ The supported product API is:
   may extend the envelope with their own top-level keys and the file still
   imports everywhere. The module is browser-free (no IndexedDB/DOM) and safe
   to run in Node — e.g. an Electron main process assembling backups;
+- the **`./report-model` subpath** — the edition-neutral report data model:
+  `ReportModel` and its block types, `buildReportModel`, the stable
+  `REPORT_BLOCK_IDS`, `serializeReportModel` (deterministic JSON), and the
+  CSV table helpers (`chartDataCsv`, `yearLedgerCsv`, `accountsCsv`). See
+  "Report model" under "Hosting the workspace". Like `./plan-format`, its
+  exported names, signatures, and block ids only change with a semver-major
+  release (new blocks/fields may be added in minors), and the module is
+  browser-free and safe to run in Node;
 - `./index.css`.
 
 The exports map also exposes wildcard `./*.ts` subpaths
@@ -238,6 +246,52 @@ export that speaks the same envelope as the web app's backup files:
 import { serializeV2Backup, parseV2Backup } from '@retiregolden/planner-ui/plan-format'
 ```
 
+### Report model
+
+Reports are data before they are documents. The stable `./report-model`
+subpath exposes the edition-neutral `ReportModel`: everything a report needs
+— headline metrics, household snapshot, accounts, income sources,
+assumptions, modeled findings with their evidence, the year-by-year ledger,
+chart series, parameter sources, disclosures, and provenance (parameter pack
+years, data vintage, generation timestamp) — assembled from an
+already-computed projection, independent of any DOM, theme, or layout:
+
+```ts
+import { buildReportModel, serializeReportModel } from '@retiregolden/planner-ui/report-model'
+
+const model = buildReportModel({ plan, result, summary, startYear })
+const json = serializeReportModel(model) // deterministic: same input, same bytes
+```
+
+Engine-computed dollar figures are carried as **whole nominal dollars** — the
+precision every report presents, and the same whole-dollar discipline as the
+repo's case-runner manifests. (Raw engine floats can differ in the last digit
+across platforms' math libraries, which would make serialized models and
+golden fixtures machine-dependent.)
+
+Every block carries a stable id from `REPORT_BLOCK_IDS`; hosts building their
+own renderers or packet templates should key layout off those ids and warn on
+ids they don't recognize rather than dropping content. The web app's own
+downloaded report is rendered from this same model
+(`buildStandaloneReportHtml` assembles it internally), so a host renderer and
+the standard report can never disagree about the underlying numbers. Golden
+JSON fixtures for the reference cases are committed under
+`src/report/goldens/` and gate changes to the serialized contract.
+
+Boundary notes for hosts (see the decision-support posture in the upstream
+repo): the `modeled-findings` block is calculation evidence attributed to the
+user's selected objective — render it as modeled results, not as advice
+authored by the software. The `advisor-recommendations` block is
+host-authored professional content: `buildReportModel` copies it verbatim
+from its input and never populates it on its own, and renderers must keep it
+visibly attributed to the professional. The `disclosures` block and the
+household `incompleteData` flag are caveats a rendering must keep visible:
+`incompleteData` marks a plan that cannot fund spending yet (no income
+sources, nothing funded), and renderers should surface it as a missing-data
+warning instead of presenting depletion as a funded plan's failure — the
+standard report renders this caveat, and the in-app Results page suppresses
+verdict framing for such plans.
+
 ### Report branding
 
 Downloaded HTML reports (Results, Report, and Optimizer pages) can carry the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retiregolden/planner-ui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The RetireGolden planner React UI: plan picker, planner workspace, results/Monte Carlo/optimizer pages, import wizard, Learning Center, and report export — the full planner tree a host app composes inside its own router. Ships TypeScript source and requires a Vite-class bundler.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -25,6 +25,7 @@
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
+    "!src/report/goldens",
     "LICENSE",
     "README.md"
   ],
@@ -32,6 +33,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./plan-format": "./src/data/planFormat.ts",
+    "./report-model": "./src/report/reportModel.ts",
     "./index.css": "./src/index.css",
     "./*": "./src/*.ts",
     "./package.json": "./package.json"

package/src/planner/ResultsPage.tsx

@@ -36,6 +36,7 @@ import { useProjection } from './useProjection'
 import { BucketLensCard } from './BucketLensCard'
 import { FundedRatioCard } from './sections/IncomeFloorSection'
 import { chartTooltipStyle } from './chartStyle'
+import { NonZeroTooltipContent } from './chartTooltip'
 import { frameH } from './chartFrame'
 import { useMcSuccessRate } from './useMcSuccessRate'
 
@@ -116,6 +117,10 @@ const tooltipProps = {
   wrapperStyle: { zIndex: 2 },
 } as const
 
+// Stacked charts (6–8 series) hide ~$0 rows in the tooltip via content, never
+// by nulling zeros in the data — see NonZeroTooltipContent.
+const stackTooltipProps = { ...tooltipProps, content: NonZeroTooltipContent } as const
+
 /** "1,000" — keeps verdict copy in sync if the default path count changes. */
 const PATH_COUNT_LABEL = DEFAULT_PATH_COUNT.toLocaleString()
 
@@ -231,14 +236,7 @@ export function ResultsPage() {
         const nominalFiTarget = view.summary.fiNumber * Math.pow(1 + plan.assumptions.inflationPct / 100, y.year - view.startYear)
         return {
           year: y.year,
-          // Zero balances render as null so empty categories stay out of the
-          // tooltip (an "HSA: $0" row is noise in a six-series stack).
-          ...Object.fromEntries(
-            CATEGORIES.map((c) => {
-              const v = adj(y.year, cats[c])
-              return [c, v > 0.5 ? v : null]
-            }),
-          ),
+          ...Object.fromEntries(CATEGORIES.map((c) => [c, adj(y.year, cats[c])])),
           income: adj(y.year, y.incomes.total),
           spending: adj(y.year, y.expenses.total + y.tax + y.penalties),
           tax: adj(y.year, y.tax),
@@ -251,22 +249,18 @@ export function ResultsPage() {
     [view, plan, adj],
   )
 
-  // Zero series values render as null so the tooltip (filterNull) skips them —
-  // a stack of 6–8 series otherwise lists every "$0" row as noise.
-  const orNull = (v: number) => (v > 0.5 ? v : null)
-
   const incomeRows = useMemo(
     () =>
       view.result.years.map((y) => ({
         year: y.year,
-        wages: orNull(adj(y.year, y.incomes.wages)),
-        socialSecurity: orNull(adj(y.year, y.incomes.socialSecurity)),
-        pension: orNull(adj(y.year, y.incomes.pension)),
-        annuity: orNull(adj(y.year, y.incomes.annuity)),
-        tipsLadder: orNull(adj(y.year, y.incomes.tipsLadder)),
-        recurring: orNull(adj(y.year, y.incomes.recurring)),
-        oneTime: orNull(adj(y.year, y.incomes.oneTime)),
-        taxableYield: orNull(adj(y.year, y.incomes.taxableYield)),
+        wages: adj(y.year, y.incomes.wages),
+        socialSecurity: adj(y.year, y.incomes.socialSecurity),
+        pension: adj(y.year, y.incomes.pension),
+        annuity: adj(y.year, y.incomes.annuity),
+        tipsLadder: adj(y.year, y.incomes.tipsLadder),
+        recurring: adj(y.year, y.incomes.recurring),
+        oneTime: adj(y.year, y.incomes.oneTime),
+        taxableYield: adj(y.year, y.incomes.taxableYield),
       })),
     [view, adj],
   )
@@ -275,14 +269,14 @@ export function ResultsPage() {
     () =>
       view.result.years.map((y) => ({
         year: y.year,
-        base: orNull(adj(y.year, y.expenses.baseSpending)),
-        healthcare: orNull(adj(y.year, y.expenses.healthcare)),
-        property: orNull(adj(y.year, y.expenses.propertyCosts)),
-        debt: orNull(adj(y.year, y.expenses.debtService)),
-        insurance: orNull(adj(y.year, y.expenses.insurancePremiums)),
-        care: orNull(adj(y.year, Math.max(0, y.expenses.careCost - y.expenses.ltcBenefit))),
-        goals: orNull(adj(y.year, y.expenses.oneTimeGoals)),
-        taxes: orNull(adj(y.year, y.tax + y.penalties)),
+        base: adj(y.year, y.expenses.baseSpending),
+        healthcare: adj(y.year, y.expenses.healthcare),
+        property: adj(y.year, y.expenses.propertyCosts),
+        debt: adj(y.year, y.expenses.debtService),
+        insurance: adj(y.year, y.expenses.insurancePremiums),
+        care: adj(y.year, Math.max(0, y.expenses.careCost - y.expenses.ltcBenefit)),
+        goals: adj(y.year, y.expenses.oneTimeGoals),
+        taxes: adj(y.year, y.tax + y.penalties),
       })),
     [view, adj],
   )
@@ -535,7 +529,7 @@ export function ResultsPage() {
               {view.summary.depletionYear !== null ? (
                 <ReferenceLine x={view.summary.depletionYear} stroke="var(--bad)" strokeDasharray="4 4" label={{ value: 'depleted', fill: 'var(--bad)', fontSize: 12 }} />
               ) : null}
-              <Tooltip {...tooltipProps} />
+              <Tooltip {...stackTooltipProps} />
             </AreaChart>
           </ResponsiveContainer>
         </div>
@@ -591,7 +585,7 @@ export function ResultsPage() {
               {INCOME_SOURCES.map((s) => (
                 <Bar key={s.key} dataKey={s.key} stackId="inc" name={s.label} fill={s.color} />
               ))}
-              <Tooltip {...tooltipProps} />
+              <Tooltip {...stackTooltipProps} />
             </BarChart>
           </ResponsiveContainer>
         </div>
@@ -620,7 +614,7 @@ export function ResultsPage() {
               {EXPENSE_CATEGORIES.map((c) => (
                 <Bar key={c.key} dataKey={c.key} stackId="exp" name={c.label} fill={c.color} />
               ))}
-              <Tooltip {...tooltipProps} />
+              <Tooltip {...stackTooltipProps} />
             </BarChart>
           </ResponsiveContainer>
         </div>

package/src/planner/SurvivalPercentileModal.tsx

@@ -113,7 +113,7 @@ export function SurvivalPercentileModal({ person, personIndex, partner, onApply,
       <div className="form-grid">
         <SelectField
           label="Chance of reaching that age"
-          help="The survival probability the planning age is anchored to. Planning to the 25th percentile means only a 1-in-4 chance of outliving the plan horizon — the usual prudent recommendation. The median (50%) is a coin flip; 10% is conservative."
+          help="The survival probability the planning age is anchored to. Planning to the 25th percentile means only a 1-in-4 chance of outliving the plan horizon — a common prudent convention. The median (50%) is a coin flip; 10% is conservative."
           value={pct}
           options={PCT_OPTIONS}
           onCommit={(v) => setPct(v as '50' | '25' | '10')}

package/src/planner/chartTooltip.tsx

@@ -0,0 +1,18 @@
+/**
+ * Default tooltip content, minus ~$0 rows. For stacked charts with many series
+ * this keeps "HSA: $0" noise out of the tooltip. Filter here, not by nulling
+ * zeros in the data: a null in a stacked Area breaks that series' polygon while
+ * the series above still ramp their baseline across the gap, punching
+ * background-colored wedges into the stack.
+ */
+
+import { DefaultTooltipContent, type TooltipContentProps } from 'recharts'
+
+export function NonZeroTooltipContent(props: TooltipContentProps) {
+  const payload = props.payload?.filter((entry) => typeof entry.value === 'number' && entry.value > 0.5)
+  // Recharts gates tooltip visibility on the unfiltered payload, so when every
+  // series is ~$0 (e.g. post-depletion years) render nothing rather than a
+  // floating card holding only the year label.
+  if (!payload || payload.length === 0) return null
+  return <DefaultTooltipContent {...props} payload={payload} />
+}

package/src/planner/insights/InsightCardView.tsx

@@ -119,7 +119,7 @@ export function InsightCardView({ card, onDismiss }: { card: InsightCard; onDism
               }
             }
           } else {
-            setPreviewError(`This suggestion can't be applied to your plan: ${applied.issues.join('; ')}`)
+            setPreviewError(`This insight can't be applied to your plan: ${applied.issues.join('; ')}`)
           }
         }
       } catch (err) {
@@ -136,7 +136,7 @@ export function InsightCardView({ card, onDismiss }: { card: InsightCard; onDism
     if (action.kind !== 'preview-scenario') return
     const applied = applyScenarioPatch(plan, action.patch)
     if (!applied.ok) {
-      setPreviewError(`This suggestion can't be applied to your plan: ${applied.issues.join('; ')}`)
+      setPreviewError(`This insight can't be applied to your plan: ${applied.issues.join('; ')}`)
       return
     }
     const name = uniqueScenarioName(action.scenarioName, plan)
@@ -198,8 +198,8 @@ export function InsightCardView({ card, onDismiss }: { card: InsightCard; onDism
         type="button"
         className="btn-ghost insight-dismiss"
         onClick={onDismiss}
-        aria-label="Dismiss this recommendation"
-        title="Dismiss this recommendation"
+        aria-label="Dismiss this insight"
+        title="Dismiss this insight"
       >
         <svg
           viewBox="0 0 24 24"
@@ -319,7 +319,7 @@ export function InsightCardView({ card, onDismiss }: { card: InsightCard; onDism
             </>
           )}
           {card.action.kind === 'advisory' && (
-            <span className="insight-advisory-note">Advisory only</span>
+            <span className="insight-advisory-note">Informational only</span>
           )}
           {card.action.kind === 'apply-toggle' && (
             <>

package/src/planner/insights/InsightsPage.tsx

@@ -102,12 +102,13 @@ export function InsightsPage() {
     <section>
       <LiveStatus message={liveMessage} />
       <div className="card">
-        <h2>Insights & Recommendations</h2>
+        <h2>Insights</h2>
         <p className="card-hint">
-          RetireGolden scans your plan to identify personalized planning opportunities. These recommendations update live as you edit.
+          RetireGolden scans your plan for modeled opportunities worth comparing. These findings update live as you
+          edit, and each one can be previewed as a scenario before anything in your plan changes.
         </p>
         <div className="callout callout--info">
-          <strong>Educational only.</strong> These suggestions are for educational purposes based on the rules and assumptions modeled. They do not constitute financial, tax, or legal advice.
+          <strong>Educational only.</strong> These findings are for educational purposes based on the rules and assumptions modeled. They do not constitute financial, tax, or legal advice.
         </div>
       </div>
 
@@ -115,7 +116,7 @@ export function InsightsPage() {
         <div className="card">
           <h2>Roth & Tax Optimizer</h2>
           <p className="card-hint">
-            Compare candidate Roth-conversion schedules on your full year-by-year projection and see the best result found for your plan.
+            Compare candidate Roth-conversion schedules on your full year-by-year projection, ranked by the objective you select.
           </p>
           <Link to={`/plan/${plan.id}/optimize`} className="btn btn-primary btn-small">
             Run optimizer →
@@ -126,7 +127,7 @@ export function InsightsPage() {
           <div className="card">
             <h2>Social Security Optimizer</h2>
             <p className="card-hint">
-              Analyze every claiming age combination side-by-side to find the schedule that maximizes your ending estate.
+              Run every claiming-age combination through your full plan and rank them by the objective you choose.
             </p>
             <Link to={`/plan/${plan.id}/social-security-analysis`} className="btn btn-secondary btn-small">
               Run SS sweep →

package/src/planner/marketModelPicker.ts

@@ -41,7 +41,7 @@ export interface ModelPreset {
 export const MODEL_PRESETS: ReadonlyArray<ModelPreset> = [
   {
     id: 'smooth',
-    label: 'Smooth randomness (recommended)',
+    label: 'Smooth randomness (default)',
     description: 'Each year varies around your expected return, like a bell curve.',
     kind: 'lognormal',
   },