@retiregolden/planner-ui 0.1.0 → 0.2.0

package/README.md

@@ -115,13 +115,129 @@ resolve against the app bundle, not the filesystem root.
 
 ### Published API surface
 
-The supported product API is the root export (`PlannerApp`) plus
-`./index.css`. The exports map also exposes wildcard `./*.ts` subpaths
+The supported product API is:
+
+- the **root export** — `PlannerApp`, the plan-persistence seam
+  (`PlanStore`, `PlanSummary`, `PlanStoreProvider`, `indexedDbPlanStore`),
+  the route groups (`plannerWorkspaceRoutes`, `plannerContentRoutes`,
+  `plannerHomeRoutes`), and `ReportBrandingProvider` — see "Hosting the
+  workspace" below;
+- the **`./plan-format` subpath** — `serializeV2Backup`, `parseV2Backup`,
+  the envelope types, and the kind/version constants. This is the plan
+  interchange format (the same file the web app's backup download produces);
+  its exported names, signatures, and envelope contract only change with a
+  semver-major release. The parser ignores unknown envelope fields, so hosts
+  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;
+- `./index.css`.
+
+The exports map also exposes wildcard `./*.ts` subpaths
 (e.g. `./report/reportHtml`) — these exist for the upstream repo's own test
 and case-runner harnesses, are not covered by any stability promise, and may
 move or change in any release. If a host needs one of them long-term, open an
 upstream issue so it can be promoted to a real export instead.
 
+## Hosting the workspace
+
+`<PlannerApp/>` is the batteries-included web composition: chrome, all
+routes, browser storage. A host with its own plans-management surface (its
+own library UI, its own chrome) instead mounts *parts* of the planner and
+supplies storage. Three hooks make that possible; none of them involve any
+capability detection — they are plain props, context, and route arrays.
+
+### Plan storage: the `PlanStore` seam
+
+The workspace, Compare, the optimizers, and the import wizard read and write
+plans through a provider interface:
+
+```ts
+import type { PlanStore, PlanSummary } from '@retiregolden/planner-ui'
+
+interface PlanStore {
+  listPlans(): Promise<PlanSummary[]>   // { id, name, updatedAtIso }
+  loadPlan(id: string): Promise<unknown> // stored plan JSON verbatim; null/undefined when absent
+  savePlan(plan: Plan): Promise<void>    // already validated + stamped; the autosave path
+  deletePlan(id: string): Promise<void>
+}
+```
+
+Implementations are storage-dumb by design: `loadPlan` returns the stored
+document as-is (any schema version) and planner-ui runs schema migration and
+Zod validation on it — the same single code path the web app has always used
+— while `savePlan` receives a plan that already passed validation and got its
+`updatedAtIso` stamp. A store never re-implements plan semantics.
+
+Supply a store with the provider or the `planStore` prop on `<PlannerApp/>`
+(the prop wins when both are present); keep the instance stable — the
+planner reloads when the store's identity changes:
+
+```tsx
+import { PlanStoreProvider } from '@retiregolden/planner-ui'
+
+<PlanStoreProvider store={myStore}>{/* planner routes */}</PlanStoreProvider>
+```
+
+Omit the provider and the browser IndexedDB implementation applies — it is
+also exported as `indexedDbPlanStore` for hosts that want to wrap it.
+
+Deliberate boundaries of the seam:
+
+- **Plan-scoped.** No client/household-grouping concepts; a host that keeps
+  per-client libraries maps plan ids to its own structure in its adapter.
+- **No change feed.** Planner list views refetch after their own mutations,
+  so the interface carries no subscription mechanism.
+- **Example demo records never cross it.** The example library's editable
+  demo slots (`example:*` ids) are per-device preview UX and stay in the
+  browser store regardless of provider; "Save to my plans" converts a demo
+  into a user plan and writes *that* through the seam. Small conveniences
+  (theme, dismissed banners) likewise stay in `localStorage`.
+
+### Route groups
+
+The route table is exported as three react-router v7 `RouteObject[]` arrays
+that spread into `useRoutes` or feed `createBrowserRouter`. Mount them at
+the host router's **root**; to serve the planner under a URL prefix, put the
+prefix in the router's `basename`
+(e.g. `<BrowserRouter basename="/planner">`) — planner pages navigate with
+root-absolute paths, which react-router resolves against the basename. Do
+not nest the groups under a parent route path (`path: 'planner/*'`): the
+initial deep link would render, but the first in-app navigation would escape
+the prefix. Deep links (e.g. `/plan/<id>/results`) work with only the
+workspace group mounted:
+
+| Export | Routes | Notes |
+|--------|--------|-------|
+| `plannerWorkspaceRoutes` | `plan/:planId/*` (sections, results, Monte Carlo, scenarios, survivor, relocation, optimizers, report) + `compare` | The plan workspace a host wraps in its own chrome |
+| `plannerContentRoutes` | `examples`, `learn/*`, `disclaimer`, `how-tested` | Storage-independent content; workspace pages link into it, so mount it (or redirect those paths) |
+| `plannerHomeRoutes` | `` (index), `import`, retired-route redirects | The web plans-management home — omit it if the host owns plan management |
+
+```tsx
+import { useRoutes } from 'react-router-dom'
+import { plannerWorkspaceRoutes, plannerContentRoutes } from '@retiregolden/planner-ui'
+
+function PlannerRoutes() {
+  return useRoutes([...plannerWorkspaceRoutes, ...plannerContentRoutes])
+}
+```
+
+The groups are chrome-free: no header/nav/footer, no theme toggle, and no
+`document.title` management for non-plan routes (plan routes retitle
+themselves). Workspace pages render links to `/` ("Your plans") — point that
+path at your own library surface. Hosts mounting groups directly brand
+downloaded reports with `ReportBrandingProvider` (the component form of the
+`reportBranding` prop below); `<PlannerApp/>` remains exactly the composition
+of all three groups plus the web chrome.
+
+### Plan interchange
+
+Use the `./plan-format` subpath (see "Published API surface") for import/
+export that speaks the same envelope as the web app's backup files:
+
+```ts
+import { serializeV2Backup, parseV2Backup } from '@retiregolden/planner-ui/plan-format'
+```
+
 ### Report branding
 
 Downloaded HTML reports (Results, Report, and Optimizer pages) can carry the
@@ -153,10 +269,11 @@ tokens (above).
 
 ### Storage
 
-Plans persist in the browser profile via IndexedDB (`idb`) with localStorage
-for small preferences, exactly as on retiregolden.app. Hosts that need a
-different persistence story should treat that as an upstream conversation,
-not a fork point.
+By default, plans persist in the browser profile via IndexedDB (`idb`) with
+localStorage for small preferences, exactly as on retiregolden.app. Hosts
+that need a different persistence story implement the `PlanStore` seam (see
+"Hosting the workspace") — anything the seam doesn't cover should be an
+upstream conversation, not a fork point.
 
 ## Relationship to the web app
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retiregolden/planner-ui",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -31,6 +31,7 @@
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./plan-format": "./src/data/planFormat.ts",
     "./index.css": "./src/index.css",
     "./*": "./src/*.ts",
     "./package.json": "./package.json"

package/src/App.tsx

@@ -1,26 +1,14 @@
-import { lazy, Suspense, useEffect, useRef, useState } from 'react'
-import { Navigate, NavLink, Route, Routes, useLocation } from 'react-router-dom'
-import { PlanPickerPage } from './planner/PlanPickerPage'
-import { DisclaimerPage } from './planner/DisclaimerPage'
+import { useEffect, useRef, useState } from 'react'
+import { NavLink, useLocation, useRoutes } from 'react-router-dom'
 import { RouteErrorBoundary } from './RouteErrorBoundary.tsx'
-import { RouteFallback } from './routes/RouteFallback'
+import { plannerContentRoutes, plannerHomeRoutes, plannerWorkspaceRoutes } from './routes/groups'
 import { readLocal, STORAGE_KEYS, writeLocal } from './data/localStore'
+import { usePlanStore, type PlanStore } from './data/planStoreContext'
+import { PlanStoreProvider } from './data/PlanStoreProvider'
 import { ReportBrandingContext } from './report/brandingContext'
 import type { ReportBranding } from './report/reportHtml'
 import './planner/planner.css'
 
-const PlanRoutes = lazy(() => import('./routes/PlanRoutes'))
-const LearnRoutes = lazy(() => import('./routes/LearnRoutes'))
-// Lazy like /plan and /learn: Examples pulls in all example builders + the Zod
-// schema, Compare pulls in the whole engine via projectPlan — eager imports
-// here would drag both into the landing entry chunk.
-const ExamplesPage = lazy(() => import('./planner/examples/ExamplesPage').then((m) => ({ default: m.ExamplesPage })))
-const ComparePlansPage = lazy(() => import('./planner/ComparePlansPage').then((m) => ({ default: m.ComparePlansPage })))
-// Lazy so the glob-derived test-suite manifests it embeds stay out of the landing chunk.
-const HowTestedPage = lazy(() => import('./planner/HowTestedPage').then((m) => ({ default: m.HowTestedPage })))
-// Lazy: the import wizard pulls in the per-source mappers and the Zod schema.
-const ImportPage = lazy(() => import('./import/ImportPage').then((m) => ({ default: m.ImportPage })))
-
 const navClass = ({ isActive }: { isActive: boolean }) =>
   isActive ? 'nav-link nav-link--active' : 'nav-link'
 
@@ -67,10 +55,25 @@ export interface PlannerAppProps {
    * (override the custom properties from index.css).
    */
   reportBranding?: ReportBranding
+  /**
+   * Plan storage for the planner (see `PlanStore` in the package exports).
+   * Precedence: this prop, else a `<PlanStoreProvider>` wrapping
+   * `<PlannerApp/>`, else the browser IndexedDB store — exactly as on
+   * retiregolden.app. Pass a stable instance — the planner reloads when the
+   * store's identity changes.
+   */
+  planStore?: PlanStore
 }
 
-export function App({ reportBranding }: PlannerAppProps = {}) {
+export function App({ reportBranding, planStore }: PlannerAppProps = {}) {
+  // An ambient <PlanStoreProvider> above the app must win over the built-in
+  // default; with neither prop nor provider this resolves to the browser
+  // store (the context's default value).
+  const ambientStore = usePlanStore()
   const location = useLocation()
+  // The full route table — <Routes> is exactly useRoutes over its children,
+  // so composing the exported groups this way renders identically.
+  const routeTree = useRoutes([...plannerHomeRoutes, ...plannerWorkspaceRoutes, ...plannerContentRoutes])
   const isLanding = location.pathname === '/' || location.pathname === '/examples'
   const [themeMode, setThemeMode] = useState<ThemeMode>(getInitialThemeMode)
   const [resolvedTheme, setResolvedTheme] = useState<'light' | 'dark'>(() => getResolvedTheme(getInitialThemeMode()))
@@ -122,6 +125,7 @@ export function App({ reportBranding }: PlannerAppProps = {}) {
       : '/brand/retiregolden-logo-lockup-light.png'
 
   return (
+    <PlanStoreProvider store={planStore ?? ambientStore}>
     <ReportBrandingContext.Provider value={reportBranding ?? null}>
     <div className={`app-shell planner-shell${isLanding ? ' app-shell--landing' : ''}`}>
       <a className="skip-link" href="#main-content">
@@ -175,64 +179,7 @@ export function App({ reportBranding }: PlannerAppProps = {}) {
         </div>
       </header>
       <main className="app-main" id="main-content" tabIndex={-1}>
-        <RouteErrorBoundary>
-          <Routes>
-            <Route path="/" element={<PlanPickerPage />} />
-            <Route
-              path="/examples"
-              element={
-                <Suspense fallback={<RouteFallback />}>
-                  <ExamplesPage />
-                </Suspense>
-              }
-            />
-            <Route
-              path="/compare"
-              element={
-                <Suspense fallback={<RouteFallback />}>
-                  <ComparePlansPage />
-                </Suspense>
-              }
-            />
-            <Route
-              path="/plan/*"
-              element={
-                <Suspense fallback={<RouteFallback />}>
-                  <PlanRoutes />
-                </Suspense>
-              }
-            />
-            <Route
-              path="/learn/*"
-              element={
-                <Suspense fallback={<RouteFallback />}>
-                  <LearnRoutes />
-                </Suspense>
-              }
-            />
-            <Route
-              path="/import"
-              element={
-                <Suspense fallback={<RouteFallback />}>
-                  <ImportPage />
-                </Suspense>
-              }
-            />
-            <Route path="/disclaimer" element={<DisclaimerPage />} />
-            <Route
-              path="/how-tested"
-              element={
-                <Suspense fallback={<RouteFallback />}>
-                  <HowTestedPage />
-                </Suspense>
-              }
-            />
-            {/* Retired v1 routes now redirect into the planner. */}
-            <Route path="/legacy" element={<Navigate to="/" replace />} />
-            <Route path="/longevity" element={<Navigate to="/" replace />} />
-            <Route path="/social-security" element={<Navigate to="/" replace />} />
-          </Routes>
-        </RouteErrorBoundary>
+        <RouteErrorBoundary>{routeTree}</RouteErrorBoundary>
       </main>
       <footer className="app-footer">
         <span className="muted small">
@@ -242,5 +189,6 @@ export function App({ reportBranding }: PlannerAppProps = {}) {
       </footer>
     </div>
     </ReportBrandingContext.Provider>
+    </PlanStoreProvider>
   )
 }

package/src/data/PlanStoreProvider.tsx

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react'
+
+import { PlanStoreContext, type PlanStore } from './planStoreContext'
+
+/**
+ * Supplies a host `PlanStore` (see data/planStoreContext.ts) to the planner
+ * tree. Without it — or via `<PlannerApp/>` with no `planStore` prop — the
+ * browser IndexedDB store applies. Keep the instance stable (module constant
+ * or memoized): the planner reloads when the store changes identity.
+ */
+export function PlanStoreProvider({ store, children }: { store: PlanStore; children: ReactNode }) {
+  return <PlanStoreContext.Provider value={store}>{children}</PlanStoreContext.Provider>
+}

package/src/data/planFormat.ts

@@ -0,0 +1,89 @@
+/**
+ * The v2 backup envelope — serialization and parsing of the plan-interchange
+ * format documented in DOCS/features/plan-file-format.md.
+ *
+ * **Stability promise:** this module is published as the
+ * `@retiregolden/planner-ui/plan-format` subpath and, unlike the wildcard
+ * deep paths, is a supported API: the envelope `kind`/`backupVersion`
+ * contract, the exported names, and their signatures only change with a
+ * semver-major release of the package. It is deliberately browser-free
+ * (no IndexedDB, no DOM) so hosts can run it anywhere — e.g. an Electron
+ * main process assembling library backups. (A standalone
+ * `@retiregolden/plan-format` package may eventually take this over; this
+ * subpath is the first step.)
+ *
+ * Format invariants callers may rely on:
+ * - Plans inside the envelope carry their own `schemaVersion` and are
+ *   individually migrated on parse, so old backups stay restorable forever.
+ * - `parseV2Backup` ignores unknown envelope fields — a host may extend the
+ *   envelope (extra top-level keys) and the file still round-trips through
+ *   this parser and the web app's import.
+ * - Envelope `kind`s from before the RetireGolden rebrand are still accepted.
+ */
+
+import { migratePlanToCurrent } from '@retiregolden/engine/model/migrations'
+import type { Plan } from '@retiregolden/engine/model/plan'
+
+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 }
+}

package/src/data/planStore.ts

@@ -82,15 +82,26 @@ export async function loadPlan(id: string): Promise<MigrateResult> {
 
 export type SavePlanResult = { ok: true; plan: Plan } | { ok: false; issues: string[] }
 
-/** Validates and writes a plan, bumping `updatedAtIso`. */
-export async function savePlan(plan: Plan, now: () => Date = () => new Date()): Promise<SavePlanResult> {
+/**
+ * The pure half of a save: bump `updatedAtIso` and re-validate. Every store
+ * that persists plans (this one and any host-provided `PlanStore`) writes
+ * through this so validation cannot drift between implementations.
+ */
+export function checkPlanForSave(plan: Plan, now: () => Date = () => new Date()): SavePlanResult {
   const stamped: Plan = { ...plan, updatedAtIso: now().toISOString() }
   const checked = parsePlan(stamped)
   if (!checked.ok) return { ok: false, issues: checked.issues }
-  await (await db()).put(PLANS_STORE, checked.plan)
   return { ok: true, plan: checked.plan }
 }
 
+/** Validates and writes a plan, bumping `updatedAtIso`. */
+export async function savePlan(plan: Plan, now: () => Date = () => new Date()): Promise<SavePlanResult> {
+  const checked = checkPlanForSave(plan, now)
+  if (!checked.ok) return checked
+  await (await db()).put(PLANS_STORE, checked.plan)
+  return checked
+}
+
 export interface DuplicatePlanOptions {
   name?: string
   newId?: () => string
@@ -103,13 +114,12 @@ export interface DuplicatePlanOptions {
   source?: Plan
 }
 
-export async function duplicatePlan(id: string, opts: DuplicatePlanOptions = {}): Promise<SavePlanResult> {
-  let source = opts.source
-  if (!source) {
-    const loaded = await loadPlan(id)
-    if (!loaded.ok) return { ok: false, issues: [`Could not load source plan (${loaded.reason}).`] }
-    source = loaded.plan
-  }
+/**
+ * The pure half of duplication: fresh id, user origin, stamped timestamps.
+ * Shared by the browser store and the store-generic seam operations so the
+ * clone semantics live in exactly one place.
+ */
+export function cloneAsUserPlan(source: Plan, opts: DuplicatePlanOptions = {}): { clone: Plan; nowIso: string } {
   const now = opts.now ?? (() => new Date())
   const nowIso = now().toISOString()
   const clone: Plan = structuredClone(source)
@@ -119,17 +129,29 @@ export async function duplicatePlan(id: string, opts: DuplicatePlanOptions = {})
   clone.exampleSourceId = source.exampleSourceId
   clone.createdAtIso = nowIso
   clone.updatedAtIso = nowIso
+  return { clone, nowIso }
+}
+
+export async function duplicatePlan(id: string, opts: DuplicatePlanOptions = {}): Promise<SavePlanResult> {
+  let source = opts.source
+  if (!source) {
+    const loaded = await loadPlan(id)
+    if (!loaded.ok) return { ok: false, issues: [`Could not load source plan (${loaded.reason}).`] }
+    source = loaded.plan
+  }
+  const { clone, nowIso } = cloneAsUserPlan(source, opts)
   return savePlan(clone, () => new Date(nowIso))
 }
 
 /**
- * Atomically converts a library demo to a user plan: delete the reserved
- * `example:*` record and put the converted plan under a fresh id.
+ * The pure half of demo conversion: the `example:*` record re-keyed under a
+ * fresh id as a user plan, re-validated. The delete/write choreography is the
+ * caller's business (atomic here; save-then-delete across the seam).
  */
-export async function convertExampleToUserPlan(
+export function convertedFromExample(
   plan: Plan,
   opts: { newId?: () => string; now?: () => Date } = {},
-): Promise<SavePlanResult> {
+): SavePlanResult {
   const newId = (opts.newId ?? (() => crypto.randomUUID()))()
   const now = opts.now ?? (() => new Date())
   const nowIso = now().toISOString()
@@ -142,13 +164,26 @@ export async function convertExampleToUserPlan(
   }
   const checked = parsePlan(converted)
   if (!checked.ok) return { ok: false, issues: checked.issues }
+  return { ok: true, plan: checked.plan }
+}
+
+/**
+ * Atomically converts a library demo to a user plan: delete the reserved
+ * `example:*` record and put the converted plan under a fresh id.
+ */
+export async function convertExampleToUserPlan(
+  plan: Plan,
+  opts: { newId?: () => string; now?: () => Date } = {},
+): Promise<SavePlanResult> {
+  const converted = convertedFromExample(plan, opts)
+  if (!converted.ok) return converted
 
   const database = await db()
   const tx = database.transaction(PLANS_STORE, 'readwrite')
   await tx.store.delete(plan.id)
-  await tx.store.put(checked.plan)
+  await tx.store.put(converted.plan)
   await tx.done
-  return { ok: true, plan: checked.plan }
+  return converted
 }
 
 export async function deletePlan(id: string): Promise<void> {
@@ -163,3 +198,17 @@ export async function clearAllPlans(): Promise<void> {
 export async function countStoredPlans(): Promise<number> {
   return (await (await db()).count(PLANS_STORE))
 }
+
+/**
+ * Raw record accessors backing the browser implementation of the `PlanStore`
+ * seam (data/planStoreContext.tsx): documents in/out, no migration or
+ * validation — those stay in the seam layer so they run identically over any
+ * store. Prefer `loadPlan`/`savePlan` everywhere else.
+ */
+export async function getPlanRecord(id: string): Promise<unknown> {
+  return (await (await db()).get(PLANS_STORE, id)) as unknown
+}
+
+export async function putPlanRecord(plan: Plan): Promise<void> {
+  await (await db()).put(PLANS_STORE, plan)
+}