Honor save failures and surface USB-MSC hint when the filesystem is locked

[makermelissa-piclaw]

Summary

Fixes #460 — "Cannot Save code.py Edits on Adafruit Qualia ESP32-S3."

The root cause, after walking through the firmware code, is that the
board's filesystem is write-locked by USB Mass Storage: when the host
computer has CIRCUITPY mounted, CircuitPython can't write through FatFS
even though the web workflow happily accepts the request. The current
firmware reports this as HTTP 500 Internal Server Error, which looks
like a server crash and gave the editor nothing actionable to show.
Confirmed by repro: the failure disappears the moment USB MSC is
disabled in boot.py.

This PR fixes the editor's behavior in three ways:

1. Stop pretending failed saves succeeded. The previous
   saveFileContents() retried via a fire-and-forget setTimeout, so
   workflow.saveFile() returned true immediately while retries ran
   in the background. saveRunFile() then soft-restarted the board
   while the PUT hadn't actually landed yet, running the previously
   saved code.py.
2. Show an actionable hint when the device tells us the filesystem
   is locked, instead of the generic "failed after multiple attempts."
3. Skip pointless retries when the failure is "host owns the disk"
   — retrying can't help until the user ejects.

A companion firmware PR (adafruit/circuitpython#11017)
brings the file-writing PUT in line with DELETE / MOVE / mkdir-PUT in
the same file, which already reply 409 Conflict for
FR_WRITE_PROTECTED. The editor handles both 500 (old firmware) and
409 (new firmware) the same way, so users on any CP version benefit
from the better error message.

Root cause

The prior PR #472 capped the runaway retry loop (the "editor reloads
every 1-2 seconds" symptom) but the deeper bug was still there:

• saveFileContents() retried via setTimeout(saveFileContents, 2000)
  inside the catch block.
• The outer call returned normally, so workflow.saveFile()
  unconditionally returned true.
• saveRunFile() saw a truthy result and called
  workflow.runCurrentCode() → repl.softRestart().
• The board rebooted into the OLD code.py while retries fired against
  a rebooting device, all failed, and the editor showed
  "Saving file failed after multiple attempts" — but had already
  flipped its UI back to "saved," so the unsaved buffer was lost too.

Two bugs stacked: a misleading server response from the firmware AND
the editor lying about save success to the rest of the app.

Changes

js/script.js

• saveFileContents() is now a real awaitable retry loop:

  • 3 attempts, 2 s apart, using await sleep(...) instead of
    fire-and-forget setTimeout.

  • Returns true on success, false on exhausted retries (or on
    disconnect mid-retry).

  • saveInFlight flag refuses re-entrant invocations so mashing
    Ctrl-S / Save+Run doesn't race two PUTs onto the wire and corrupt
    partialWrites bookkeeping.

  • On any failure the editor stays marked dirty (setSaved(false)),
    so the unsaved buffer is recoverable.

  • New: when the device cleanly says the filesystem is held by
    someone else (409 Conflict or 500 Internal Server Error on a
    /fs/ PUT), skip the remaining retries and show:

    Could not save '/code.py'.

    The board's filesystem is locked, usually because CIRCUITPY is
    mounted on a computer over USB.

    To fix:

    • Disconnect the USB cable, or
    • Disable USB Mass Storage in boot.py, then reset the board.

    Note: ejecting the drive in your OS isn't always enough on its own.

    Disabling USB Mass Storage (Adafruit Learn)

    Your edits are still here — save again once the filesystem is writable.

    The dialog renders headers, list, and link via real HTML
    (MessageModal uses innerHTML), so it scans cleanly instead of
    being a wall of prose.

    The corresponding connect-time read-only warning was shortened
    to a single line so it doesn't shout at every connect:

    Filesystem is read-only — you can browse files, but saving
    will fail until USB Mass Storage is released.
    How to fix.

    (The "eject may not be enough" caveat reflects real-world
    behavior on macOS: Finder's Eject command sometimes unmounts the
    filesystem locally without sending the SCSI START_STOP_UNIT
    eject command, so the device-side blockdev_unlock() never
    fires and STA_PROTECT stays set.)

• saveRunFile() drops the redundant setSaved(true);
  saveFileContents() already handles it on success, and we only
  reach runCurrentCode() when the save actually worked.

• disconnectCallback() no longer juggles a retry timeout — the
  inline loop owns its own state now and bails out cleanly when
  connectionStatus() flips false between attempts.

js/workflows/workflow.js

• saveFile() propagates the real result from _saveFileContents()
  instead of unconditionally returning true. Uses result !== false
  so any legacy saveFileFunc callback returning undefined still
  counts as success.

js/common/web-file-transfer.js

• _fetch() attaches numeric status, method, and path to the thrown
  ProtocolError, and tags /fs/ PUT failures with status 409 or
  500 as writeProtected = true with a human-readable hint.
  Additive — callers that ignore the new fields get the same
  ProtocolError they used to.
• writeFile() returns response.ok so the workflow layer sees real
  success / failure (matches what makeDir() already does).

Behavior after the fix

Scenario	Before	After
PUT succeeds first try	UI marks saved ✅	UI marks saved ✅
Host has CIRCUITPY mounted (current firmware → 500)	"Failed after multiple attempts" after ~6s of retries; board soft-restarted with stale code ❌	Immediate "unplug USB / disable USB MSC in boot.py" message; no retries; no soft-restart ✅
Host has CIRCUITPY mounted (with #11017 → 409)	n/a	Same as above ✅
Transient network glitch	Retries 2× (sometimes worked, sometimes restarted before completion)	Retries 2× inline; Save+Run waits for real success ✅
Persistent network failure	UI flipped to "saved," unsaved buffer lost, soft-restart anyway ❌	Editor stays dirty, no restart, generic error dialog, buffer recoverable ✅
User mashes Ctrl-S during save	Two overlapping PUTs, partialWrites offsets confused	Second call no-ops with a console message
Disconnect mid-retry	disconnectCallback had to clean up a global timeout	Inline loop notices !connectionStatus() and bails

Why detect both 409 and 500

CircuitPython firmware versions that ship today return 500 for the
write-protected case. The companion firmware PR
(adafruit/circuitpython#11017)
will return 409 Conflict to match the rest of the web workflow's
error contract. Users will be on mixed firmware versions for years,
so the editor handles both the same way. The detection is gated on
the request being a PUT to /fs/, so generic 500s elsewhere are
unaffected.

Testing

• npm run build (vite) passes clean.
• node --check on all edited files passes.
• Manual reproduction:
  • Before: Mount CIRCUITPY on host, hit Save+Run → editor showed
    "Saving file failed after multiple attempts," board soft-restarted
    with stale code.
  • After: Same flow → immediate "Eject CIRCUITPY / disable USB
    MSC in boot.py" message, no soft-restart, buffer stays in the
    editor.
  • With USB MSC disabled in boot.py: save works on the first try
    as expected.
• Manually traced BLE (partialWrites=true), web workflow
  (partialWrites=false), checkSaved() unsaved dialog, and the
  Ctrl-S / Save+Run / Mod-r hotkey paths through the refactored code.

Refs adafruit/circuitpython#11017

Closes #460

[makermelissa]

Looks good after testing a number of times locally.