For Support
What users will ask
"The upload screen shows a percentage now, is that new?" Yes — this replaces the old plain spinner on four screens: clocking in/out with a photo, adding a file to a patient's record, recording a patient voice note, and sending a voice message in staff chat. Nothing about how those flows work changed, only what's shown while they run.
"It says 0% / no percentage and just spins — is something broken?" Not necessarily. The percentage line only appears once a total size is known (useUploadProgress.js:85). For a recording (a clock-in photo just taken, or a voice note/voice message), the size isn't known until the upload itself starts reporting bytes — so a brief plain-spinner period before the percentage appears is expected, especially on a fast connection where it may be too quick to notice normally.
"The percentage jumped around / seemed to go backwards briefly." The very first percentage shown for a clock-in photo is based on an estimate of the file's size (from its base64 payload) before the real upload has reported anything. Once the platform reports the actual bytes being sent, the total is corrected to the real figure — so the percentage can jump when that correction happens. This is expected behavior, not a bug, and should self-resolve within a second or two of the upload starting.
"Upload is stuck at some percentage and the speed line disappeared." The speed clause only shows while bytes are actively being measured as moving (useUploadProgress.js:78, 86-88). If the speed line vanishes and the percentage stops climbing, that's consistent with the upload having actually stalled — a real connectivity issue, not just a display quirk. This is exactly the situation this PR was built to make visible; before it, an S3 upload could look exactly the same whether it was slow or completely stuck.
What to check before escalating
- Confirm which of the four flows is affected (clock-in, patient file, patient
note, or staff chat voice message) — they share the same underlying hook and upload function, so a bug in one likely affects all four.
- Confirm whether the clinic uses Google Drive or the default S3 storage
(user.company.googleDriveAuth) — both routes report progress, but they go through different code paths (see Streaming the bytes instead of buffering them), so a bug may be specific to one.
- Ask about connection quality (Wi-Fi vs. cellular, signal strength) before
assuming an app bug — a stalled speed line is often an accurate report of a real network problem, not a false one.
Scope
This is a mobile-app-only change (packages/clinic-mobile). The web dashboard's upload experience (Patient Files tab, etc.) is untouched by this PR.