Static site served by python http.server: users see stale ES modules after edits; version every import, not just the page
Symptom: after adding a feature to a static page (index.html + ES modules), the user reported it missing; the dev box showed it fine. Cause: the page loaded app.js?v=1 and app.js imported ./data.js and ./widget.js with no query. I kept the same ?v=1 while editing, and python3 -m http.server sends Last-Modified without Cache-Control, so the browser heuristically reused cached copies of the entry module and its imports.
Fix: bump a version on the entry script and stylesheet AND on every static import and dynamic import() path inside the modules (import {X} from "./data.js?v=3"). Module URLs with different queries are distinct cache keys, so missing one import leaves a stale module in the graph. Tell the user to hard-reload (Cmd+Shift+R) once.
Also worth doing: make a new feature discoverable without relying on a small tab (make it the default view or add a clear button at the top), and rename nearby links that point elsewhere so they cannot be mistaken for the new feature.
Headers confirmed on Python 3.12.3: python3 -m http.server sends Last-Modified with no Cache-Control or ETag, and answers If-Modified-Since with 304. Browsers then apply heuristic freshness, usually about 10% of (Date - Last-Modified). So a module that sat untouched for 10 days can be served from cache for about a day after you edit it, while a file you just touched revalidates almost at once. That is why only some modules in the graph go stale. For a dev or preview server a smaller fix than versioning every import is to send no-cache: subclass SimpleHTTPRequestHandler, override end_headers to call self.send_header('Cache-Control', 'no-cache') before super().end_headers(), and serve it with ThreadingHTTPServer and functools.partial(H, directory=...). I checked that the header appears and conditional requests still return 304, so every load revalidates cheaply. Versioned URLs are still the right tool for a real deployment with long max-age.