File explorer: Toggle for human-friendly size units

Some users prefer "1.02 MB" for legibility, others prefer raw bytes for precise comparison. Add a Settings > Listing toggle to flip between them. Default ON.

- New `listing.humanFriendlySizeUnits` boolean setting (default `true`). Sentence-case label, description "On: shows 1.02 MB. Off: shows raw bytes for precise comparison."
- Reactive getter + subscribe pattern in `reactive-settings.svelte.ts`, mirroring `stripedRows`. Also exposed `getFileSizeFormat()`.
- Shared `formatSizeForDisplay(bytes, { humanFriendly, format })` in `selection-info-utils.ts` returning `{ value, tierClass }[]`. Human-friendly mode returns one tier-tagged span; raw mode delegates to existing `formatSizeTriads()`. New `tierClassForUnit()` maps `bytes/KB/MB/GB/TB` to existing color classes — no new tokens.
- Threaded the toggle through every bytes-only readout:
  - `FullList.svelte`: dir + file size cells
  - `SelectionInfo.svelte`: file-info mode size, plus selection-summary `selectedSizeTriads` and `totalSizeTriads`
  - `measure-column-widths.ts`: size column width measurement reads the same options so the column shrink-wraps the actually-rendered text
- Untouched on purpose: tooltips that show both formats (`buildFileSizeTooltip`, `buildDirSizeTooltip`, `buildSelectionSizeTooltip`); volume/disk space; dialogs; search results; drive-indexing section. Those already use human-friendly only or display both — flipping them would worsen UX.
- Tests: 11 new cases in `selection-info-utils.test.ts` (tier mapping, both modes, binary/SI boundaries, sub-KB through TB). 1 new `measure-column-widths` case. Updated 3 existing a11y/component tests to mock the new exports.
- Document in `selection/CLAUDE.md`, `views/CLAUDE.md`, `settings/CLAUDE.md`.

Author: vdavid

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

@@ -20,6 +20,12 @@ Exported functions:
 
 - `formatSizeTriads(bytes)` — splits byte count into digit triads, each tagged with a `tierClass`. Uses U+2009
   thin-space as separator between triads.
+- `formatSizeForDisplay(bytes, { humanFriendly, format })` — single entry point used by views and the status bar to
+  render byte counts. In raw-bytes mode delegates to `formatSizeTriads`. In human-friendly mode returns one tier-tagged
+  span like `{ value: '1.02 MB', tierClass: 'size-mb' }`. The tier is picked from the chosen unit via
+  `tierClassForUnit`, so coloring stays consistent with the triad mode.
+- `tierClassForUnit(unit)` — maps the unit suffix from `formatFileSizeWithFormat` (`bytes`, `KB`/`kB`, `MB`, `GB`, `TB`,
+  `PB`) to one of `sizeTierClasses`. TB and PB cap at `size-tb`.
 - `formatDate(timestamp)` — Unix seconds → `"YYYY-MM-DD HH:MM:SS"` local time.
 - `buildDateTooltip(entry)` — multiline string with created/opened/added/modified dates.
 - `getSizeDisplay(entry, isBrokenSymlink, isPermissionDenied)` — returns triads array, `'DIR'`, or `null`.
@@ -84,9 +90,13 @@ every unsorted header. Handles both `onclick` and `onkeydown` (Enter/Space).
 
 ## Key decisions
 
-**Decision**: Size displayed as raw byte count with colored digit triads, not as human-readable "1.23 MB" **Why**:
-Human-readable values lose precision and make it impossible to compare similarly-sized files. Triads with tier-based CSS
-coloring (bytes/KB/MB/GB/TB) give both precision and quick visual scanning. Human-readable is available as a tooltip.
+**Decision**: Size column / status bar primary readout follows the `listing.humanFriendlySizeUnits` toggle. ON (default)
+shows "1.02 MB" via `formatFileSizeWithFormat`. OFF shows colored digit triads via `formatSizeTriads`. Both modes flow
+through the shared `formatSizeForDisplay` helper. **Why**: Human-readable is friendlier for most users, but power users
+(and David) want precise byte counts to compare similarly-sized files. The tier-based CSS coloring
+(`size-bytes`/`size-kb`/`size-mb`/`size-gb`/`size-tb`) is preserved in both modes — in human-friendly mode the entire
+formatted string takes the tier of its chosen unit. Tooltips on file/dir/selection size still always show both formats
+so the other one is always one hover away.
 
 **Decision**: Middle truncation in `file-info` mode uses the `useShortenMiddle` Svelte action (from `$lib/utils/`) with
 `preferBreakAt: '.'` and `startRatio: 0.7`, not CSS `text-overflow: ellipsis` **Why**: CSS ellipsis truncates from the

apps/desktop/src/lib/file-explorer/selection/SelectionInfo.a11y.test.ts

@@ -19,6 +19,8 @@ vi.mock('$lib/settings/reactive-settings.svelte', () => ({
   formatFileSize: (n: number) => `${String(n)} B`,
   formatDateTime: (t: number | undefined) => (t ? '2025-03-14 10:30' : ''),
   getSizeDisplayMode: () => 'smart',
+  getHumanFriendlySizeUnits: () => false,
+  getFileSizeFormat: () => 'binary',
 }))
 
 const entry = {

apps/desktop/src/lib/file-explorer/selection/SelectionInfo.svelte

@@ -7,13 +7,19 @@
         getSizeDisplay,
         isBrokenSymlink as checkBrokenSymlink,
         isPermissionDenied as checkPermissionDenied,
-        formatSizeTriads,
+        formatSizeForDisplay,
         pluralize,
         formatNumber,
         calculatePercentage,
     } from './selection-info-utils'
     import { measureDateColumnWidth } from '../views/full-list-utils'
-    import { formatFileSize, formatDateTime, getSizeDisplayMode } from '$lib/settings/reactive-settings.svelte'
+    import {
+        formatFileSize,
+        formatDateTime,
+        getSizeDisplayMode,
+        getHumanFriendlySizeUnits,
+        getFileSizeFormat,
+    } from '$lib/settings/reactive-settings.svelte'
     import {
         getDisplaySize,
         buildFileSizeTooltip,
@@ -77,6 +83,10 @@
     const scanning = $derived(isScanning())
 
     const sizeDisplayMode = $derived(getSizeDisplayMode())
+    const sizeFormatOpts = $derived({
+        humanFriendly: getHumanFriendlySizeUnits(),
+        format: getFileSizeFormat(),
+    })
     const displayName = $derived(entry?.name ?? '')
     const isDirectory = $derived(entry?.isDirectory ?? false)
     const isBrokenSymlink = $derived(checkBrokenSymlink(entry))
@@ -90,7 +100,9 @@
               )
             : undefined,
     )
-    const sizeDisplay = $derived(getSizeDisplay(entry, isBrokenSymlink, isPermissionDenied, displaySize))
+    const sizeDisplay = $derived(
+        getSizeDisplay(entry, isBrokenSymlink, isPermissionDenied, displaySize, sizeFormatOpts),
+    )
     const sizeTooltip = $derived(
         entry
             ? isDirectory
@@ -172,9 +184,9 @@
 
     const sizePercentage = $derived(calculatePercentage(selectedSize, totalSize))
 
-    // Size triads for selection summary
-    const selectedSizeTriads = $derived(formatSizeTriads(selectedSize))
-    const totalSizeTriads = $derived(formatSizeTriads(totalSize))
+    // Size display for selection summary (triads in raw mode, single span in human-friendly mode)
+    const selectedSizeTriads = $derived(formatSizeForDisplay(selectedSize, sizeFormatOpts))
+    const totalSizeTriads = $derived(formatSizeForDisplay(totalSize, sizeFormatOpts))
 
     // Tooltip shows human-readable sizes; includes both content and on-disk when they differ
     const selectionSizeTooltip = $derived(

apps/desktop/src/lib/file-explorer/selection/SelectionInfo.symlink-hint.test.ts

@@ -19,6 +19,8 @@ vi.mock('$lib/settings/reactive-settings.svelte', () => ({
   formatFileSize: (n: number) => `${String(n)} B`,
   formatDateTime: (t: number | undefined) => (t ? '2025-03-14 10:30' : ''),
   getSizeDisplayMode: () => 'smart',
+  getHumanFriendlySizeUnits: () => false,
+  getFileSizeFormat: () => 'binary',
 }))
 
 function makeDir(overrides: Partial<Record<string, unknown>> = {}) {

apps/desktop/src/lib/file-explorer/selection/selection-info-utils.test.ts

@@ -4,6 +4,8 @@
 import { describe, it, expect } from 'vitest'
 import {
   formatSizeTriads,
+  formatSizeForDisplay,
+  tierClassForUnit,
   formatDate,
   buildDateTooltip,
   getSizeDisplay,
@@ -306,6 +308,97 @@ describe('sizeTierClasses', () => {
   })
 })
 
+describe('tierClassForUnit', () => {
+  it('maps bytes to size-bytes', () => {
+    expect(tierClassForUnit('bytes')).toBe('size-bytes')
+  })
+
+  it('maps KB and kB to size-kb', () => {
+    expect(tierClassForUnit('KB')).toBe('size-kb')
+    expect(tierClassForUnit('kB')).toBe('size-kb')
+  })
+
+  it('maps MB to size-mb', () => {
+    expect(tierClassForUnit('MB')).toBe('size-mb')
+  })
+
+  it('maps GB to size-gb', () => {
+    expect(tierClassForUnit('GB')).toBe('size-gb')
+  })
+
+  it('maps TB and PB to size-tb (capped)', () => {
+    expect(tierClassForUnit('TB')).toBe('size-tb')
+    expect(tierClassForUnit('PB')).toBe('size-tb')
+  })
+})
+
+describe('formatSizeForDisplay', () => {
+  describe('raw-bytes mode (humanFriendly: false)', () => {
+    it('delegates to formatSizeTriads for small values', () => {
+      const result = formatSizeForDisplay(512, { humanFriendly: false, format: 'binary' })
+      expect(result).toEqual(formatSizeTriads(512))
+    })
+
+    it('delegates to formatSizeTriads for large values', () => {
+      const result = formatSizeForDisplay(1_073_208, { humanFriendly: false, format: 'binary' })
+      expect(result).toEqual(formatSizeTriads(1_073_208))
+      // Sanity-check: matches user's example "1 073 208" (with thin spaces)
+      expect(result.map((t) => t.value).join('')).toBe('1 073 208')
+    })
+
+    it('ignores the format option in raw-bytes mode', () => {
+      const binary = formatSizeForDisplay(1024, { humanFriendly: false, format: 'binary' })
+      const si = formatSizeForDisplay(1024, { humanFriendly: false, format: 'si' })
+      expect(binary).toEqual(si)
+    })
+  })
+
+  describe('human-friendly mode (humanFriendly: true)', () => {
+    it('returns one element with size-bytes for sub-KB binary values', () => {
+      const result = formatSizeForDisplay(512, { humanFriendly: true, format: 'binary' })
+      expect(result).toHaveLength(1)
+      expect(result[0]).toEqual({ value: '512 bytes', tierClass: 'size-bytes' })
+    })
+
+    it('returns size-kb for binary 1024', () => {
+      const result = formatSizeForDisplay(1024, { humanFriendly: true, format: 'binary' })
+      expect(result).toEqual([{ value: '1.00 KB', tierClass: 'size-kb' }])
+    })
+
+    it('returns size-mb for ~1 MB (matches feature spec example "1.02 MB")', () => {
+      const result = formatSizeForDisplay(1_073_208, { humanFriendly: true, format: 'binary' })
+      expect(result).toEqual([{ value: '1.02 MB', tierClass: 'size-mb' }])
+    })
+
+    it('returns size-gb for ~1 GB binary', () => {
+      const result = formatSizeForDisplay(1024 ** 3, { humanFriendly: true, format: 'binary' })
+      expect(result).toEqual([{ value: '1.00 GB', tierClass: 'size-gb' }])
+    })
+
+    it('returns size-tb for TB and beyond', () => {
+      const tb = formatSizeForDisplay(1024 ** 4, { humanFriendly: true, format: 'binary' })
+      const pb = formatSizeForDisplay(1024 ** 5, { humanFriendly: true, format: 'binary' })
+      expect(tb[0].tierClass).toBe('size-tb')
+      expect(pb[0].tierClass).toBe('size-tb')
+    })
+
+    it('boundary: SI 1000 is 1.00 kB (size-kb tier)', () => {
+      const result = formatSizeForDisplay(1000, { humanFriendly: true, format: 'si' })
+      expect(result).toEqual([{ value: '1.00 kB', tierClass: 'size-kb' }])
+    })
+
+    it('boundary: binary 1023 is still bytes', () => {
+      const result = formatSizeForDisplay(1023, { humanFriendly: true, format: 'binary' })
+      expect(result).toEqual([{ value: '1023 bytes', tierClass: 'size-bytes' }])
+    })
+
+    it('SI 1024 is 1.02 kB', () => {
+      const result = formatSizeForDisplay(1024, { humanFriendly: true, format: 'si' })
+      expect(result).toEqual([{ value: '1.02 kB', tierClass: 'size-kb' }])
+    })
+  })
+})
+
 // ============================================================================
 // Selection summary utility tests
 // ============================================================================

apps/desktop/src/lib/file-explorer/selection/selection-info-utils.ts

@@ -4,6 +4,8 @@
  */
 
 import type { FileEntry } from '../types'
+import type { FileSizeFormat } from '$lib/settings/types'
+import { formatFileSizeWithFormat } from '$lib/settings/format-utils'
 
 // Size tier colors for digit triads (indexed: 0=bytes, 1=kB, 2=MB, 3=GB, 4=TB+)
 export const sizeTierClasses = ['size-bytes', 'size-kb', 'size-mb', 'size-gb', 'size-tb']
@@ -35,6 +37,42 @@ export function formatSizeTriads(bytes: number): { value: string; tierClass: str
   }))
 }
 
+/**
+ * Picks a size tier CSS class for a human-friendly size string like
+ * "1.02 MB" or "512 bytes". Returns the closest of `sizeTierClasses` so the
+ * unit-tagged span uses the same coloring as the raw-bytes triad mode.
+ */
+export function tierClassForUnit(unit: string): string {
+  const lower = unit.toLowerCase()
+  if (lower === 'bytes') return 'size-bytes'
+  if (lower === 'kb') return 'size-kb' // matches KB (binary) and kB (SI)
+  if (lower === 'mb') return 'size-mb'
+  if (lower === 'gb') return 'size-gb'
+  // TB, PB and anything beyond fall back to the highest defined tier
+  return 'size-tb'
+}
+
+/**
+ * Formats a byte count for display in views/status bar based on the user's
+ * "human-friendly size units" preference. Returns an array of tier-tagged
+ * spans:
+ * - In human-friendly mode, returns one element like `{ value: '1.02 MB', tierClass: 'size-mb' }`.
+ * - In raw-bytes mode, delegates to {@link formatSizeTriads} which returns one element per digit triad.
+ */
+export function formatSizeForDisplay(
+  bytes: number,
+  opts: { humanFriendly: boolean; format: FileSizeFormat },
+): { value: string; tierClass: string }[] {
+  if (!opts.humanFriendly) {
+    return formatSizeTriads(bytes)
+  }
+  const formatted = formatFileSizeWithFormat(bytes, opts.format)
+  // The formatter returns "<value> <unit>"; the unit is the last whitespace-separated token.
+  const spaceIndex = formatted.lastIndexOf(' ')
+  const unit = spaceIndex >= 0 ? formatted.slice(spaceIndex + 1) : ''
+  return [{ value: formatted, tierClass: tierClassForUnit(unit) }]
+}
+
 /** Formats timestamp as YYYY-MM-DD hh:mm:ss */
 export function formatDate(timestamp: number | undefined): string {
   if (timestamp === undefined) return ''
@@ -65,12 +103,14 @@ export function getSizeDisplay(
   isBrokenSymlink: boolean,
   isPermissionDenied: boolean,
   displaySize?: number,
+  formatOpts?: { humanFriendly: boolean; format: FileSizeFormat },
 ): { value: string; tierClass: string }[] | 'DIR' | null {
   if (!entry || isBrokenSymlink || isPermissionDenied) return null
-  if (entry.isDirectory) return displaySize !== undefined ? formatSizeTriads(displaySize) : 'DIR'
+  const opts = formatOpts ?? { humanFriendly: false, format: 'binary' as const }
+  if (entry.isDirectory) return displaySize !== undefined ? formatSizeForDisplay(displaySize, opts) : 'DIR'
   const size = displaySize ?? entry.size
   if (size === undefined) return null
-  return formatSizeTriads(size)
+  return formatSizeForDisplay(size, opts)
 }
 
 /** Determines date display for an entry */

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

@@ -19,10 +19,14 @@ without DOM performance issues.
   FullList transitions `grid-template-columns` over 300ms so widths refine smoothly as more entries stream in.
 - **measure-brief-column-widths.ts** – `measureWidestFilename()`: widest filename's pixel width in a Brief column,
   measured via pretext. Caller adds icon/gap/padding chrome and clamps to the min/max column-width range.
-- **FullList.svelte** – Reads `listing.sizeDisplay` (via `getSizeDisplayMode()`) and `listing.sizeMismatchWarning` (via
-  `getSizeMismatchWarning()`) settings. Uses Lucide icons (via `unplugin-icons`): `~icons/lucide/circle-alert` for size
-  mismatch warnings and `~icons/lucide/hourglass` for stale index indicators. Also renders an optional Git status column
-  between Name and Ext when `gitRepoRoot` is set and `showGitColumn` is true (gated by the
+- **FullList.svelte** – Reads `listing.sizeDisplay` (via `getSizeDisplayMode()`), `listing.sizeMismatchWarning` (via
+  `getSizeMismatchWarning()`), and `listing.humanFriendlySizeUnits` (via `getHumanFriendlySizeUnits()`, paired with
+  `getFileSizeFormat()`) settings. Size cells are rendered through `formatSizeForDisplay` from
+  `selection/selection-info-utils.ts`, which delegates to triads in raw-bytes mode and to a single tier-tagged
+  human-friendly string when the toggle is on. `measure-column-widths.ts` accepts the same options so the size column
+  shrink-wraps the actually-rendered cell text. Uses Lucide icons (via `unplugin-icons`): `~icons/lucide/circle-alert`
+  for size mismatch warnings and `~icons/lucide/hourglass` for stale index indicators. Also renders an optional Git
+  status column between Name and Ext when `gitRepoRoot` is set and `showGitColumn` is true (gated by the
   `fileExplorer.git.showStatusColumn` setting in `FilePane`); fetches `fetchStatusMap` and refreshes on
   `git-state-changed` for the active repo
 - **dir-size-display.test.ts** – Tests for `getDirSizeDisplayState` / `buildDirSizeTooltip` (functions in

apps/desktop/src/lib/file-explorer/views/FullList.a11y.test.ts

@@ -42,6 +42,8 @@ vi.mock('$lib/settings/reactive-settings.svelte', () => ({
   getSizeDisplayMode: () => 'smart',
   getSizeMismatchWarning: () => false,
   getStripedRows: () => false,
+  getHumanFriendlySizeUnits: () => false,
+  getFileSizeFormat: () => 'binary',
 }))
 
 vi.mock('$lib/settings/settings-store', () => ({

apps/desktop/src/lib/file-explorer/views/FullList.svelte

@@ -23,7 +23,7 @@
         type DirStats,
     } from './file-list-utils'
     import { getDirStatsBatch } from '$lib/tauri-commands'
-    import { formatSizeTriads, formatNumber, pluralize } from '../selection/selection-info-utils'
+    import { formatSizeForDisplay, formatNumber, pluralize } from '../selection/selection-info-utils'
     import { isScanning, isAggregating } from '$lib/indexing/index-state.svelte'
     import {
         getVisibleItemsCount as getVisibleItemsCountUtil,
@@ -45,6 +45,8 @@
         getSizeDisplayMode,
         getSizeMismatchWarning,
         getStripedRows,
+        getHumanFriendlySizeUnits,
+        getFileSizeFormat,
     } from '$lib/settings/reactive-settings.svelte'
     import { iconCacheCleared } from '$lib/icon-cache'
     import { tooltip } from '$lib/tooltip/tooltip'
@@ -146,6 +148,12 @@
     // Striped rows setting
     const stripedRows = $derived(getStripedRows())
 
+    // Human-friendly vs. raw-bytes size formatting
+    const sizeFormatOpts = $derived({
+        humanFriendly: getHumanFriendlySizeUnits(),
+        format: getFileSizeFormat(),
+    })
+
     // Drive index state — show spinner while scanning OR aggregating (sizes aren't ready until aggregation finishes)
     const indexing = $derived(isScanning() || isAggregating())
 
@@ -237,6 +245,7 @@
             indexing,
             showSizeMismatchWarning,
             sortBy,
+            sizeFormatOpts,
         })
     })
 
@@ -706,7 +715,7 @@
                             {:else if file.isDirectory}
                                 {#if dirDisplaySize !== undefined}
                                     <span class="size-text"
-                                        >{#each formatSizeTriads(dirDisplaySize) as triad, i (i)}<span
+                                        >{#each formatSizeForDisplay(dirDisplaySize, sizeFormatOpts) as triad, i (i)}<span
                                                 class={triad.tierClass}>{triad.value}</span
                                             >{/each}</span
                                     >
@@ -746,7 +755,7 @@
                                 {/if}
                             {:else if fileDisplaySize !== undefined}
                                 <span class="size-text"
-                                    >{#each formatSizeTriads(fileDisplaySize) as triad, i (i)}<span
+                                    >{#each formatSizeForDisplay(fileDisplaySize, sizeFormatOpts) as triad, i (i)}<span
                                             class={triad.tierClass}>{triad.value}</span
                                         >{/each}</span
                                 >

apps/desktop/src/lib/file-explorer/views/measure-column-widths.test.ts

@@ -35,6 +35,7 @@ const baseArgs = {
   indexing: false,
   showSizeMismatchWarning: false,
   sortBy: 'name' as const,
+  sizeFormatOpts: { humanFriendly: false, format: 'binary' as const },
 }
 
 describe('computeFullListColumnWidths', () => {
@@ -140,4 +141,18 @@ describe('computeFullListColumnWidths', () => {
     expect(w.size).toBeGreaterThanOrEqual(40)
     expect(w.date).toBeGreaterThanOrEqual(70)
   })
+
+  it('size column tracks the human-friendly format when enabled', () => {
+    _setMeasureForTests(fakeMeasure)
+    const big = entry({ name: 'z.bin', size: 123_456_789, physicalSize: 123_456_789 })
+    const raw = computeFullListColumnWidths({ ...baseArgs, entries: [big] })
+    const human = computeFullListColumnWidths({
+      ...baseArgs,
+      entries: [big],
+      sizeFormatOpts: { humanFriendly: true, format: 'binary' },
+    })
+    // "123 456 789" (with thin spaces) is 11 visible chars; "117.74 MB" is 9.
+    // With our deterministic length*7 measurer the human-friendly cell is narrower.
+    expect(human.size).toBeLessThan(raw.size)
+  })
 })