MTP: explain why a phone's folders add up to less than the used space

On a phone reached over USB (MTP), the disk-space readout reports the whole userdata partition (47.67 GB used on one Redmi 9), but Cmdr can only browse the shared-storage subtree (~5.5 GB of folders). Apps and system data make up the rest and aren't reachable over MTP, so the numbers look impossible to reconcile and read as a Cmdr bug. Now a hover hint explains the gap.

- `formatBarTooltip` takes an optional `mtpHint`, appended after the size/level sentences. Pure, TDD'd (`disk-space-utils.test.ts`).
- The hint shows on BOTH surfaces that display the figure: the disk-usage bar tooltip and the visible free-space text in `SelectionInfo` (the number users actually read). Gated on `caps.kind === 'mtp'` per A6 (not a volume-id string), via a new `mtpSpaceHint` prop from `FilePane`.
- New catalog key `fileExplorer.navigation.spaceMtpHint` with a translator `@key` description, translated into all nine shipped locales (de, es, fr, hu, nl, pt, sv, vi, zh) against their style guides; "Cmdr" and "USB" preserved. i18n coverage/parity/ICU green.

Author: vdavid

apps/desktop/src/lib/file-explorer/disk-space-utils.test.ts

@@ -172,4 +172,23 @@ describe('formatBarTooltip', () => {
     const customFormat = (bytes: number): string => `${String(Math.round(bytes / 1073741824))} GB`
     expect(formatBarTooltip(space, customFormat)).toBe('1 GB of 1 GB free (50%)')
   })
+
+  it('appends the extra hint after the sizes when space is OK', () => {
+    const space = createSpace(1000, 400) // 60% used
+    expect(formatBarTooltip(space, mockFormatSize, 'Phones hide app data.')).toBe(
+      '400 B of 1000 B free (40%). Phones hide app data.',
+    )
+  })
+
+  it('appends the extra hint after a low-space warning', () => {
+    const space = createSpace(1000, 100) // 90% used → yellow
+    expect(formatBarTooltip(space, mockFormatSize, 'Phones hide app data.')).toBe(
+      '100 B of 1000 B free (10%). This bar is yellow to indicate that the volume is somewhat low on space. Phones hide app data.',
+    )
+  })
+
+  it('omits the hint when none is provided', () => {
+    const space = createSpace(1000, 400)
+    expect(formatBarTooltip(space, mockFormatSize, undefined)).toBe('400 B of 1000 B free (40%)')
+  })
 })

apps/desktop/src/lib/file-explorer/disk-space-utils.ts

@@ -36,16 +36,24 @@ export function formatDiskSpaceShort(space: VolumeSpaceInfo, formatSize: FormatS
   return `${freeText} free of ${totalText}`
 }
 
-/** Formats the usage bar tooltip: sizes, percentage, and a contextual warning when space is low. */
-export function formatBarTooltip(space: VolumeSpaceInfo, formatSize: FormatSize): string {
+/**
+ * Formats the usage bar tooltip: sizes, percentage, a contextual warning when
+ * space is low, and an optional trailing hint. `mtpHint` carries the
+ * phone-storage explanation (resolved from the message catalog by the caller)
+ * for MTP volumes, where the browsable folders add up to less than the used
+ * space because apps and system data aren't reachable over USB.
+ */
+export function formatBarTooltip(space: VolumeSpaceInfo, formatSize: FormatSize, mtpHint?: string): string {
   const freeText = formatSize(space.availableBytes)
   const totalText = formatSize(space.totalBytes)
   const usedPercent = getUsedPercent(space)
   const freePercent = 100 - usedPercent
   const level = getDiskUsageLevel(usedPercent)
+  const sentences: string[] = []
+  if (level.label === 'Critical') sentences.push('This bar is red to indicate that the volume is low on space.')
+  else if (level.label === 'Warning')
+    sentences.push('This bar is yellow to indicate that the volume is somewhat low on space.')
+  if (mtpHint) sentences.push(mtpHint)
   const base = `${freeText} of ${totalText} free (${String(freePercent)}%)`
-  if (level.label === 'Critical') return `${base}. This bar is red to indicate that the volume is low on space.`
-  if (level.label === 'Warning')
-    return `${base}. This bar is yellow to indicate that the volume is somewhat low on space.`
-  return base
+  return sentences.length > 0 ? `${base}. ${sentences.join(' ')}` : base
 }

apps/desktop/src/lib/file-explorer/pane/FilePane.svelte

@@ -302,6 +302,14 @@
      */
     const isSearchResultsView = $derived(caps.kind === 'search-results')
 
+    /**
+     * The phone-storage caveat for the disk-space readout, only on MTP volumes
+     * (keyed on `caps.kind`, not a volume-id string, per A6). Over USB a phone
+     * exposes only its shared storage, so the browsable folders add up to far
+     * less than the space reported as used; this explains the gap on hover.
+     */
+    const mtpSpaceHint = $derived(caps.kind === 'mtp' ? tString('fileExplorer.navigation.spaceMtpHint') : undefined)
+
     /**
      * Snapshot id encoded in `currentPath` for the search-results pane (`search-results://<id>`),
      * or `null` for any other pane / unparseable path. Drives the breadcrumb label, the
@@ -2929,12 +2937,13 @@
             stats={listingStats}
             selectedCount={selection.selectedIndices.size}
             {volumeSpace}
+            {mtpSpaceHint}
         />
         <!--suppress HtmlWrongAttributeValue -- We know this is not a valid ARIA role, it's fine -->
         <div
             class="disk-usage-bar-wrapper"
             use:tooltip={volumeSpace
-                ? { text: formatBarTooltip(volumeSpace, (b) => formatFileSizeWithFormat(b, getFileSizeFormat())) }
+                ? { text: formatBarTooltip(volumeSpace, (b) => formatFileSizeWithFormat(b, getFileSizeFormat()), mtpSpaceHint) }
                 : ''}
         >
             <div

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

@@ -41,8 +41,10 @@ lives in `FilePane.svelte` as a `Set<number>`).
   briefly after a theme/accent change clears the cache) and swaps seamlessly to the live accent-tinted OS icon once
   `get_icons` populates the cache. The component subscribes to `$iconCacheVersion` to re-render then.
 
-## Symlink and stale-size hints (`SelectionInfo`)
+## Status-bar hints (`SelectionInfo`)
 
+- **Phone-storage hint (MTP)** tooltips the free-space readout on `caps.kind === 'mtp'` volumes (`mtpSpaceHint` from
+  `FilePane`), explaining the folders-vs-used-space gap. See [DETAILS.md](DETAILS.md).
 - **Stale (hourglass) indicator** appears when directory sizes may be incomplete: in `selection-summary` mode while
   `isScanning()` and dirs are selected, and in `file-info` mode via the shared `getDirSizeDisplayState(...)` (the same
   decider FullList uses, so Brief's status bar matches Full's size column). File sizes come from metadata and are always

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

@@ -54,6 +54,20 @@ Other layout: filename truncation uses `useShortenMiddle` with `preferBreakAt: '
 `measureDateColumnWidth(formatDateTime)` to stay in sync with FullList; `formatDateTime` comes from
 `reactive-settings.svelte`.
 
+## Phone-storage hint (MTP)
+
+On a phone reached over USB (MTP), the disk-space readout reports the whole device userdata partition, but Cmdr can only
+browse the shared-storage subtree; apps and system data make up the rest and aren't reachable over MTP. So the visible
+folders add up to far less than the space reported as used, which reads as a Cmdr bug. A hover hint closes that gap.
+
+- The copy lives in `fileExplorer.navigation.spaceMtpHint`. `FilePane` resolves it to the `mtpSpaceHint` prop only when
+  `caps.kind === 'mtp'` (the A6-correct discriminant, not a volume-id string); it's `undefined` for every other kind.
+- Both surfaces that show the figure carry it: `SelectionInfo` tooltips the visible free-space text (the number users
+  read), and `FilePane` passes the same string as the third arg of `formatBarTooltip` for the disk-usage bar, appended
+  after the size/level sentences. One catalog key, so the two never drift.
+- It rides on `use:tooltip`, so it's hover-only: a touch/keyboard user reading the footer text never sees it. Making the
+  footer text itself focusable is the honest a11y fix if that matters later.
+
 ## `FileIcon.svelte`
 
 Props: `file: FileEntry`, `syncIcon?: string` (URL for sync overlay badge).

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

@@ -57,9 +57,15 @@
         selectedCount: number
         /** Disk space info for current volume (null when unavailable) */
         volumeSpace?: VolumeSpaceInfo | null
+        /**
+         * Phone-storage caveat for the disk-space readout, set only on MTP
+         * volumes. When present, it tooltips the free/total text to explain why
+         * the browsable folders add up to less than the used space.
+         */
+        mtpSpaceHint?: string
     }
 
-    const { viewMode, entry, currentDirModifiedAt, stats, selectedCount, volumeSpace }: Props = $props()
+    const { viewMode, entry, currentDirModifiedAt, stats, selectedCount, volumeSpace, mtpSpaceHint }: Props = $props()
 
     // ========================================================================
     // Display mode determination
@@ -243,7 +249,7 @@
     {#if displayMode === 'empty'}
         <span class="summary-text">{tString('fileExplorer.selectionInfo.nothingHere')}</span>
         {#if volumeSpace}
-            <span class="disk-space-text">{diskSpaceStatusText(volumeSpace)}</span>
+            <span class="disk-space-text" use:tooltip={mtpSpaceHint ?? ''}>{diskSpaceStatusText(volumeSpace)}</span>
         {/if}
     {:else if displayMode === 'file-info' && entry}
         <!-- Brief mode without selection: show file info -->
@@ -297,13 +303,13 @@
             {#if datePlaceholder !== null}{datePlaceholder}{:else}<DateLabel modifiedAt={dateTimestamp} />{/if}
         </span>
         {#if volumeSpace}
-            <span class="disk-space-text">{diskSpaceStatusText(volumeSpace)}</span>
+            <span class="disk-space-text" use:tooltip={mtpSpaceHint ?? ''}>{diskSpaceStatusText(volumeSpace)}</span>
         {/if}
     {:else if displayMode === 'no-selection'}
         <!-- Full mode without selection: show totals -->
         <span class="summary-text">{noSelectionText}</span>
         {#if volumeSpace}
-            <span class="disk-space-text">{diskSpaceStatusText(volumeSpace)}</span>
+            <span class="disk-space-text" use:tooltip={mtpSpaceHint ?? ''}>{diskSpaceStatusText(volumeSpace)}</span>
         {/if}
     {:else if displayMode === 'selection-summary' && stats}
         <!-- Selection summary -->

apps/desktop/src/lib/intl/keys.gen.ts

@@ -824,6 +824,7 @@ export type MessageKey =
   | 'fileExplorer.navigation.reorderFavoritesFailed'
   | 'fileExplorer.navigation.searchResultsVolume'
   | 'fileExplorer.navigation.spaceFetchFailed'
+  | 'fileExplorer.navigation.spaceMtpHint'
   | 'fileExplorer.navigation.spaceRetrying'
   | 'fileExplorer.navigation.spaceRetryingAuto'
   | 'fileExplorer.navigation.spaceRetryingText'

apps/desktop/src/lib/intl/messages/de/fileExplorer.json

@@ -1177,6 +1177,10 @@
   "@fileExplorer.navigation.spaceUnavailableText": {
     "sourceHash": "ca18449"
   },
+  "fileExplorer.navigation.spaceMtpHint": "Auf einem Smartphone zählen hier auch Apps und Systemdateien mit. Über USB erreicht Cmdr nur deine freigegebenen Dateien, daher ergeben die Ordner hier zusammen weniger als der belegte Speicherplatz.",
+  "@fileExplorer.navigation.spaceMtpHint": {
+    "sourceHash": "43ec861"
+  },
   "fileExplorer.navigation.volumesStillUnreachable": "Weiterhin nicht erreichbar. Versuche es später erneut",
   "@fileExplorer.navigation.volumesStillUnreachable": {
     "sourceHash": "e4661d2"

apps/desktop/src/lib/intl/messages/en/fileExplorer.json

@@ -1725,6 +1725,10 @@
   "@fileExplorer.navigation.spaceUnavailableText": {
     "description": "Short inline text shown in place of a volume''s disk-space figure when its free space couldn''t be fetched. Tight space; keep it short."
   },
+  "fileExplorer.navigation.spaceMtpHint": "On a phone, this also counts apps and system files. Over USB, Cmdr can reach only your shared files, so the folders here add up to less than the used space.",
+  "@fileExplorer.navigation.spaceMtpHint": {
+    "description": "Hover tooltip on a connected phone''s disk-space readout (the free/total figure and its usage bar), shown only for phones reached over USB (MTP). Explains why the visible folders add up to far less than the space reported as used: a phone''s apps and system data count toward usage but can''t be browsed over USB. \"USB\" is the cable connection; \"Cmdr\" is the app name (do not translate)."
+  },
 
   "fileExplorer.navigation.volumesStillUnreachable": "Still unreachable. Try again later",
   "@fileExplorer.navigation.volumesStillUnreachable": {

apps/desktop/src/lib/intl/messages/es/fileExplorer.json

@@ -1171,6 +1171,10 @@
   "@fileExplorer.navigation.spaceUnavailableText": {
     "sourceHash": "ca18449"
   },
+  "fileExplorer.navigation.spaceMtpHint": "En un teléfono, esto también incluye apps y archivos del sistema. Por USB, Cmdr solo puede acceder a tus archivos compartidos, así que las carpetas que ves aquí suman menos que el espacio usado.",
+  "@fileExplorer.navigation.spaceMtpHint": {
+    "sourceHash": "43ec861"
+  },
   "fileExplorer.navigation.volumesStillUnreachable": "Sigue sin poder accederse. Inténtalo de nuevo más tarde",
   "@fileExplorer.navigation.volumesStillUnreachable": {
     "sourceHash": "e4661d2"