utils/dopamine-ux/TODO-08-dufs-motion.md

Give dufs-cloud real latency feedback on its slow operations

## findings (4, ranked by value over effort)

1. **No cancel on the unbounded index walk or the ZIP build** — the real
   usability failure, and worth more than any animation.
2. **Slow operations report one static string** — the walk and the zip both know
   real counts and discard them.
3. **No `prefers-reduced-motion` block anywhere in 806 lines of CSS** — a
   straight accessibility gap.
4. **Long-press multi-select has no haptic** — the canonical place for one.

## what

dufs-cloud has genuinely slow operations and tells the user almost nothing while
they run. Verified 2026-08-16:

- The **recursive cloud index walk** lists every directory in the cloud,
  unbounded. Web shows one static string `"Indexing cloud…"`; Flutter shows one
  indeterminate `CircularProgressIndicator`. **No count, no current path, no
  cancel** on either side.
- The **multi-file ZIP build** downloads every selected file's bytes into memory
  and then zips them, with `setBusy('Preparing N item(s)…')` — a single static
  string for the entire operation. Neither `buildSelectionZip` signature even
  accepts a progress callback.
- Web's entire 806-line `index.css` contains **exactly one transition**
  (`.tile-actions { transition: opacity 0.12s }` ~:539-544), zero `@keyframes`,
  and **no `prefers-reduced-motion` block at all**.
- Flutter side has **zero animations and zero haptics** — notably
  `browser_screen.dart` (~:95) enters multi-select on **long-press** with no
  `HapticFeedback.selectionClick()`, the canonical place for one.

This is the article's micro-animation point in its most defensible form: replace
dead latency with honest, informative feedback. Nothing here needs a manufactured
reward — the operations are genuinely slow and the progress is genuinely knowable.

## where

Repo: `~/src/dufs-cloud`. Web: `web/`. Flutter: `app/` (package `dufs_client`).

**First step — bump both dependencies** to pick up prompt 01's motion tokens:
- `web/package.json`: `"@kuhyx/web-ui": "github:kuhyx/utils#web_ui-v0.3.1&path:/web_ui"`
  → bump to **`web_ui-v0.3.2`** (or whatever tag prompt 01 printed).
  **pnpm only** — npm cannot install a monorepo subdirectory and will lock the repo.
- `app/pubspec.yaml`: bump `design_system` to the tag prompt 01 cut.
  **Prompt 07 must have run first** — it is what adds this dependency at all.

Slow operations (the highest-value targets):
- Index walk — web `web/src/hooks/use-cloud-index.ts` (`walkInto` ~:36-43, root
  walk ~:56-63, `loading` derived ~:113); Flutter
  `app/lib/services/cloud_index.dart` (`buildCloudIndex` ~:25, `_walk` ~:31-41),
  driven by `app/lib/screens/browser_screen.dart` `_ensureIndex()` ~:184-194.
- ZIP build — web `web/src/lib/download.ts` (`gatherFiles` ~:24,
  `buildSelectionZip` ~:37-47, `saveBytes` ~:55; encoder `web/src/lib/zip.ts`
  `zipStore` ~:32), triggered from `web/src/components/gallery.tsx` ~:307;
  Flutter `app/lib/services/download_zip.dart` (`gatherFiles` ~:15,
  `buildSelectionZip` ~:29-37).
- Upload — web `gallery.tsx` ~:186; Flutter
  `app/lib/services/dufs_client.dart` `upload()` ~:73-81 (a plain `_http.put`
  with the full body — **not** a `StreamedRequest`, so byte progress is not
  currently observable), called from `browser_screen.dart` ~:339.
- Bulk mutations, all single static strings in `gallery.tsx`: move ~:211/:271,
  delete ~:229/:290 (the bulk delete loops per item and reports only a final
  failure count), rename ~:243, create dir ~:257.
- Directory listing — web `web/src/hooks/use-listing.ts` ~:31-72; Flutter
  `browser_screen.dart` ~:120/:140/:149/:155.

Other surfaces:
- `web/src/index.css` (806 lines; `.busy` styled ~:87 — static text, no shimmer).
- `web/src/components/filter-bar.tsx` ~:75-83 — the search input fires `onFilter`
  on **every keystroke with no debounce**.
- `web/src/components/gallery.tsx` ~:454 `{loading && <p className="muted">Loading…</p>}`,
  ~:355 the `busy` span; `folder-picker.tsx` ~:97.
- Flutter spinners: `browser_screen.dart` ~:717, ~:732, `RefreshIndicator` ~:748
  (the one built-in motion affordance), plus `text_editor_screen.dart` ~:101/:80,
  `audio_screen.dart` ~:104, `video_screen.dart` ~:169, `pdf_screen.dart` ~:184,
  `app/lib/widgets/folder_picker.dart` ~:92.
- Settings: `app/lib/screens/settings_screen.dart` (93 lines — room for a toggle),
  store `app/lib/services/settings.dart`.

## must

**Step 1 — motion + honest progress (the valuable half).**

- Make the index walk report **real progress**: directories walked, files found,
  and ideally the current path. The walk already knows these numbers — it just
  discards them. Thread a progress callback through `buildCloudIndex`/`walkInto`.
- Make the ZIP build report **per-file progress** (`3 of 47`). Both
  `buildSelectionZip` signatures need a progress callback added; today neither
  accepts one.
- Add a **cancel** to both. A long unbounded operation with no way out is the
  actual usability failure here, and it is more valuable than any animation.
- Add `HapticFeedback.selectionClick()` on the Flutter **long-press to
  multi-select** (`browser_screen.dart` ~:95). No dependency needed
  (`flutter/services.dart`); add `<uses-permission
  android:name="android.permission.VIBRATE"/>` to the manifest if absent.
- Add a `@media (prefers-reduced-motion: reduce)` block to `web/src/index.css`.
  **There is none today** — this is a straight accessibility gap, not a nicety.
  Flutter side: honour `MediaQuery.of(context).disableAnimations`.
- Use the shared motion tokens for any transition you add. Replace the inline
  `0.12s` at `index.css` ~:539-544 with the token while you are there.
- Debounce the search input (`filter-bar.tsx` ~:75-83). Firing on every keystroke
  over a large index is the cause of jank, and no animation fixes that.

**Step 2 — sound (separate, independently revertable).**

- A completion cue for long operations only (index built, ZIP ready, upload
  finished) — **not** for navigation or selection. A file manager that chirps on
  every click is intolerable.
- Sound ships **on**, with an opt-out toggle in
  `app/lib/screens/settings_screen.dart` backed by `app/lib/services/settings.dart`,
  and an equivalent on web.
- Consider suppressing the cue when the operation finishes in under ~2s — a
  completion sound for something that felt instant is noise.

**Both steps:**

- must not: **fake progress.** No indeterminate bar dressed up as determinate, no
  bar that advances on a timer, no "estimated" percentage that is really elapsed
  time. If a total is unknown, show the count that *is* known ("47 files found")
  rather than a fabricated fraction. This is the project's first test and the
  easiest place in the fleet to violate it.
- must not: add a variable/random reward. There is no real pool here; any
  variance would be manufactured.
- must not: change what the index actually contains, or filter/sort semantics
  (`web/src/lib/filter-sort.ts`, `app/lib/util/filter_sort.dart` mirror each
  other — a change to one desyncs the port).
- must not: use npm in `web/`. **pnpm only.**
- must not: let web and Flutter drift further apart. If you add a progress
  callback on one side, add the equivalent on the other, or state explicitly in
  the summary why not.

- optional: skeleton screens for the directory listing instead of "Loading…".
  Genuinely useful for perceived latency, but lower value than cancel + real
  counts. Do it only after step 1 lands.

## done

1. Starting a cloud index shows a live, **true** count and can be cancelled — on
   both web and Flutter.
2. A multi-file ZIP shows per-file progress and can be cancelled.
3. `web/src/index.css` has a `prefers-reduced-motion` block; with the OS setting
   on, transitions are suppressed.
4. Long-press multi-select produces a haptic on the phone.
5. `cd ~/src/dufs-cloud/web && pnpm install && pnpm build && pnpm test` passes
   (use the repo's actual script names).
6. `cd ~/src/dufs-cloud/app && flutter analyze && flutter test` clean.
7. No fabricated progress value anywhere in the diff.

## verify

**Both surfaces — this repo has two and they drift.**

Web: run the dev server, open it in a real browser, and index a directory large
enough to take several seconds. Confirm the count moves, the cancel works, and
the numbers are real (cross-check the final count against the actual file count).
A jsdom test cannot verify this — it has no layout and no perceived latency.

Flutter, on the phone:
```
adb devices
cd ~/src/dufs-cloud/app
flutter build apk --release
adb install -r build/app/outputs/flutter-apk/app-release.apk
```
Never `adb uninstall`/`pm clear` — the app holds a stored credential.

Then trigger a real index build and a real multi-file ZIP on the device and
report what you saw. State the haptic as a physical observation.

## read first

- `web/src/hooks/use-cloud-index.ts` and `app/lib/services/cloud_index.dart` —
  read both before changing either; they mirror each other deliberately.
- `web/src/lib/download.ts` and `app/lib/services/download_zip.dart` — same.
- `web/src/components/gallery.tsx` — the `setBusy` call sites; they are the
  inventory of every operation currently reduced to one static string.
- `~/src/dufs-cloud/DESIGN_AUDIT_TODO.md` — prior findings for this repo.
- `~/src/utils/unified-design-system/motion.md` — vocabulary from prompt 01.

## context you would otherwise rediscover

- **Prompt 07 must have run first.** Until it does, `app/` has no
  `design_system` dependency and hand-restates the palette in
  `app/lib/ui/theme.dart`.
- Web tokens come from `@kuhyx/web-ui` imported in `web/src/main.tsx`;
  `web/src/index.css` declares only `--overlay`. New tokens arrive **only** after
  the tag bump — this is the step that is easy to forget and silently produces
  "the variable doesn't exist".
- `upload()` uses a non-streaming `_http.put`, so real byte-level upload progress
  needs a `StreamedRequest` refactor. That may be more than this prompt wants —
  if you skip it, say so explicitly and report per-**file** progress instead of
  per-byte rather than faking a byte percentage.
- Media playback (`web/src/hooks/use-dash-player.ts`, `web/src/lib/dash-buffer.ts`,
  `app/lib/services/app_player.dart`) has its own buffering states. Out of scope
  unless trivially adjacent.

REMOVE ME AFTER FINISH