Keep preferences on iOS: re-link lost device cookies, ship prefs with the page

[lstein]

Problem

On iOS (Safari, and Chrome/Firefox on iOS), the selected album, slide delay, autotagging flag and control-label visibility reset to defaults after the browser has been closed for a while.

Preferences have been stored on the server since #284, keyed by an HttpOnly photomap_device cookie. iOS deletes that cookie along with localStorage, though. The server then created a new device ID with a record of defaults, and the real record was left with nothing pointing to it: one install had 18 device records in 8 days. No client-side storage can fix that.

Three more bugs made it worse:

• A boot with empty localStorage drew the UI from defaults. reconcileWithServer applied the server copy afterwards, but nothing redrew the UI from it.
• Every write PATCHed the whole settings set, stale values included. So did the 30-second backup in page-visibility.js.
• The "show control panel labels" checkbox only ever wrote to localStorage.

Changes

Backend

• When a request has no cookie, it is re-linked to its device by client IP + User-Agent.
  • A fingerprint belongs to one device at a time and moves only on writes (PATCH/PUT).
  • DELETE /preferences/ drops the fingerprint, so Reset to Defaults isn't re-linked.
  • The cookie is re-sent on every response, renewing its Max-Age.
• GET / embeds the device's record as window.initialPreferences (null if it has none) and sets the cookie itself. FastAPI doesn't merge a dependency's Response into a response returned directly, hence setting it there. The page is served Cache-Control: no-cache.
• New fields: umapWindowOpen, and lastSlideIndex (album → index, merged per album rather than replaced).

Frontend

• state.js starts from the embedded record, falls back to localStorage, then to defaults.
  • A device with no record seeds one.
  • A key the record lacks but localStorage has is sent up.
  • reconcileWithServer and the _prefServerUpdatedAt timestamp cache are gone.
• Writes send only the keys they changed: generated setters, persistSettings(...keys), and persistSlidePosition.
• The preferences client:
  • retries failed PATCHes with backoff;
  • on a 422, resends key by key, so one bad value doesn't drop the rest;
  • sends flushes one after another, never overlapping;
  • uses keepalive;
  • can be closed during Reset to Defaults.
• page-visibility.js drops the sessionStorage backup/restore and the periodic full saves.
• Visual session state is remembered: whether the UMAP window is open, grid vs. swiper (already persisted), and the last slide in each album.

Known limits

• If the iPad's IP changes (DHCP) or an iOS update changes its UA string, the device gets a fresh record. That is today's behavior.
• Browsers on one machine with an identical UA share a record once their cookies are gone.
• Orphaned records from before this change have no fingerprint and can't be re-linked.

Testing

• make lint, Jest (997 tests) and pytest (1299 tests) all pass. New tests cover:
  • re-linking, fingerprint ownership, forget, persistence across restarts, and the old store format;
  • embedding preferences in the page;
  • starting up from the embedded record and per-key writes;
  • retries, the 422 split, serialized flushes, and per-album merging;
  • restoring the slide position.
• Checked end to end in headless Chromium with an iPad UA. After clearing both the cookie and localStorage, every setting and the visual state came back, and only one device record existed.
• Checked on a real iPad by the author.
• An adversarial review was run on the diff. The second commit fixes what it found.

🤖 Generated with Claude Code