@retiregolden/planner-ui 0.1.0

package/src/planner/useMcSuccessRate.ts

@@ -0,0 +1,77 @@
+/**
+ * Background Monte Carlo success rate for headline surfaces (the KPI bar and
+ * the Results verdict). Runs the MC page's exact default configuration — same
+ * seed, model, and path count — so headline numbers always match what the
+ * Monte Carlo page shows on arrival. Debounced well past the autosave window;
+ * failures stay silent here (the MC page owns the full error/retry surface).
+ *
+ * Concurrent subscribers share one run per plan object via the in-flight map,
+ * so the KPI bar and the verdict never trigger two identical 1,000-path
+ * simulations for the same plan.
+ */
+
+import { useEffect, useRef, useState } from 'react'
+
+import type { Plan } from '@retiregolden/engine/model/plan'
+import { DEFAULT_PATH_COUNT, runMonteCarlo } from '../mc/pool'
+import { buildModel } from './marketModelPicker'
+import { currentStartYear, seedFromPlanId } from './useProjection'
+
+const MC_DEBOUNCE_MS = 1200
+
+const inflight = new WeakMap<Plan, Promise<number>>()
+
+function successRateOf(plan: Plan): Promise<number> {
+  const existing = inflight.get(plan)
+  if (existing !== undefined) return existing
+  const model = buildModel('lognormal', plan.assumptions.inflationPct, 12, 60, plan)
+  const run = runMonteCarlo(plan, {
+    startYear: currentStartYear(),
+    pathCount: DEFAULT_PATH_COUNT,
+    seed: seedFromPlanId(plan.id),
+    model,
+  }).then((s) => s.successRate)
+  // Successful runs stay cached (later subscribers reuse the result), but a
+  // rejection is evicted so the next subscriber retries instead of replaying
+  // a transient worker failure forever for this plan object.
+  run.catch(() => {
+    inflight.delete(plan)
+  })
+  inflight.set(plan, run)
+  return run
+}
+
+export function useMcSuccessRate(plan: Plan, enabled: boolean): number | null {
+  // The rate is stored WITH the plan it was computed for, and derived to null
+  // whenever the current plan differs — so a headline number can never show a
+  // previous plan's rate through the debounce + recompute, and a silently
+  // failed re-run can never leave a stale rate up (edits produce a new plan
+  // object via structuredClone, so reference identity is the right key).
+  const [snapshot, setSnapshot] = useState<{ plan: Plan; rate: number } | null>(null)
+  const runToken = useRef(0)
+  useEffect(() => {
+    if (!enabled) return undefined
+    const token = ++runToken.current
+    const attach = () => {
+      successRateOf(plan)
+        .then((rate) => {
+          if (token === runToken.current) setSnapshot({ plan, rate })
+        })
+        .catch(() => {
+          /* silent — the Monte Carlo page carries the error state and retry */
+        })
+    }
+    // A run for this plan already exists (typically started by the KPI bar):
+    // attach immediately. The debounce only guards against launching fresh
+    // simulations mid-edit, and attaching to an existing run starts none.
+    if (inflight.get(plan) !== undefined) {
+      attach()
+      return undefined
+    }
+    const t = window.setTimeout(attach, MC_DEBOUNCE_MS)
+    return () => {
+      window.clearTimeout(t)
+    }
+  }, [plan, enabled])
+  return enabled && snapshot !== null && snapshot.plan === plan ? snapshot.rate : null
+}

package/src/planner/useProjection.ts

@@ -0,0 +1,63 @@
+/**
+ * Live deterministic projection: memoized simulatePlan over the standard tax
+ * stack (federal engine + flat state rate — same stack the Monte Carlo
+ * workers use, see src/mc/runRequest.ts). Fast enough (<5 ms typical) to run
+ * on every committed keystroke.
+ */
+
+import { useMemo } from 'react'
+
+import type { Plan } from '@retiregolden/engine/model/plan'
+import { summarizeProjection, type ProjectionSummary } from '@retiregolden/engine/projection/compare'
+import { simulatePlan } from '@retiregolden/engine/projection/simulate'
+import type { ProjectionResult } from '@retiregolden/engine/projection/types'
+import { combineTaxCalculators, createFederalTaxCalculator } from '@retiregolden/engine/tax/federalTax'
+import { createStateTaxCalculator } from '@retiregolden/engine/tax/stateTax'
+
+export function taxCalculatorFor(plan: Plan) {
+  return combineTaxCalculators(
+    createFederalTaxCalculator(),
+    createStateTaxCalculator({
+      overridePct: plan.assumptions.stateEffectiveTaxPct,
+      localPct: plan.assumptions.localIncomeTaxPct,
+    }),
+  )
+}
+
+export function currentStartYear(): number {
+  return new Date().getFullYear()
+}
+
+export interface ProjectionView {
+  result: ProjectionResult
+  summary: ProjectionSummary
+  startYear: number
+  /** Divide a nominal amount in `year` by this to get today's dollars. */
+  deflate: (year: number, amount: number) => number
+}
+
+export function projectPlan(plan: Plan, startYear = currentStartYear()): ProjectionView {
+  const result = simulatePlan(plan, { startYear, taxCalculator: taxCalculatorFor(plan) })
+  const summary = summarizeProjection(plan, result)
+  const r = 1 + plan.assumptions.inflationPct / 100
+  return {
+    result,
+    summary,
+    startYear,
+    deflate: (year, amount) => amount / Math.pow(r, year - startYear),
+  }
+}
+
+export function useProjection(plan: Plan): ProjectionView {
+  return useMemo(() => projectPlan(plan), [plan])
+}
+
+/** Stable Monte Carlo seed per plan (re-rollable in the UI). */
+export function seedFromPlanId(id: string): number {
+  let h = 2166136261
+  for (let i = 0; i < id.length; i++) {
+    h ^= id.charCodeAt(i)
+    h = Math.imul(h, 16777619)
+  }
+  return h >>> 0
+}

package/src/relocation/messages.ts

@@ -0,0 +1,21 @@
+/**
+ * Wire types between the Relocation Compare page and its worker. Same rules
+ * as src/mc/messages.ts: everything must survive structured clone — the
+ * comparison rows are plain data (numbers, strings, small arrays).
+ */
+
+import type { Plan } from '@retiregolden/engine/model/plan'
+import type { MarketModelConfig } from '@retiregolden/engine/montecarlo/marketModels'
+import type { RelocationCandidate, RelocationComparison } from '@retiregolden/engine/projection/relocation'
+
+export interface RelocationCompareRequest {
+  plan: Plan
+  candidates: RelocationCandidate[]
+  startYear: number
+  /** When present, rows get a Monte Carlo success rate on shared market paths. */
+  monteCarlo?: { model: MarketModelConfig; pathCount: number; seed: number } | null
+}
+
+export type RelocationCompareResponse =
+  | { type: 'done'; result: RelocationComparison }
+  | { type: 'error'; message: string }

package/src/relocation/relocation.worker.ts

@@ -0,0 +1,18 @@
+/**
+ * Web Worker entry for the relocation compare: one request per run — up to
+ * six deterministic full-plan simulations plus the optional shared-path
+ * Monte Carlo — posted back as one summarized result.
+ */
+
+import type { RelocationCompareRequest, RelocationCompareResponse } from './messages'
+import { runRelocationCompareRequest } from './runRelocation'
+
+const post = (msg: RelocationCompareResponse) => (self as unknown as Worker).postMessage(msg)
+
+self.onmessage = (event: MessageEvent<RelocationCompareRequest>) => {
+  try {
+    post({ type: 'done', result: runRelocationCompareRequest(event.data) })
+  } catch (err) {
+    post({ type: 'error', message: err instanceof Error ? err.message : String(err) })
+  }
+}

package/src/relocation/runRelocation.ts

@@ -0,0 +1,17 @@
+/**
+ * Executes one relocation-compare sweep. Shared by the Web Worker entry and
+ * the synchronous fallback (tests / no-Worker environments). The engine
+ * builds the app-standard per-candidate tax stacks itself (federal + modeled
+ * state packs with the plan's flat rate as an override), so both paths run
+ * identical numbers.
+ */
+
+import { compareRelocationCandidates, type RelocationComparison } from '@retiregolden/engine/projection/relocation'
+import type { RelocationCompareRequest } from './messages'
+
+export function runRelocationCompareRequest(req: RelocationCompareRequest): RelocationComparison {
+  return compareRelocationCandidates(req.plan, req.candidates, {
+    startYear: req.startYear,
+    monteCarlo: req.monteCarlo ?? null,
+  })
+}

package/src/relocation/runner.ts

@@ -0,0 +1,22 @@
+/**
+ * Spawns the relocation-compare sweep in a Web Worker (lazy-loaded only here)
+ * and resolves the comparison. Falls back to a synchronous in-process run
+ * where Worker is unavailable (tests, very old browsers), mirroring
+ * src/optimize/spendingRunner.ts.
+ */
+
+import type { RelocationComparison } from '@retiregolden/engine/projection/relocation'
+import { runWorkerRequest } from '../workers/run'
+import type { RelocationCompareRequest, RelocationCompareResponse } from './messages'
+import { runRelocationCompareRequest } from './runRelocation'
+
+export function runRelocationCompare(req: RelocationCompareRequest): Promise<RelocationComparison> {
+  if (typeof Worker === 'undefined') return Promise.resolve(runRelocationCompareRequest(req))
+  return runWorkerRequest<RelocationCompareRequest, RelocationCompareResponse, RelocationComparison>({
+    request: req,
+    createWorker: () => new Worker(new URL('./relocation.worker.ts', import.meta.url), { type: 'module' }),
+    interpret: (msg) =>
+      msg.type === 'done' ? { kind: 'done', result: msg.result } : { kind: 'error', message: msg.message },
+    errorLabel: 'Relocation compare worker failed',
+  })
+}

package/src/report/brandingContext.ts

@@ -0,0 +1,15 @@
+/**
+ * Threads the host's `reportBranding` prop (see `PlannerApp`) from the app
+ * shell down to the pages with "Download HTML report" buttons, so a host can
+ * brand downloaded reports without touching the planner tree. Null means "no
+ * branding supplied" — the report renders its RetireGolden defaults.
+ */
+import { createContext, useContext } from 'react'
+
+import type { ReportBranding } from './reportHtml'
+
+export const ReportBrandingContext = createContext<ReportBranding | null>(null)
+
+export function useReportBranding(): ReportBranding | null {
+  return useContext(ReportBrandingContext)
+}

package/src/report/downloadReport.ts

@@ -0,0 +1,34 @@
+import type { Plan } from '@retiregolden/engine/model/plan'
+import type { ProjectionSummary } from '@retiregolden/engine/projection/compare'
+import type { ProjectionResult } from '@retiregolden/engine/projection/types'
+import { buildStandaloneReportHtml, type ReportBranding, type ReportRecommendationEvidence } from './reportHtml'
+
+function slug(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+function fileStem(name: string): string {
+  return slug(name) || 'retiregolden-plan'
+}
+
+export function downloadStandaloneReport(args: {
+  plan: Plan
+  result: ProjectionResult
+  summary: ProjectionSummary
+  startYear: number
+  recommendationEvidence?: ReportRecommendationEvidence | null
+  branding?: ReportBranding | null
+}): void {
+  const html = buildStandaloneReportHtml(args)
+  const brandStem = slug(args.branding?.productName ?? '') || 'retiregolden'
+  const blob = new Blob([html], { type: 'text/html' })
+  const a = document.createElement('a')
+  a.href = URL.createObjectURL(blob)
+  a.download = `${fileStem(args.plan.name)}-${brandStem}-report.html`
+  a.click()
+  URL.revokeObjectURL(a.href)
+}