@retiregolden/planner-ui 0.1.0 → 0.3.0

package/src/data/planStoreContext.ts

@@ -0,0 +1,138 @@
+/**
+ * The plan-persistence seam: a host supplies plan storage by implementing
+ * `PlanStore` and wrapping the planner in `<PlanStoreProvider>`; the default
+ * is the browser IndexedDB implementation, so web hosts change nothing.
+ *
+ * The seam is deliberately plan-scoped and storage-dumb:
+ *
+ * - **Documents in, documents out.** `loadPlan` returns the stored plan JSON
+ *   verbatim (any schema version) and the seam layer runs schema migration +
+ *   validation on read — the single code path persisted reads have always
+ *   gone through. `savePlan` receives an already-validated, already-stamped
+ *   `Plan`; a store never re-implements validation.
+ * - **No client/household concepts.** A host that groups plans (per-client
+ *   libraries) binds that identity outside this interface — its adapter maps
+ *   plan ids into whatever structure it keeps.
+ * - **No change feed.** Every list view refetches after its own mutations
+ *   (the pattern the web app has always used), so a subscription mechanism
+ *   is deliberately omitted rather than speculatively bolted on.
+ * - **Library demo records (`example:*` ids) never cross the seam.** They
+ *   are per-device preview UX, not plan data, and stay in the browser store
+ *   regardless of provider; "Save to my plans" is the crossing point, and it
+ *   writes the converted user plan through the seam. The `*Via` operations
+ *   below route by id so callers don't care.
+ */
+
+import { createContext, useContext } from 'react'
+
+import { migratePlanToCurrent, type MigrateResult } from '@retiregolden/engine/model/migrations'
+import type { Plan } from '@retiregolden/engine/model/plan'
+import { isExamplePlanId } from './planOrigin'
+import {
+  checkPlanForSave,
+  cloneAsUserPlan,
+  deletePlan,
+  getPlanRecord,
+  listExampleSummaries,
+  listUserPlanSummaries,
+  loadPlan,
+  putPlanRecord,
+  savePlan,
+  type DuplicatePlanOptions,
+  type SavePlanResult,
+} from './planStore'
+
+/** What a plan list needs to render a row. The seam type carries no origin — every plan in a store is the user's. */
+export interface PlanSummary {
+  id: string
+  name: string
+  updatedAtIso: string
+}
+
+/**
+ * Host-implementable plan storage. Implementations are plain objects; keep
+ * the instance stable (module constant or memoized) — the planner reloads
+ * when the provided store changes identity.
+ */
+export interface PlanStore {
+  /** Summaries of every plan in the store. Order is not significant — the seam sorts by `updatedAtIso`, newest first. */
+  listPlans(): Promise<PlanSummary[]>
+  /** The stored plan document verbatim (any schema version), or `null`/`undefined` when absent. */
+  loadPlan(id: string): Promise<unknown>
+  /** Persist a validated plan. This is the autosave path — it runs on a debounce while the user edits. */
+  savePlan(plan: Plan): Promise<void>
+  deletePlan(id: string): Promise<void>
+}
+
+/**
+ * The browser IndexedDB implementation (data/planStore.ts) — the default
+ * store, and exported so hosts can wrap it. `listPlans` excludes library
+ * demo records: they live in the same database but belong to the example
+ * slots, not the user's plan list.
+ */
+export const indexedDbPlanStore: PlanStore = {
+  listPlans: listUserPlanSummaries,
+  loadPlan: getPlanRecord,
+  savePlan: putPlanRecord,
+  deletePlan,
+}
+
+/** Prefer `<PlanStoreProvider>` (data/PlanStoreProvider.tsx); the raw context is exported for it, not for general use. */
+export const PlanStoreContext = createContext<PlanStore>(indexedDbPlanStore)
+
+export function usePlanStore(): PlanStore {
+  return useContext(PlanStoreContext)
+}
+
+/*
+ * Store-generic operations. Components read the store from context and call
+ * these; each routes `example:*` ids to the browser store (demo records are
+ * device-local by design) and everything else through the given store, with
+ * migration/validation applied here so hosts stay storage-dumb.
+ */
+
+/** The store's plan summaries, newest first. */
+export async function listPlansVia(store: PlanStore): Promise<PlanSummary[]> {
+  const summaries = await store.listPlans()
+  return summaries.slice().sort((a, b) => b.updatedAtIso.localeCompare(a.updatedAtIso))
+}
+
+/** Loads, migrates, and validates a plan. Missing records surface as `{ ok: false, reason: 'not_object' }`, exactly like the browser store. */
+export async function loadPlanVia(store: PlanStore, id: string): Promise<MigrateResult> {
+  if (isExamplePlanId(id)) return loadPlan(id)
+  const raw = await store.loadPlan(id)
+  if (raw === undefined || raw === null) return { ok: false, reason: 'not_object' }
+  return migratePlanToCurrent(raw)
+}
+
+/** Validates and writes a plan, bumping `updatedAtIso`. */
+export async function savePlanVia(store: PlanStore, plan: Plan, now: () => Date = () => new Date()): Promise<SavePlanResult> {
+  if (isExamplePlanId(plan.id)) return savePlan(plan, now)
+  const checked = checkPlanForSave(plan, now)
+  if (!checked.ok) return checked
+  await store.savePlan(checked.plan)
+  return checked
+}
+
+export async function deletePlanVia(store: PlanStore, id: string): Promise<void> {
+  if (isExamplePlanId(id)) return deletePlan(id)
+  return store.deletePlan(id)
+}
+
+export async function duplicatePlanVia(store: PlanStore, id: string, opts: DuplicatePlanOptions = {}): Promise<SavePlanResult> {
+  let source = opts.source
+  if (!source) {
+    const loaded = await loadPlanVia(store, id)
+    if (!loaded.ok) return { ok: false, issues: [`Could not load source plan (${loaded.reason}).`] }
+    source = loaded.plan
+  }
+  const { clone, nowIso } = cloneAsUserPlan(source, opts)
+  // Duplicates are always user plans (fresh uuid), so this writes through the store.
+  return savePlanVia(store, clone, () => new Date(nowIso))
+}
+
+/** Every id the import path must not collide with: the store's plans plus the browser's demo slots. */
+export async function listKnownPlanIdsVia(store: PlanStore): Promise<Set<string>> {
+  const [stored, demos] = await Promise.all([store.listPlans(), listExampleSummaries()])
+  return new Set([...stored.map((s) => s.id), ...demos.map((s) => s.id)])
+}

package/src/data/v2Backup.ts

@@ -1,86 +1,37 @@
 /**
  * v2 JSON backup envelope — ports the retired v1 pattern (versioned envelope,
  * size cap, validate-before-replace) to multi-plan v2 data.
- * Plans inside the envelope carry their own schemaVersion and are individually
- * migrated on import, so old backups stay restorable forever.
+ *
+ * The pure envelope logic lives in `planFormat.ts` (published as the stable
+ * `@retiregolden/planner-ui/plan-format` subpath) and is re-exported here so
+ * existing import sites keep working; this module keeps the storage-aware
+ * import normalization.
  */
 
-import { migratePlanToCurrent } from '@retiregolden/engine/model/migrations'
 import type { Plan } from '@retiregolden/engine/model/plan'
 import { isExamplePlanId } from './planOrigin'
 import { listPlanSummaries } from './planStore'
 
-export const V2_BACKUP_KIND = 'retiregolden.v2.backup'
-/** Legacy envelope kinds from before the RetireGolden rebrand — still accepted on import. */
-export const LEGACY_V2_BACKUP_KIND = 'retirecalc.v2.backup'
-export const RETIREMINT_V2_BACKUP_KIND = 'retiremint.v2.backup'
-export const V2_BACKUP_VERSION = 1
-/** Generous cap; primarily guards against importing the wrong (huge) file. */
-export const MAX_BACKUP_JSON_CHARS = 10_000_000
-
-export interface V2BackupEnvelope {
-  kind: typeof V2_BACKUP_KIND
-  backupVersion: typeof V2_BACKUP_VERSION
-  exportedAtIso: string
-  plans: unknown[]
-}
-
-export function serializeV2Backup(plans: Plan[], now: () => Date = () => new Date()): string {
-  const envelope: V2BackupEnvelope = {
-    kind: V2_BACKUP_KIND,
-    backupVersion: V2_BACKUP_VERSION,
-    exportedAtIso: now().toISOString(),
-    plans,
-  }
-  return JSON.stringify(envelope, null, 2)
-}
-
-export type ParseV2BackupResult =
-  | { ok: true; plans: Plan[]; warnings: string[] }
-  | { ok: false; reason: 'too_large' | 'not_json' | 'wrong_kind' | 'unsupported_version' | 'no_valid_plans' }
-
-export function parseV2Backup(json: string): ParseV2BackupResult {
-  if (json.length > MAX_BACKUP_JSON_CHARS) return { ok: false, reason: 'too_large' }
-
-  let raw: unknown
-  try {
-    raw = JSON.parse(json)
-  } catch {
-    return { ok: false, reason: 'not_json' }
-  }
-  if (typeof raw !== 'object' || raw === null) return { ok: false, reason: 'wrong_kind' }
-  const env = raw as { kind?: string; backupVersion?: number; plans?: unknown }
-  if (
-    (env.kind !== V2_BACKUP_KIND &&
-      env.kind !== RETIREMINT_V2_BACKUP_KIND &&
-      env.kind !== LEGACY_V2_BACKUP_KIND) ||
-    !Array.isArray(env.plans)
-  ) {
-    return { ok: false, reason: 'wrong_kind' }
-  }
-  if (env.backupVersion !== V2_BACKUP_VERSION) return { ok: false, reason: 'unsupported_version' }
-
-  const plans: Plan[] = []
-  const warnings: string[] = []
-  env.plans.forEach((rawPlan, i) => {
-    const result = migratePlanToCurrent(rawPlan)
-    if (result.ok) {
-      plans.push(result.plan)
-    } else {
-      warnings.push(`plan ${i + 1}: skipped (${result.reason})`)
-    }
-  })
-  if (plans.length === 0) return { ok: false, reason: 'no_valid_plans' }
-  return { ok: true, plans, warnings }
-}
+export {
+  LEGACY_V2_BACKUP_KIND,
+  MAX_BACKUP_JSON_CHARS,
+  RETIREMINT_V2_BACKUP_KIND,
+  V2_BACKUP_KIND,
+  V2_BACKUP_VERSION,
+  parseV2Backup,
+  serializeV2Backup,
+  type ParseV2BackupResult,
+  type V2BackupEnvelope,
+} from './planFormat'
 
 /**
  * On import, demos become user plans and reserved `example:*` ids are rekeyed
- * so they cannot collide with library demo slots.
+ * so they cannot collide with library demo slots. `existingIds` is every id
+ * already taken (host store plans + browser demo slots — see
+ * `listKnownPlanIdsVia`); when omitted, the browser store supplies them.
  */
-export async function normalizePlansForImport(plans: Plan[]): Promise<Plan[]> {
-  const existing = new Set((await listPlanSummaries()).map((s) => s.id))
-  const used = new Set(existing)
+export async function normalizePlansForImport(plans: Plan[], existingIds?: Iterable<string>): Promise<Plan[]> {
+  const used = new Set(existingIds ?? (await listPlanSummaries()).map((s) => s.id))
   const normalized: Plan[] = []
 
   for (const plan of plans) {

package/src/import/ImportPage.tsx

@@ -11,7 +11,7 @@
 import { useRef, useState } from 'react'
 import { Link, useNavigate } from 'react-router-dom'
 
-import { savePlan } from '../data/planStore'
+import { savePlanVia, usePlanStore } from '../data/planStoreContext'
 import type { Plan } from '@retiregolden/engine/model/plan'
 import { DateField, MoneyField, SelectField } from '../planner/fields'
 import { US_STATES } from '../planner/usStates'
@@ -82,6 +82,7 @@ const EMPTY_1040: TenFortyInputs = {
 
 export function ImportPage() {
   const navigate = useNavigate()
+  const store = usePlanStore()
   const [source, setSource] = useState<SourceId | null>(null)
   const [error, setError] = useState<string | null>(null)
   const [draft, setDraft] = useState<Draft | null>(null)
@@ -151,7 +152,7 @@ export function ImportPage() {
 
   const saveAndOpen = async () => {
     if (!draft) return
-    const r = await savePlan(draft.plan)
+    const r = await savePlanVia(store, draft.plan)
     if (r.ok) navigate(`/plan/${r.plan.id}`)
     else setError(`Could not save the draft plan: ${r.issues.join('; ')}`)
   }

package/src/index.ts

@@ -14,3 +14,26 @@
  */
 export { App as PlannerApp, type PlannerAppProps } from './App.tsx'
 export type { ReportBranding } from './report/reportHtml'
+
+// The plan-persistence seam: implement `PlanStore` and wrap the planner in
+// `<PlanStoreProvider>` (or pass `planStore` to `<PlannerApp/>`) to supply
+// host storage; omit both and plans persist in the browser via IndexedDB.
+export { PlanStoreProvider } from './data/PlanStoreProvider.tsx'
+export {
+  indexedDbPlanStore,
+  type PlanStore,
+  type PlanSummary,
+} from './data/planStoreContext.ts'
+
+// Route-level exports: mount a subset of the planner under the host's own
+// router (react-router v7 route-object arrays). `<PlannerApp/>` remains the
+// batteries-included composition of all three groups plus the web chrome.
+export {
+  plannerContentRoutes,
+  plannerHomeRoutes,
+  plannerWorkspaceRoutes,
+} from './routes/groups.tsx'
+
+// Report branding for hosts that mount route groups directly; `<PlannerApp/>`
+// hosts use the `reportBranding` prop instead.
+export { ReportBrandingProvider } from './report/ReportBrandingProvider.tsx'

package/src/planner/ComparePlansPage.tsx

@@ -7,7 +7,7 @@
 import { useEffect, useMemo, useState } from 'react'
 import { Link } from 'react-router-dom'
 
-import { listUserPlanSummaries, loadPlan, type PlanSummary } from '../data/planStore'
+import { listPlansVia, loadPlanVia, usePlanStore, type PlanSummary } from '../data/planStoreContext'
 import type { Plan } from '@retiregolden/engine/model/plan'
 import type { ProjectionSummary } from '@retiregolden/engine/projection/compare'
 import { fmtMoneyCompact } from './format'
@@ -65,6 +65,7 @@ function MetricRow({
 }
 
 export function ComparePlansPage() {
+  const store = usePlanStore()
   const [summaries, setSummaries] = useState<PlanSummary[] | null>(null)
   const [leftId, setLeftId] = useState('')
   const [rightId, setRightId] = useState('')
@@ -73,12 +74,12 @@ export function ComparePlansPage() {
   const [notice, setNotice] = useState<string | null>(null)
 
   useEffect(() => {
-    void listUserPlanSummaries().then((items) => {
+    void listPlansVia(store).then((items) => {
       setSummaries(items)
       setLeftId(items[0]?.id ?? '')
       setRightId(items.find((p) => p.id !== items[0]?.id)?.id ?? '')
     })
-  }, [])
+  }, [store])
 
   useEffect(() => {
     let cancelled = false
@@ -87,7 +88,7 @@ export function ComparePlansPage() {
         setter(null)
         return
       }
-      const r = await loadPlan(id)
+      const r = await loadPlanVia(store, id)
       if (cancelled) return
       if (r.ok) setter({ plan: r.plan, view: projectPlan(r.plan) })
       else {
@@ -100,7 +101,7 @@ export function ComparePlansPage() {
     return () => {
       cancelled = true
     }
-  }, [leftId, rightId])
+  }, [leftId, rightId, store])
 
   const options = summaries ?? []
   const canCompare = left !== null && right !== null && left.plan.id !== right.plan.id

package/src/planner/PlanContext.tsx

@@ -10,7 +10,7 @@ import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react'
 import { Link } from 'react-router-dom'
 
 import { parsePlan, type Plan } from '@retiregolden/engine/model/plan'
-import { loadPlan, savePlan } from '../data/planStore'
+import { loadPlanVia, savePlanVia, usePlanStore } from '../data/planStoreContext'
 import { EXAMPLE_PLAN_ID_PREFIX, isExamplePlanId } from '../data/planOrigin'
 import { getExampleById } from './examples/registry'
 import { saveFreshDemo } from './examples/loadExample'
@@ -24,6 +24,7 @@ const AUTOSAVE_MS = 600
  * asynchronously.
  */
 export function PlanProvider({ planId, children }: { planId: string; children: ReactNode }) {
+  const store = usePlanStore()
   const [plan, setPlan] = useState<Plan | null>(null)
   const [loadError, setLoadError] = useState<string | null>(null)
   const [saveState, setSaveState] = useState<SaveState>('loading')
@@ -39,7 +40,7 @@ export function PlanProvider({ planId, children }: { planId: string; children: R
       setSaveState('saved')
     }
     void (async () => {
-      const r = await loadPlan(planId)
+      const r = await loadPlanVia(store, planId)
       if (cancelled) return
       if (r.ok) {
         adopt(r.plan)
@@ -68,21 +69,21 @@ export function PlanProvider({ planId, children }: { planId: string; children: R
     return () => {
       cancelled = true
     }
-  }, [planId])
+  }, [planId, store])
 
-  // savePlan resolves { ok: false } on validation failure, but the IndexedDB
+  // savePlanVia resolves { ok: false } on validation failure, but the store
   // write itself can still reject (quota, private mode) — degrade to 'error'
   // instead of leaving 'saving' stuck plus an unhandled rejection.
   const runSave = useCallback((toSave: Plan) => {
     setSaveState('saving')
-    void savePlan(toSave)
+    void savePlanVia(store, toSave)
       .then((r) => {
         setSaveState(r.ok ? 'saved' : 'error')
       })
       .catch(() => {
         setSaveState('error')
       })
-  }, [])
+  }, [store])
 
   const scheduleSave = useCallback(() => {
     if (timer.current !== null) window.clearTimeout(timer.current)

package/src/planner/PlanWorkspace.tsx

@@ -7,7 +7,7 @@
 import { useEffect } from 'react'
 import { Link, NavLink, Outlet, useLocation, useNavigate, useParams } from 'react-router-dom'
 
-import { duplicatePlan } from '../data/planStore'
+import { duplicatePlanVia, usePlanStore } from '../data/planStoreContext'
 import { DEFAULT_PATH_COUNT } from '../mc/pool'
 import { useDialogs } from './dialogs'
 import { isPlanIncomplete } from './planCompleteness'
@@ -177,6 +177,7 @@ function PlanName() {
 
 function WorkspaceInner() {
   const { plan, discardPendingSave } = usePlan()
+  const store = usePlanStore()
   const navigate = useNavigate()
   const location = useLocation()
   const { prompt, alert, dialogs } = useDialogs()
@@ -205,7 +206,7 @@ function WorkspaceInner() {
     })
     if (name === null) return
     if (plan.origin === 'example') discardPendingSave()
-    const r = await duplicatePlan(plan.id, { name, source: plan })
+    const r = await duplicatePlanVia(store, plan.id, { name, source: plan })
     if (r.ok) navigate(`/plan/${r.plan.id}/results`)
     else await alert({ title: 'Duplicate plan', body: `Could not duplicate this plan: ${r.issues.join('; ')}` })
   }

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/examples/ExampleLibrary.tsx

@@ -10,7 +10,10 @@ import { useDialogs } from '../dialogs'
 import { EXAMPLE_PLANS, type ExamplePlan } from './registry'
 import { openExampleExisting, openExampleFresh, prepareExampleOpen, saveExampleToMyPlans } from './loadExample'
 import { EXAMPLE_LOAD_FRESH_DESC, EXAMPLE_OPEN_EXISTING_DESC } from './exampleCopy'
+// Demo records are browser-local by design, so this loadPlan stays on the
+// browser store; only the "Save to my plans" conversion crosses the seam.
 import { loadPlan } from '../../data/planStore'
+import { usePlanStore } from '../../data/planStoreContext'
 import { readLocal, STORAGE_KEYS, writeLocal } from '../../data/localStore'
 
 /**
@@ -30,6 +33,7 @@ function householdFacts(example: ExamplePlan): string {
 
 function ExampleCard({ example, onNotice }: { example: ExamplePlan; onNotice: (msg: string) => void }) {
   const navigate = useNavigate()
+  const store = usePlanStore()
   const [busy, setBusy] = useState(false)
   const { choice, dialogs } = useDialogs()
 
@@ -94,7 +98,7 @@ function ExampleCard({ example, onNotice }: { example: ExamplePlan; onNotice: (m
         onNotice('Could not load the example to save.')
         return
       }
-      const converted = await saveExampleToMyPlans(loaded.plan)
+      const converted = await saveExampleToMyPlans(loaded.plan, { store })
       if (converted.ok) {
         onNotice(`"${example.title}" saved to Your plans.`)
         navigate(`/plan/${converted.plan.id}/results`)

package/src/planner/examples/ExamplePreviewBanner.tsx

@@ -6,6 +6,7 @@ import { useState } from 'react'
 import { useNavigate } from 'react-router-dom'
 
 import { LearnLink } from '../../learn/LearnLink'
+import { usePlanStore } from '../../data/planStoreContext'
 import { useDialogs } from '../dialogs'
 import { usePlan } from '../planContextCore'
 import { getExampleById } from './registry'
@@ -14,6 +15,7 @@ import { EXAMPLE_BANNER_PERSISTENCE } from './exampleCopy'
 
 export function ExamplePreviewBanner() {
   const { plan, discardPendingSave } = usePlan()
+  const store = usePlanStore()
   const navigate = useNavigate()
   const [busy, setBusy] = useState(false)
   const { alert, dialogs } = useDialogs()
@@ -29,7 +31,7 @@ export function ExamplePreviewBanner() {
     setBusy(true)
     try {
       discardPendingSave()
-      const r = await saveExampleToMyPlans(plan)
+      const r = await saveExampleToMyPlans(plan, { store })
       if (r.ok) navigate(`/plan/${r.plan.id}/results`)
       else await alert({ title: 'Save example', body: `Could not save: ${r.issues.join('; ')}` })
     } finally {