P4-6: Files-on-demand UI and setup flow #49

New issue

Open

opened 2026-09-10 18:10:28 +00:00 by Cordy · 0 comments

Cordy commented

2026-09-10 18:10:28 +00:00

Owner

Depends on P4-5.

Goal

Make hydration state and disk usage legible, and let the user control both without reading
documentation.

Files

Modify: internal/app/status.go, internal/app/setup.go, frontend/*
Create: frontend/storage.*

Setup wizard changes (P3-4)

Files-on-demand changes the first question the wizard asks. Offer the choice explicitly:

"Keep everything on this device" — classic sync. Best when the Cairn fits comfortably.
"Save space — download files as you open them" — files-on-demand. Show the difference in
concrete numbers: "Your Cairn is 2.1 TB. This device has 180 GB free."

Making it a real choice with real numbers is what stops people picking the wrong one and then
filling their disk.

macOS is different and the wizard must say so. With files-on-demand enabled, macOS places
the domain in Finder's sidebar rather than at a folder path the user chooses (P4-3). Do not
pretend the platforms behave identically — explain it in one sentence.

Status window

Local usage vs Cairn total: "180 GB of 2.1 TB kept on this device."
"Free up space" button (P4-5), showing how much would be reclaimed before doing it.
Per-file state where the file list appears: available online only · downloading · available
offline · pinned.

Pin controls

Right-click / context menu: Always keep on this device ↔ Free up space.
On Windows, map to the native Explorer menu items rather than adding a parallel set —
users already know them from OneDrive.
On macOS, use the Finder integration the File Provider gives you.

Hydration feedback

Progress for large downloads, with cancel.
If a hydration fails — offline, quota, auth expired — say so at the file, and do not
leave a zero-byte file behind. A truncated file that opens and shows nothing is worse than a
clear failure.

Offline behaviour

This is the sharp edge of the whole feature. When the device is offline, placeholders cannot
be opened.

Detect offline and say so plainly: "You're offline. This file isn't downloaded yet."
Never present it as corruption or a sync bug.
Suggest the fix: pin the files you need before travelling.
Consider a "make available offline" bulk action for a folder — this is the feature people ask
for immediately after their first flight.

Steps

Add the wizard choice with real size numbers.
Add local-usage display and "free up space".
Add pin controls, mapped to native menus per platform.
Add hydration progress, cancellation and failure states.
Add offline messaging.
Add all new strings to the four i18n catalogues (#41).
Commit: git commit -s -m "feat(app): files-on-demand UI and setup flow"

Acceptance criteria

The user chooses the mode during setup, with real numbers.
Hydration state is visible per file.
A failed hydration never leaves a zero-byte file.
Offline placeholder access produces a clear explanation, not an error code.
All strings are translated.

Depends on P4-5. ## Goal Make hydration state and disk usage legible, and let the user control both without reading documentation. ## Files - Modify: `internal/app/status.go`, `internal/app/setup.go`, `frontend/*` - Create: `frontend/storage.*` ## Setup wizard changes (P3-4) Files-on-demand changes the first question the wizard asks. Offer the choice explicitly: - **"Keep everything on this device"** — classic sync. Best when the Cairn fits comfortably. - **"Save space — download files as you open them"** — files-on-demand. Show the difference in concrete numbers: *"Your Cairn is 2.1 TB. This device has 180 GB free."* Making it a real choice with real numbers is what stops people picking the wrong one and then filling their disk. **macOS is different and the wizard must say so.** With files-on-demand enabled, macOS places the domain in Finder's sidebar rather than at a folder path the user chooses (P4-3). Do not pretend the platforms behave identically — explain it in one sentence. ## Status window - **Local usage vs Cairn total:** "180 GB of 2.1 TB kept on this device." - **"Free up space"** button (P4-5), showing how much would be reclaimed before doing it. - Per-file state where the file list appears: available online only · downloading · available offline · pinned. ## Pin controls - Right-click / context menu: **Always keep on this device** ↔ **Free up space**. - On Windows, map to the native Explorer menu items rather than adding a parallel set — users already know them from OneDrive. - On macOS, use the Finder integration the File Provider gives you. ## Hydration feedback - Progress for large downloads, with **cancel**. - If a hydration fails — offline, quota, auth expired — say so **at the file**, and do not leave a zero-byte file behind. A truncated file that opens and shows nothing is worse than a clear failure. ## Offline behaviour This is the sharp edge of the whole feature. When the device is offline, placeholders **cannot** be opened. - Detect offline and say so plainly: *"You're offline. This file isn't downloaded yet."* - Never present it as corruption or a sync bug. - Suggest the fix: pin the files you need before travelling. - Consider a "make available offline" bulk action for a folder — this is the feature people ask for immediately after their first flight. ## Steps - [ ] Add the wizard choice with real size numbers. - [ ] Add local-usage display and "free up space". - [ ] Add pin controls, mapped to native menus per platform. - [ ] Add hydration progress, cancellation and failure states. - [ ] Add offline messaging. - [ ] Add all new strings to the four i18n catalogues (#41). - [ ] Commit: `git commit -s -m "feat(app): files-on-demand UI and setup flow"` ## Acceptance criteria - The user chooses the mode during setup, with real numbers. - Hydration state is visible per file. - A failed hydration never leaves a zero-byte file. - Offline placeholder access produces a clear explanation, not an error code. - All strings are translated.