feat: replace demo data automatically on first real import

src/features/demo/demo-manifest.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest"
+
+import {
+  clearDemoManifest,
+  DEMO_MANIFEST_KEY,
+  readDemoManifest,
+  writeDemoManifest,
+} from "@/features/demo/demo-manifest"
+
+function memoryStorage(initial: Record<string, string> = {}): Storage {
+  const store = new Map(Object.entries(initial))
+  return {
+    getItem: (key: string) => store.get(key) ?? null,
+    setItem: (key: string, value: string) => {
+      store.set(key, value)
+    },
+    removeItem: (key: string) => {
+      store.delete(key)
+    },
+    clear: () => store.clear(),
+    get length() {
+      return store.size
+    },
+    key: (index: number) => [...store.keys()][index] ?? null,
+  }
+}
+
+describe("demo manifest", () => {
+  it("round-trips recorded budget and group ids", () => {
+    const storage = memoryStorage()
+    writeDemoManifest({ budgetIds: ["b1"], groupIds: ["g1", "g2"] }, storage)
+    expect(storage.getItem(DEMO_MANIFEST_KEY)).toContain("b1")
+    expect(readDemoManifest(storage)).toEqual({ budgetIds: ["b1"], groupIds: ["g1", "g2"] })
+  })
+
+  it("returns null when missing, corrupt, or empty", () => {
+    expect(readDemoManifest(memoryStorage())).toBeNull()
+    expect(readDemoManifest(memoryStorage({ [DEMO_MANIFEST_KEY]: "not-json" }))).toBeNull()
+    expect(readDemoManifest(memoryStorage({ [DEMO_MANIFEST_KEY]: JSON.stringify({}) }))).toBeNull()
+    expect(
+      readDemoManifest(
+        memoryStorage({ [DEMO_MANIFEST_KEY]: JSON.stringify({ budgetIds: [], groupIds: [] }) }),
+      ),
+    ).toBeNull()
+  })
+
+  it("drops non-string entries and clears on demand", () => {
+    const storage = memoryStorage({
+      [DEMO_MANIFEST_KEY]: JSON.stringify({ budgetIds: ["b1", 42, null], groupIds: "nope" }),
+    })
+    expect(readDemoManifest(storage)).toEqual({ budgetIds: ["b1"], groupIds: [] })
+    clearDemoManifest(storage)
+    expect(readDemoManifest(storage)).toBeNull()
+    expect(storage.getItem(DEMO_MANIFEST_KEY)).toBeNull()
+  })
+})

src/features/demo/demo-manifest.ts

@@ -0,0 +1,59 @@
+// Tracks exactly which budget/group rows the demo seeder created, so the
+// first real import can remove them again. ids are random per seed, so they
+// cannot be rediscovered from content. Leaf module (no imports) to avoid a
+// cycle: demo-seed writes it, import-service reads and clears it.
+
+export const DEMO_MANIFEST_KEY = "budgetlens.demo-manifest.v1"
+
+export interface DemoManifest {
+  budgetIds: string[]
+  groupIds: string[]
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null
+}
+
+function asIdList(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((item): item is string => typeof item === "string" && item.length > 0)
+}
+
+export function readDemoManifest(
+  storage: Pick<Storage, "getItem"> = globalThis.localStorage,
+): DemoManifest | null {
+  try {
+    const raw = storage.getItem(DEMO_MANIFEST_KEY)
+    if (!raw) return null
+    const parsed: unknown = JSON.parse(raw) as unknown
+    if (!isRecord(parsed)) return null
+    const budgetIds = asIdList(parsed.budgetIds)
+    const groupIds = asIdList(parsed.groupIds)
+    if (budgetIds.length === 0 && groupIds.length === 0) return null
+    return { budgetIds, groupIds }
+  } catch {
+    return null
+  }
+}
+
+export function writeDemoManifest(
+  manifest: DemoManifest,
+  storage: Pick<Storage, "setItem"> = globalThis.localStorage,
+): void {
+  try {
+    storage.setItem(DEMO_MANIFEST_KEY, JSON.stringify(manifest))
+  } catch {
+    // Private-mode storage may throw; seeding still succeeds, and replacement
+    // falls back to import-linked rows only (budgets/groups are re-seedable).
+  }
+}
+
+export function clearDemoManifest(
+  storage: Pick<Storage, "removeItem"> = globalThis.localStorage,
+): void {
+  try {
+    storage.removeItem(DEMO_MANIFEST_KEY)
+  } catch {
+    // Best-effort only.
+  }
+}

src/features/demo/demo-seed.ts

@@ -4,6 +4,7 @@ import { database } from "@/db/database"
 import { ImportService } from "@/features/imports/import-service"
 import { readOnboardingChoice } from "@/features/onboarding/onboarding-storage"
 
+import { writeDemoManifest } from "./demo-manifest"
 import {
   DEFAULT_DEMO_TEMPLATE_ID,
   getDemoTemplate,
@@ -48,21 +49,25 @@ export async function seedDemoDataIfEmpty(
   await importService.commit(preview)
 
   const now = new Date().toISOString()
-  await db.budgets.bulkPut(
-    template.budgets.map((goal) => ({
-      ...goal,
-      id: crypto.randomUUID(),
-      createdAt: now,
-      updatedAt: now,
-    })),
-  )
+  const budgetRows = template.budgets.map((goal) => ({
+    ...goal,
+    id: crypto.randomUUID(),
+    createdAt: now,
+    updatedAt: now,
+  }))
+  await db.budgets.bulkPut(budgetRows)
 
   const groupSeeds = template.groups.map((group) => {
     const id = crypto.randomUUID()
     return { id, name: group.name, row: { ...group, id, createdAt: now, updatedAt: now } }
   })
   await db.transactionGroups.bulkPut(groupSeeds.map((seed) => seed.row))
   const groupIds = new Map(groupSeeds.map((seed) => [seed.name, seed.id]))
+  // Record exactly what was seeded so the first real import can remove it.
+  writeDemoManifest({
+    budgetIds: budgetRows.map((row) => row.id),
+    groupIds: groupSeeds.map((seed) => seed.id),
+  })
 
   // Link the tagged trip expenses to the trip group as a shared two-way split.
   const tripGroupId = groupIds.get(template.tripGroupName)

src/features/imports/import-page.test.tsx

@@ -1,7 +1,9 @@
 import { render, screen } from "@testing-library/react"
 import userEvent from "@testing-library/user-event"
 
+import { database } from "@/db/database"
 import type { ImportBatch } from "@/domain/models"
+import { DEMO_SOURCE_NAME } from "@/features/demo/golden-bundle"
 import type {
   ImportCollectionPreview,
   ImportDeletionReceipt,
@@ -537,3 +539,93 @@ describe("ImportPage", () => {
     ).not.toBeInTheDocument()
   })
 })
+
+describe("demo replacement notice", () => {
+  afterEach(async () => {
+    await database.imports.clear()
+  })
+
+  it("warns that importing replaces demo data, once per preview", async () => {
+    const user = userEvent.setup()
+    await database.imports.add({
+      id: "demo-batch-1",
+      kind: "bundle",
+      sourceName: DEMO_SOURCE_NAME,
+      sourceHash: "demo-hash",
+      rowCount: 1,
+      importedCount: 1,
+      skippedCount: 0,
+      replacedCount: 0,
+      importedAt: "2026-07-22T12:00:00.000Z",
+    })
+    mocks.preview.mockResolvedValueOnce({
+      kind: "transactions",
+      sourceName: "real.csv",
+      sourceHash: "real-hash",
+      rowCount: 1,
+      transactions: [],
+      wealth: [],
+      wealthBreakdown: [],
+      wealthAccounts: [],
+      issues: [],
+      duplicateFile: false,
+      duplicateCount: 0,
+      replacementCount: 0,
+      importableCount: 1,
+      duplicatePolicy: "skip",
+      wealthPolicy: "skip",
+    })
+    render(<ImportPage />)
+    const file = new File(["Date,Description,Amount"], "real.csv", { type: "text/csv" })
+    Object.defineProperty(file, "text", {
+      value: () => Promise.resolve("Date,Description,Amount"),
+    })
+    await user.upload(screen.getByLabelText("CSV or JSON files"), file)
+    await screen.findByRole("heading", { name: "Import preview" })
+    expect(
+      await screen.findByText("Importing will replace the sample demo data currently shown."),
+    ).toBeInTheDocument()
+    await database.imports.clear()
+  })
+
+  it("stays silent for demo bundles", async () => {
+    const user = userEvent.setup()
+    await database.imports.add({
+      id: "demo-batch-1",
+      kind: "bundle",
+      sourceName: DEMO_SOURCE_NAME,
+      sourceHash: "demo-hash",
+      rowCount: 1,
+      importedCount: 1,
+      skippedCount: 0,
+      replacedCount: 0,
+      importedAt: "2026-07-22T12:00:00.000Z",
+    })
+    mocks.preview.mockResolvedValueOnce({
+      kind: "bundle",
+      sourceName: DEMO_SOURCE_NAME,
+      sourceHash: "demo-hash-2",
+      rowCount: 1,
+      transactions: [],
+      wealth: [],
+      wealthBreakdown: [],
+      wealthAccounts: [],
+      issues: [],
+      duplicateFile: false,
+      duplicateCount: 0,
+      replacementCount: 0,
+      importableCount: 1,
+      duplicatePolicy: "skip",
+      wealthPolicy: "skip",
+    })
+    render(<ImportPage />)
+    const file = new File(["{}"], "demo.json", { type: "application/json" })
+    Object.defineProperty(file, "text", { value: () => Promise.resolve("{}") })
+    await user.upload(screen.getByLabelText("CSV or JSON files"), file)
+    await screen.findByRole("heading", { name: "Import preview" })
+    expect(
+      screen.queryByText("Importing will replace the sample demo data currently shown."),
+    ).not.toBeInTheDocument()
+    await database.imports.clear()
+  })
+})

src/features/imports/import-page.tsx

@@ -7,6 +7,8 @@ import { Input } from "@/components/ui/input"
 import { Label } from "@/components/ui/label"
 import { repositories } from "@/db/repositories"
 import type { ImportBatch } from "@/domain/models"
+import { useIsDemoData } from "@/features/demo/demo-seed"
+import { isDemoSourceName } from "@/features/demo/demo-templates"
 import type { CsvColumnMapping, CsvMappableField } from "@/features/imports/csv-mapping"
 import {
   CSV_MAPPABLE_FIELDS,
@@ -177,6 +179,7 @@ export async function readFilesIndependently(
 
 export function ImportPage() {
   const inputId = useId()
+  const demoPresent = useIsDemoData()
   const [preview, setPreview] = useState<ImportPreview | null>(null)
   const [collection, setCollection] = useState<ImportCollectionPreview | null>(null)
   const [history, setHistory] = useState<ImportBatch[]>([])
@@ -678,6 +681,12 @@ export function ImportPage() {
             </CardDescription>
           </CardHeader>
           <CardContent className="space-y-5">
+            {demoPresent &&
+            collection.previews.some((item) => !isDemoSourceName(item.sourceName)) ? (
+              <p className="rounded-lg bg-muted p-3 text-sm">
+                Importing will replace the sample demo data currently shown.
+              </p>
+            ) : null}
             <dl className="grid grid-cols-2 gap-4 sm:grid-cols-4">
               <div>
                 <dt className="text-xs text-muted-foreground">Rows</dt>
@@ -955,6 +964,11 @@ export function ImportPage() {
             </CardDescription>
           </CardHeader>
           <CardContent className="space-y-5">
+            {demoPresent && !isDemoSourceName(preview.sourceName) ? (
+              <p className="rounded-lg bg-muted p-3 text-sm">
+                Importing will replace the sample demo data currently shown.
+              </p>
+            ) : null}
             <dl className="grid grid-cols-2 gap-4 sm:grid-cols-4">
               <div>
                 <dt className="text-xs text-muted-foreground">Rows</dt>

src/features/imports/import-service.test.ts

@@ -2,6 +2,9 @@ import { readFile } from "node:fs/promises"
 import path from "node:path"
 
 import { BudgetLensDatabase } from "@/db/database"
+import { clearDemoManifest, readDemoManifest } from "@/features/demo/demo-manifest"
+import { seedDemoDataIfEmpty } from "@/features/demo/demo-seed"
+import { DEMO_SOURCE_NAME } from "@/features/demo/golden-bundle"
 import { ImportService } from "@/features/imports/import-service"
 
 async function fixture(name: string): Promise<string> {
@@ -379,3 +382,57 @@ describe("ImportService", () => {
     ).rejects.toThrow("combined byte limit")
   })
 })
+
+describe("demo replacement on real import", () => {
+  let db: BudgetLensDatabase
+  let service: ImportService
+
+  beforeEach(() => {
+    db = new BudgetLensDatabase(`budgetlens-restore-test-${crypto.randomUUID()}`)
+    service = new ImportService(db)
+    clearDemoManifest()
+  })
+
+  afterEach(async () => {
+    clearDemoManifest()
+    await db.delete()
+  })
+
+  it("removes demo content when real data lands", async () => {
+    expect(await seedDemoDataIfEmpty(db)).toBe(true)
+    expect(await db.transactions.count()).toBeGreaterThan(0)
+    expect(await db.budgets.count()).toBeGreaterThan(0)
+    expect(readDemoManifest()).not.toBeNull()
+
+    const preview = await service.preview(
+      "Date,Description,Amount,Account Name\n2026-09-01,Real Grocer,-42.10,Real Checking",
+      "real.csv",
+    )
+    await service.commit(preview)
+
+    expect(await db.transactions.count()).toBe(1)
+    expect(await db.wealth.count()).toBe(0)
+    expect(await db.budgets.count()).toBe(0)
+    expect(await db.transactionGroups.count()).toBe(0)
+    expect(await db.imports.count()).toBe(1)
+    expect((await db.imports.toArray())[0]).toMatchObject({ sourceName: "real.csv" })
+    expect(readDemoManifest()).toBeNull()
+  })
+
+  it("keeps demo content when committing demo-shaped data", async () => {
+    expect(await seedDemoDataIfEmpty(db)).toBe(true)
+    const before = await db.transactions.count()
+
+    const preview = await service.preview(
+      "Date,Description,Amount\n2026-09-02,Extra,-5.00",
+      "extra.csv",
+    )
+    await service.commit({ ...preview, sourceName: DEMO_SOURCE_NAME })
+
+    expect(await db.transactions.count()).toBe(before + 1)
+    expect(await db.budgets.count()).toBeGreaterThan(0)
+    expect(readDemoManifest()).not.toBeNull()
+    const sources = (await db.imports.toArray()).map((batch) => batch.sourceName)
+    expect(sources).toContain(DEMO_SOURCE_NAME)
+  })
+})