Drive indexing: show a per-volume step checklist

Indexing is no longer an opaque bar that restarts under changing titles. Each drive's tooltip now shows a checklist of the actual steps — find files, save the file list, compute folder sizes, catch up on recent changes — each marked waiting (hollow), in progress (spinner), or done (check), with the live detail (count, folder-sizing sub-phase, progress bar, per-step ETA) under the active step. The user can finally see what indexing does, which step it's on, and how many remain.

- Steps are composed from the events that actually fire for each drive: a network (SMB/MTP) scan inserts entries inline and shows just find + compute; an event-log roll-on collapses to a single 'Update index' step. The derivation is a pure, unit-tested function driven by the typed pipeline phase + aggregation sub-phase (no string-matching), and stays correct across a mid-scan reload by deriving from the furthest-reached signal.
- The corner indicator expands the primary drive's checklist and collapses each other active drive to a one-line summary. The breadcrumb badge shows its own drive's full checklist. All steps render up-front so the tooltip height stays stable as steps tick.
- Per-step ETA only; a true overall ETA needs persisted per-phase calibration and is deferred (docs/specs/later/drive-index-overall-eta.md).
- Honest folder wording throughout; markers via the shared Icon/Spinner; reduced-motion respected; checklist is screen-reader friendly (per-step status words).

Part of the drive-index progress-reporting plan, milestone M4b.

Author: vdavid

apps/desktop/src/lib/file-explorer/navigation/CLAUDE.md

@@ -38,9 +38,9 @@ Browser-style back/forward history, path resolution, paged keyboard shortcuts, a
   single live-activity source), read per-volume via `getVolumeActivity` — don't reintroduce a manager-side progress map.
   The `scanning` badge tooltip switches from a text tooltip to the `contentEl` DOM tooltip and renders the SHARED
   `IndexingDriveRow` body (heading off) for its volume, so it matches the corner indicator; it falls back to a static
-  "Scanning your drive…" text when activity hasn't hydrated yet (the SMB/MTP first-tick window). Non-scanning states keep
-  the text tooltip. The badge is a `<button>` (axe rejects `role="img"`). Refused enable/rescan is classified by typed
-  `SmbIndexGateReason`, never text. Full contract: DETAILS § Drive index freshness badge.
+  "Scanning your drive…" text when activity hasn't hydrated yet (the SMB/MTP first-tick window). Non-scanning states
+  keep the text tooltip. The badge is a `<button>` (axe rejects `role="img"`). Refused enable/rescan is classified by
+  typed `SmbIndexGateReason`, never text. Full contract: DETAILS § Drive index freshness badge.
 - **Favorites: mutate ONLY via the `commands.*` wrappers, ALWAYS stripping the `fav-` prefix** (the switcher id is
   `fav-<favoriteId>`; the commands take the bare id via `stripFavoritePrefix`). The `volume-grouping.ts` favorites group
   always renders even when empty (the placeholder row), so don't tidy it into a hide-when-empty branch. "Add to

apps/desktop/src/lib/file-explorer/navigation/DETAILS.md

@@ -344,14 +344,14 @@ formatter are the pure `drive-index-status.ts` (unit-tested). Blue pulses (gated
 - **A scanning badge shows the SHARED live status body**, not a bespoke string — the same `IndexingDriveRow` body the
   corner indicator renders (heading off), so the two surfaces match exactly (count + elapsed for a first scan, or
   bar+percent+ETA for a calibrated rescan; see `$lib/indexing` DETAILS § Status indicator tooltip content). The badge
-  reads ONLY its own volume's live activity from `index-state` via `getVolumeActivity(volumeId)` (+ `getVolumeAggregation`)
-  — `index-state` is the single live-activity source; the manager carries no progress map. For the `scanning` state the
-  tooltip switches from the text variant to the `contentEl` DOM tooltip: the body lives in a `<div hidden>` host and the
-  INNER element is handed to the tooltip as `contentEl` (an adopted element keeps its own `hidden`, so the host can't be
-  passed — mirrors `IndexingStatusIndicator`). Fallback: for a non-root (SMB/MTP) volume, `index-state` only hydrates on
-  the next ~500 ms progress tick, so in the window between the freshness flip to `scanning` and that tick there's no
-  activity — the badge then shows a static "Scanning your drive…" text tooltip (`indexing.scan.label`), never an empty
-  one. Non-scanning states (disabled/fresh/stale) keep their text tooltips.
+  reads ONLY its own volume's live activity from `index-state` via `getVolumeActivity(volumeId)` (+
+  `getVolumeAggregation`) — `index-state` is the single live-activity source; the manager carries no progress map. For
+  the `scanning` state the tooltip switches from the text variant to the `contentEl` DOM tooltip: the body lives in a
+  `<div hidden>` host and the INNER element is handed to the tooltip as `contentEl` (an adopted element keeps its own
+  `hidden`, so the host can't be passed — mirrors `IndexingStatusIndicator`). Fallback: for a non-root (SMB/MTP) volume,
+  `index-state` only hydrates on the next ~500 ms progress tick, so in the window between the freshness flip to
+  `scanning` and that tick there's no activity — the badge then shows a static "Scanning your drive…" text tooltip
+  (`indexing.scan.label`), never an empty one. Non-scanning states (disabled/fresh/stale) keep their text tooltips.
 - **The badge is a focusable `<button>`** with an `aria-label` (state ariaLabel + the tooltip text) and
   `aria-haspopup="menu"`; clicking opens a small themed popover menu (NOT a native menu) anchored to the badge. Menu
   actions (`enable`/`rescan`/`disable`/`stop`) call back to `VolumeBreadcrumb`'s `handleDriveIndexAction`, which runs

apps/desktop/src/lib/file-explorer/navigation/DriveIndexBadge.a11y.test.ts

@@ -8,12 +8,27 @@ import { mount, flushSync, tick } from 'svelte'
 import type { Freshness, VolumeIndexStatus } from '$lib/ipc/bindings'
 import type { VolumeIndexActivity } from '$lib/indexing'
 
-// The badge reads its own volume's live activity from `index-state`; mock it so
-// we can exercise the scanning tooltip's rich DOM body.
+// The badge reads its own volume's live activity + phase from `index-state`; mock
+// it so we can exercise the scanning tooltip's rich DOM checklist body.
 let badgeActivity: VolumeIndexActivity | undefined
 vi.mock('$lib/indexing', () => ({
   getVolumeActivity: () => badgeActivity,
   getVolumeAggregation: () => undefined,
+  getVolumePhase: () => undefined,
+  placeholderActivity: (volumeId: string): VolumeIndexActivity => ({
+    volumeId,
+    phase: 'scanning',
+    entriesScanned: 0,
+    dirsFound: 0,
+    bytesScanned: 0,
+    scanStartedAt: 0,
+    priorTotalEntries: null,
+    priorScanDurationMs: null,
+    volumeUsedBytes: null,
+    replayEventsProcessed: 0,
+    replayEstimatedTotal: 0,
+    replayStartedAt: 0,
+  }),
 }))
 
 import DriveIndexBadge from './DriveIndexBadge.svelte'
@@ -32,7 +47,10 @@ function makeStatus(freshness: Freshness | null, enabled = freshness != null): V
 async function mountBadge(status: VolumeIndexStatus) {
   const target = document.createElement('div')
   document.body.appendChild(target)
-  mount(DriveIndexBadge, { target, props: { volumeId: status.volumeId, status, driveName: 'Backups', onAction: () => {} } })
+  mount(DriveIndexBadge, {
+    target,
+    props: { volumeId: status.volumeId, status, driveName: 'Backups', onAction: () => {} },
+  })
   await tick()
   return target
 }

apps/desktop/src/lib/file-explorer/navigation/DriveIndexBadge.svelte

@@ -25,7 +25,7 @@
         type DriveIndexMenuAction,
         type DriveIndexState,
     } from './drive-index-status'
-    import { getVolumeActivity, getVolumeAggregation } from '$lib/indexing'
+    import { getVolumeActivity, getVolumeAggregation, getVolumePhase, placeholderActivity } from '$lib/indexing'
     import IndexingDriveRow from '$lib/indexing/IndexingDriveRow.svelte'
 
     interface Props {
@@ -69,12 +69,19 @@
     // the static text fallback shows instead of an empty tooltip.
     const activity = $derived(getVolumeActivity(volumeId))
     const aggregation = $derived(getVolumeAggregation(volumeId))
+    // This volume's top-level phase, so the checklist stays visible through the
+    // reconcile step (scan + aggregation both done, only the phase event marks it):
+    // there's no live `activity` then, so fall back to a placeholder the checklist
+    // reads its state from via the phase. `undefined` until the first signal lands.
+    const phase = $derived(getVolumePhase(volumeId))
+    const bodyActivity = $derived(activity ?? (phase != null ? placeholderActivity(volumeId) : undefined))
 
     // The shared body lives in a hidden host; we hand its inner element to the
-    // tooltip as `contentEl`. Rich only once it's mounted (activity present), else
-    // the static fallback text. Mirrors the indicator's `contentEl` pattern.
+    // tooltip as `contentEl`. Rich only once there's something to show (live
+    // activity, or a phase mid-pipeline), else the static fallback text. Mirrors
+    // the indicator's `contentEl` pattern.
     let scanBodyEl = $state<HTMLDivElement>()
-    const useRichScanningTooltip = $derived(badgeState === 'scanning' && activity != null && scanBodyEl != null)
+    const useRichScanningTooltip = $derived(badgeState === 'scanning' && bodyActivity != null && scanBodyEl != null)
 
     // The text tooltip per state. The `scanning` text is the static fallback for
     // the no-activity-yet window (the rich body replaces it once activity lands);
@@ -156,14 +163,14 @@
     onclick={toggleMenu}
 ></button>
 
-{#if badgeState === 'scanning' && activity}
+{#if badgeState === 'scanning' && bodyActivity}
     <!-- The scanning tooltip's rich body. Lives in a hidden host; the tooltip
          action adopts the INNER element (`scanBodyEl`) as `contentEl`, not the
          hidden host (an adopted element keeps its own `hidden`, so a hidden host
          would render an empty tooltip). Mirrors `IndexingStatusIndicator`. -->
     <div hidden>
         <div bind:this={scanBodyEl} class="scan-tooltip-body">
-            <IndexingDriveRow {activity} {aggregation} {driveName} showHeading={false} />
+            <IndexingDriveRow activity={bodyActivity} {aggregation} {driveName} showHeading={false} />
         </div>
     </div>
 {/if}

apps/desktop/src/lib/file-explorer/navigation/DriveIndexBadge.svelte.test.ts

@@ -8,15 +8,31 @@
  */
 import { describe, it, expect, vi, beforeEach } from 'vitest'
 import { mount, flushSync } from 'svelte'
-import type { VolumeIndexStatus } from '$lib/ipc/bindings'
+import type { ActivityPhase, VolumeIndexStatus } from '$lib/ipc/bindings'
 import type { VolumeIndexActivity } from '$lib/indexing'
 
-// The badge reads its own volume's live activity from `index-state` (the single
-// live-activity source). Mock it so we can drive the scanning tooltip body.
+// The badge reads its own volume's live activity + phase from `index-state` (the
+// single live-activity source). Mock it so we can drive the scanning tooltip body.
 let badgeActivity: VolumeIndexActivity | undefined
+let badgePhase: ActivityPhase | undefined
 vi.mock('$lib/indexing', () => ({
   getVolumeActivity: () => badgeActivity,
   getVolumeAggregation: () => undefined,
+  getVolumePhase: () => badgePhase,
+  placeholderActivity: (volumeId: string): VolumeIndexActivity => ({
+    volumeId,
+    phase: 'scanning',
+    entriesScanned: 0,
+    dirsFound: 0,
+    bytesScanned: 0,
+    scanStartedAt: 0,
+    priorTotalEntries: null,
+    priorScanDurationMs: null,
+    volumeUsedBytes: null,
+    replayEventsProcessed: 0,
+    replayEstimatedTotal: 0,
+    replayStartedAt: 0,
+  }),
 }))
 
 import DriveIndexBadge from './DriveIndexBadge.svelte'
@@ -75,6 +91,7 @@ function ariaLabel(target: HTMLElement): string {
 
 beforeEach(() => {
   badgeActivity = undefined
+  badgePhase = undefined
 })
 
 describe('DriveIndexBadge color class', () => {
@@ -155,12 +172,13 @@ describe('DriveIndexBadge scanning tooltip', () => {
     expect(target.querySelector('.scan-tooltip-body')).toBeNull()
   })
 
-  it('renders the shared status body (count + elapsed) once live activity is present', () => {
+  it('renders the shared checklist body (count + elapsed) once live activity is present', () => {
     badgeActivity = scanActivity({ volumeUsedBytes: 10_000_000 }) // rough first scan: count + elapsed, no bar
     const { target } = render(makeStatus({ freshness: 'scanning' }))
     const body = target.querySelector('.scan-tooltip-body')
     expect(body).not.toBeNull()
-    expect(body?.textContent).toContain('Scanning your drive')
+    // The checklist's first step (a network drive: Find files, then Compute folder sizes).
+    expect(body?.textContent).toContain('Find files')
     expect(body?.textContent).toContain('12,345')
     // Rough first scan → no progress bar.
     expect(body?.querySelector('[role="progressbar"]')).toBeNull()
@@ -173,6 +191,16 @@ describe('DriveIndexBadge scanning tooltip', () => {
     expect(body?.querySelector('[role="progressbar"]')).not.toBeNull()
   })
 
+  it('renders the checklist from the phase alone when there is no live activity (reconcile / pre-tick)', () => {
+    badgeActivity = undefined
+    badgePhase = 'scanning'
+    const { target } = render(makeStatus({ freshness: 'scanning' }))
+    // A phase but no activity yet: the body still renders (off a placeholder), so
+    // the checklist stays visible instead of falling back to the static phrase.
+    expect(target.querySelector('.scan-tooltip-body')).not.toBeNull()
+    expect(target.querySelector('.scan-tooltip-body')?.textContent).toContain('Find files')
+  })
+
   it('does not render the rich body when the badge is not scanning', () => {
     badgeActivity = scanActivity()
     const { target } = render(makeStatus({ freshness: 'fresh' }))

apps/desktop/src/lib/indexing/CLAUDE.md

@@ -11,14 +11,15 @@ indicator. Rust counterpart: `apps/desktop/src-tauri/src/indexing/`.
   Tauri index events.
 - **`index-events.ts`**: listens for `index-dir-updated`, calls back with updated paths.
 - **`eta.ts`**: pure ETA helpers + `computeScanProgress` (two-tier scan fraction).
+- **`indexing-steps.ts`**: pure, unit-tested step-checklist derivation (`deriveSteps`) + the step/sub-phase label maps.
 - **`elapsed.ts`**: pure `formatElapsedClock` (`m:ss`, `null` under 1s) — the first-scan elapsed clock, used by the
   shared `IndexingStatusBody` (so both the corner indicator and the badge tooltip show it from one source).
-- **`IndexingStatusIndicator.svelte`** + **`IndexingDriveRow.svelte`** + **`IndexingStatusBody.svelte`**: top-right
-  hourglass shown whenever ANY drive is indexing; tooltip lists one `IndexingDriveRow` per active drive.
-  `IndexingStatusBody` is the shared, PRESENTATIONAL status body (label / counters+elapsed / detail / bar+percent+ETA);
-  `IndexingDriveRow` is the thin WRAPPER (heading + body + its own ETA sliding windows + the 1 Hz tick). The breadcrumb
-  badge's scanning tooltip renders the SAME `IndexingDriveRow` (heading off) for its one volume, so both surfaces show
-  one representation.
+- **The status surface** (`IndexingStatusIndicator` / `IndexingDriveRow` / `IndexingStatusBody` /
+  `IndexingDriveSummary`): the top-right hourglass shown whenever ANY drive is indexing. `IndexingStatusBody` is the
+  shared PRESENTATIONAL per-volume step checklist; `IndexingDriveRow` the thin WRAPPER (heading + body + ETA windows +
+  1 Hz tick). The corner expands the primary drive and collapses each secondary to a one-line `IndexingDriveSummary`;
+  the breadcrumb badge renders the same `IndexingDriveRow`. One representation everywhere. DETAILS § Step checklist.
+- **`indexing-steps.ts`**: pure `deriveSteps` (the checklist's per-volume step states) + the step/sub-phase label maps.
 - **`drive-index-prefs.ts`**: FE-OWNED persisted prefs the backend never reads: per-drive "don't ask again" silences
   (D6) and the one-time stale-dialog flag (D2), stored as hidden settings.
 - **`first-connect-trigger.ts`** + **`FirstConnectIndexToastContent.svelte`**: the first-connect "index this drive?"
@@ -40,12 +41,18 @@ indicator. Rust counterpart: `apps/desktop/src-tauri/src/indexing/`.
 - **Scan progress has two tiers** (`computeScanProgress`). Each tier uses a specific counter as both the numerator and
   the ETA window sample — don't mix them (swapping counter and denominator ships wrong ETAs). Details and clamping
   values: DETAILS.md.
-- **The indicator tracks ALL drives** via a per-volume `activity` map keyed by `volumeId`. Aggregation is per-volume
-  too (its own map). State model, attribution, and the API: [DETAILS.md](DETAILS.md).
-- **`index-state` is the SINGLE source of live activity** (scan/replay counters + aggregation), keyed by `volumeId`.
-  The breadcrumb badge reads its own volume's via `getVolumeActivity(volumeId)` to render the shared body; the badge's
+- **The indicator tracks ALL drives** via a per-volume `activity` map keyed by `volumeId`. Aggregation is per-volume too
+  (its own map). State model, attribution, and the API: [DETAILS.md](DETAILS.md).
+- **`index-state` is the SINGLE source of live activity** (scan/replay counters + aggregation), keyed by `volumeId`. The
+  breadcrumb badge reads its own volume's via `getVolumeActivity(volumeId)` to render the shared body; the badge's
   `drive-index-manager` owns ONLY freshness/menu facts (the dot color, last-scan facts), never live progress. Don't
   reintroduce a second live-count path.
+- **Checklist STEPS are composed from the events that fire for THIS volume** (`deriveSteps`), never a fixed list: a
+  network (SMB/MTP) scan omits Save and Catch-up; a roll-on collapses to one Update step. Branch on typed discriminants
+  only. Per-step ETA only; NO overall ETA by design (deferred — `docs/specs/later/drive-index-overall-eta.md`). The
+  catch-up (reconcile) step has ONLY the `phase` event, so the visibility gate (`isAnyVolumeIndexing`) and the
+  indicator/badge must include `phase`-only volumes (`getActivePhaseVolumeIds`) or the surface vanishes the moment
+  aggregation completes and the step never shows. Full step model + composition: DETAILS § Step checklist.
 - **A keyed entry is cleared by a TERMINAL event**, never by freshness. Scan → `index-scan-complete`; replay →
   `index-replay-complete`; aggregation → `index-aggregation-complete`. A network (SMB/MTP) scan that aborts
   (disconnect/cancel/timeout) fires NO completion, so the backend emits `index-scan-aborted { volumeId }` and
@@ -66,5 +73,6 @@ indicator. Rust counterpart: `apps/desktop/src-tauri/src/indexing/`.
   `getDirSizeDisplayState` (`views/full-list-utils.ts`) is the single source of truth, consumed in lockstep by
   `FullList` / `SelectionInfo` / `measure-column-widths`. Rendering + sort: [DETAILS.md](DETAILS.md).
 
-Full public API, the eight-event table, tooltip content per state, ETA blending, dependencies, and tests:
-[DETAILS.md](DETAILS.md). Read it before any non-trivial work here: editing, planning, reorganizing, or advising.
+Full public API, the ten-event table, the step model + per-volume composition, tooltip content per state, ETA blending,
+dependencies, and tests: [DETAILS.md](DETAILS.md). Read it before any non-trivial work here: editing, planning,
+reorganizing, or advising.