coldwire-rails 0.3.0 → 0.5.0

data/docs/configuration.md

@@ -154,6 +154,36 @@ Listing a URL here is an explicit instruction: `cache_as_you_go` does not filter
 
 A stored page's stylesheets, scripts, and images are fetched with it, whatever the lists say.
 
+**Naming a frame or a format.** A URL is one field short of naming a body: the same path
+answers a visit, a Turbo Frame and a `respond_to` format with three different things, and a
+bare listing asks for the page. A Hash says which one you mean:
+
+```ruby
+sync.precache_urls = -> {
+  Feature.published.map { |f| { url: feature_path(f), frame: "map_feature_popup" } } +
+  Report.all.map { |r| { url: report_path(r), format: :json } } +
+  [ root_path ]
+}
+```
+
+`frame:` is the frame tag's own id, which is what Turbo puts in the `Turbo-Frame` header. The
+worker fetches with that header, so an app branching on `turbo_frame_request?` answers with the
+frame, and the body is stored where a frame request will look for it.
+
+`format:` is any registered Rails format, including one your app registered itself. It is
+resolved to that format's media type here and sent as `Accept`, so the worker never has to know
+what `:json` means. `accept:` takes a media type directly, for anything with no registered name.
+
+Without this, a frame URL is precached as its whole page. That still works offline, since a
+frame request falls back to the page and Turbo pulls the frame out of it, but only while the
+page actually contains that frame, and it stores the whole document where a fragment would do.
+
+List a URL twice to precache both:
+
+```ruby
+[ feature_path(f), { url: feature_path(f), frame: "map_feature_popup" } ]
+```
+
 ### `auto_sync.interval`
 
 **Default:** `1.day`
@@ -203,7 +233,8 @@ collect and the cache grows until the browser evicts the lot.
 **Only ever with a connection.** Deleting is the one cache operation with no way back:
 whatever goes is gone until the network can be reached again. So a sweep pings
 [`probe_path`](#probe_path) first and stands down if it cannot be reached, and stands down
-under force offline. `navigator.onLine` is not consulted — a web view answers it wrongly often
+under force offline. The one exception is somebody choosing a storage limit on the settings
+page, which applies right away: see [`max_size`](#garbage_collectionmax_size). `navigator.onLine` is not consulted — a web view answers it wrongly often
 enough to be worthless for a decision this expensive to get wrong.
 
 **Untouched, not old.** Age is measured from when an entry was last *used*, not when it was
@@ -268,15 +299,27 @@ Measured over what a sweep is allowed to take, which is everything but the offli
 assets and downloaded archives. Counting a 300 MB download somebody deliberately kept would
 empty the rest of the cache to make room for a file no sweep may touch.
 
+Which leaves two figures on the settings page that do not match: the header counts everything
+on the device, the limit governs only part of it. So Storage and Downloads are separate cards,
+each carrying one line about the other. Storage says its figure is cached pages only and that
+downloads are counted below; Downloads says the limit never counts a download and never clears
+one to make room.
+
 The ceiling is applied when a sweep runs, so [`interval`](#garbage_collectioninterval) is also
 how long the cache may sit over it. Lower the interval if a tighter bound matters more than
 the work.
 
-**People can change it.** The offline settings page offers a ladder of sizes — the configured
-default always among them — and the choice is remembered in `localStorage` for that device,
-the way Force offline and the Auto Sync switch are. It travels to the worker with each sweep,
-since a worker cannot read `localStorage`. Changing it there sweeps immediately rather than
-waiting out the interval.
+**People can change it.** The offline settings page offers a ladder of sizes, the configured
+default always among them, and the choice is remembered in `localStorage` for that device the
+way Force offline and the Auto Sync switch are. It travels to the worker with each sweep,
+since a worker cannot read `localStorage`.
+
+Picking a size applies it on the spot: if the cache is over the new ceiling, the least
+recently read entries go immediately, until it fits. That one pass does **not** wait for a
+connection, and runs under Force offline, because it is a deliberate instruction about
+somebody's own storage rather than an automatic sweep. Clear cache has always worked the same
+way. Only the ceiling is applied; age collection still waits for a connection it has
+confirmed.
 
 ### `garbage_collection.interval`
 
@@ -548,10 +591,19 @@ archive is how the rest does.
 
 **Default:** `[]`
 
-Large files somebody can choose to keep — a tile archive, an audio guide, a reference PDF.
-Nothing downloads on its own: hundreds of megabytes over somebody's connection is their
-decision. The offline settings page shows **Download**, then **Download again** and **Delete** once it
-is on the device, or **Resume** where a download stopped part way.
+Large files somebody can choose to keep: a tile archive, an audio guide, a reference PDF.
+Nothing downloads on its own, because hundreds of megabytes over somebody's connection is
+their decision. Each appears in the Downloads card on the offline settings page: the title
+with the button hard right, **Download**, then **Download again** once it is on the device or
+**Resume** where one stopped part way, with a trash button beside it to remove it. The
+description, the size and the progress of a running download read underneath, at the full width
+of the card.
+
+They live in that card rather than one of their own because they answer the same question the
+storage limit does: what is on this device, and how much of it do you want to keep? What the
+limit governs is at the top, these sit under it with their own sizes, and the card ends on a
+total that reconciles with the header. A download is never deleted to make room and never
+counted against the limit, so removing one is something only the person who chose it does.
 
 ```ruby
 config.cache_archives = [

data/docs/how-it-works.md

@@ -23,6 +23,27 @@ Turbo — rather than a native error screen:
 3. **Turbo Frames need a frame.** A frame request discards any response without a matching
    `<turbo-frame>`, leaving the frame loading forever. Coldwire reads the `Turbo-Frame`
    header and answers with one.
+
+   **And a frame is not the page it came from.** Turbo sends that header on every frame
+   navigation, and an app answering it with `turbo_frame_request?` returns just the frame.
+   Keyed on the URL alone, that body lands in the slot the page occupies: a later cold visit
+   is then served a fragment as a whole document, which is a blank screen, and in Hotwire
+   Native a page where `window.Turbo` never appears. Whichever was cached last wins, so it
+   also happens in reverse. `Vary` cannot fix this, because matching is URL-only by design
+   (see 1), so Coldwire puts the frame in the key instead. A frame takes its own entry first
+   and the page second, since Turbo pulls a frame out of a document exactly as it does
+   online. An ordinary visit never takes the reverse trade.
+
+   **And neither is any other format.** The same URL answers a `respond_to` block in as many
+   formats as the app defines: `/report` is a page to Turbo, JSON to a `fetch`, a CSV to an
+   export link and an RSS feed to a reader. Coldwire names the format in the key too, with the
+   page left unnamed so anything cached before this keeps the key it had. The name is worked
+   out from the request's `Accept`, not the response's type, because the same name has to be
+   produced again when the entry is looked for, and there is no response to read then. A
+   request asking for data gets data or nothing, since handing it a page is the mistake in 6
+   wearing a different hat. A path that names its own format is left alone: `/report.json` is
+   JSON and nothing else, so only `/report` needs telling apart. A Turbo Stream is never stored at all: it is a list of changes to
+   make to a page, and replaying a stale one applies yesterday's mutations to today's DOM.
 4. **A followed redirect poisons the cache.** A signed-out request to `/` gets a `302` that
    `fetch` follows; the result looks fine and `cache.put()` stores it without complaint.
    Now `/` holds the sign-in page and keeps `redirected: true` — and serving a redirected

data/docs/setup.md

@@ -135,9 +135,11 @@ redirects to login, so nothing about the online flow changes.
 Mounted at the engine root — `/offline` with the mount above. It inherits your
 `ApplicationController`, so it picks up your layout, authentication, and helpers.
 
-This is the page people use to turn offline support on or off, see connection status, download
-archives, turn auto-sync off for this device, set how much storage the cache may use, force
-offline, and manage what is cached.
+This is the page people use to turn offline support on or off, see connection status, turn
+auto-sync off for this device, force offline, and manage what is cached. The three switches
+sit together in the status card at the top, since each is a choice this device makes about how
+Coldwire behaves. Storage and Downloads are separate cards, since the storage limit governs
+cached pages and never touches a download.
 Turning offline support off asks first, then deletes what is stored and hides the rest of the
 page. It sets `content_for :title` to `"Offline settings"` — yield that in your layout's
 `<title>` (and any native title bar that reads it) rather than expecting an on-page heading.

data/lib/coldwire/debug.css

@@ -114,14 +114,43 @@
 .coldwire-input:focus-visible, .coldwire-select:focus-visible { outline: 2px solid #6b7280;
   outline-offset: 1px; }
 
+/* The sync clock, its button and its bar, behind a disclosure: worth having, worth going to,
+   and three lines of furniture under a switch you are not currently using. Quiet like the
+   Inspect cache summary, because it is the same kind of thing. */
+.coldwire-sync { margin-top: 0.9rem; }
+.coldwire-sync > summary { display: flex; align-items: center; gap: 0.35rem; cursor: pointer;
+  list-style: none; font-size: 0.75rem; font-weight: 600; letter-spacing: 0.04em;
+  text-transform: uppercase; color: #9ca3af; }
+.coldwire-sync > summary::-webkit-details-marker { display: none; }
+.coldwire-sync > summary::after { content: ""; width: 0.8rem; height: 0.8rem; flex-shrink: 0;
+  background: var(--coldwire-caret) no-repeat center / contain; opacity: 0.7;
+  transition: transform 160ms ease; }
+.coldwire-sync[open] > summary::after { transform: rotate(180deg); }
+.coldwire-sync > summary:focus-visible { outline: 2px solid #6b7280; outline-offset: 2px;
+  border-radius: 0.25rem; }
+/* The first line inside sets its own spacing from the summary. */
+.coldwire-sync-body > .coldwire-facts:first-child { margin-top: 0.5rem; }
+
+/* The line each card carries about the other: what the limit does not count, and what the
+   limit will never take. Quieter than the figures they qualify, and always under them. */
+.coldwire-downloads-note { margin: 0.9rem 0 0; padding-top: 0.75rem;
+  border-top: 1px solid #e5e7eb; font-size: 0.8125rem; line-height: 1.5; color: #9ca3af; }
+.coldwire-downloads-note strong { color: #6b7280; font-weight: 600; }
+
 /* The rule separates one download from the next; the first has nothing above it. */
-.coldwire-archive { margin-top: 1rem; padding-top: 1rem; border-top: 1px solid #e5e7eb; }
-.coldwire-archive:first-child { margin-top: 0; padding-top: 0; border-top: 0; }
-.coldwire-archive-title { font-size: 0.9375rem; font-weight: 600; }
-/* The buttons used to sit under a status line that spaced them; they lead now. */
-.coldwire-archive .coldwire-actions { margin-top: 0.75rem; }
-/* What pressing them got you, reading under them rather than above. */
-.coldwire-archive-meta { margin-top: 0.6rem; font-size: 0.8125rem; }
+.coldwire-archive { margin-top: 0.9rem; padding-top: 0.9rem; border-top: 1px solid #e5e7eb; }
+.coldwire-archive:first-of-type { margin-top: 0; padding-top: 0; border-top: 0; }
+/* The name and the action on one line, the words underneath at full width. The buttons sit
+   hard right, where the eye goes for the action, and keep their width whatever the title does:
+   a long title gives way instead, because a button that wraps to two lines is worse than a
+   name that ellipsises. */
+.coldwire-archive-head { display: flex; align-items: center; justify-content: space-between;
+  gap: 0.75rem; }
+.coldwire-archive-actions { flex: 0 0 auto; flex-wrap: nowrap; }
+.coldwire-archive-title { flex: 1 1 auto; min-width: 0; overflow: hidden;
+  text-overflow: ellipsis; white-space: nowrap; font-size: 0.9375rem; font-weight: 600; }
+/* What pressing them got you, under the words rather than under the buttons. */
+.coldwire-archive-meta { margin-top: 0.4rem; font-size: 0.8125rem; }
 /* Under the filter, because it answers what the filter asks. */
 .coldwire-count { margin: 0 0 0.6rem; }
 
@@ -200,5 +229,6 @@
   .coldwire-pulse { animation: none; }
   .coldwire-switch span,
   .coldwire-switch span::after,
+  .coldwire-sync > summary::after,
   .coldwire-inspect-label::after { transition: none; }
 }

data/lib/coldwire/precache.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/array/wrap"
+
+module Coldwire
+  class << self
+    # The precache manifest, as the worker needs it. A bare URL is a page; a Hash can also name
+    # the Turbo frame it is loaded into, or the format it is fetched as, which are the two
+    # things a URL alone cannot say:
+    #
+    #   sync.precache_urls = -> {
+    #     Feature.published.map { |f| { url: feature_path(f), frame: "map_feature_popup" } } +
+    #     Report.all.map { |r| { url: report_path(r), format: :json } }
+    #   }
+    #
+    # Listing one URL twice is how you ask for both the page and the frame, so nothing here
+    # collapses them.
+    def precache_entries(list)
+      Array.wrap(list).map { |entry| precache_entry(entry) }
+    end
+
+    private
+
+    def precache_entry(entry)
+      return { url: entry.to_s } unless entry.is_a?(Hash)
+
+      entry = entry.transform_keys(&:to_sym)
+      url = entry[:url].to_s
+      raise ArgumentError, "Coldwire precache_urls entries need a url: #{entry.inspect}" if url.empty?
+
+      { url: url, frame: entry[:frame].presence&.to_s, accept: precache_accept(entry) }.compact
+    end
+
+    # A format becomes the Accept header the worker asks with, resolved here rather than in the
+    # worker because Rails already knows what every registered format means — including any the
+    # app registered itself.
+    #
+    # `format: :json` is the friendly way to say it and `accept:` is the way out when a media
+    # type has no registered name. Naming a format that is not registered is a typo worth
+    # refusing: it would otherwise be fetched as HTML and cached as the page.
+    def precache_accept(entry)
+      return entry[:accept].to_s if entry[:accept].present?
+      return nil if entry[:format].blank?
+
+      mime = Mime[entry[:format]]
+      unless mime
+        raise ArgumentError,
+              "Coldwire precache_urls format #{entry[:format].inspect} is not a registered Mime " \
+              "type. Register it with `Mime::Type.register`, or give `accept:` instead."
+      end
+
+      mime.to_s
+    end
+  end
+end

data/lib/coldwire/worker/collect.js

@@ -3,18 +3,79 @@
 // fetched again until one returns. So a sweep proves the network first, and only then takes
 // what nothing has asked for in a long time — and, if the cache is still over its ceiling,
 // whatever has gone longest unread until it fits.
+//
+// Somebody choosing a ceiling on the settings page is the exception, and applyCeiling() below
+// is where it is made.
 let collecting = null
 
+// One pass over the cache at a time. Two of them deleting at once would each be measuring a
+// total the other is still taking from, and both would stop early.
+function track(run) {
+  collecting = run
+  run.catch(() => {}).then(() => { if (collecting === run) collecting = null })
+
+  return run
+}
+
 // The ceiling is a per-device choice, so it arrives with the request rather than being baked
 // into the worker. Undefined is a page that has nothing to say about it — an older client, or
 // one that never loaded the collector — and falls back to what the app configured.
 function collectGarbage({ maxSize } = {}) {
   const limit = maxSize === undefined ? COLLECT_MAX_SIZE : maxSize
-  // A sweep already running is the answer to this one too. It may be working to a ceiling
-  // that has just changed; the next sweep uses the new one, and a sweep is cheap to be late.
-  collecting = collecting || runCollection(limit).finally(() => { collecting = null })
+  // A sweep already running is the answer to this one too: it is doing the same automatic
+  // work, and a sweep is cheap to be late.
+  return collecting || track(runCollection(limit))
+}
+
+// Somebody has just set the ceiling and is watching the number under it. Two things separate
+// this from a sweep:
+//
+// It does not prove the connection first. The probe is there because nothing asked for an
+// automatic sweep, so the cost of getting it wrong falls on somebody who never requested it.
+// This was requested: it is the same deliberate instruction Clear cache is, and that has
+// never waited for a network to agree. Refusing until the connection returns would answer a
+// question nobody asked.
+//
+// It never joins a run already in flight. That run is working to the ceiling this call
+// replaces, so its answer is the answer to the old question — the very thing that made the
+// setting look like it did nothing. It queues behind instead.
+function applyCeiling(maxSize) {
+  const queued = collecting ? collecting.catch(() => {}) : Promise.resolve()
+
+  return track(queued.then(() => runTrim(maxSize)))
+}
+
+// Only the ceiling. Age collection stays behind the probe, because nothing has asked for it.
+async function runTrim(maxSize) {
+  if (maxSize === undefined || maxSize === null) return { ok: true, evicted: 0, trimmed: false }
 
-  return collecting
+  const cache = await caches.open(CACHE_NAME)
+  const { evicted, bytes } = await trimToSize(cache, await collectable(cache), maxSize)
+
+  return { ok: true, evicted, bytes, trimmed: true, finishedAt: Date.now() }
+}
+
+// Everything a sweep is allowed to take, with the stamp it sorts by.
+async function collectable(cache) {
+  const spared = offlinePageAssets()
+
+  return (await cache.keys())
+    .filter((key) => !isSpared(key, spared))
+    .map((key) => ({ key, at: unixTimestamp(key.headers.get(TIMESTAMP_HEADER)) }))
+}
+
+// The URLs a sweep may never take, for the settings page.
+//
+// The page has to add up the same bytes the worker does or its bar lies: counting files the
+// worker is not allowed to touch shows an overage that no amount of trimming will ever bring
+// down, and the setting reads as broken when it is working exactly as told. The page knows
+// about downloads by their query, but the offline page's own assets it cannot know, because
+// working them out means parsing the offline page — which only the worker holds.
+//
+// The list, rather than the total: the page has already read every entry and its size to draw
+// the list, so this is all it is missing, and one message beats a second pass over the cache.
+async function sparedUrls() {
+  return { ok: true, urls: [ ...offlinePageAssets() ] }
 }
 
 async function runCollection(maxSize) {
@@ -149,5 +210,10 @@ async function renew(cache, key) {
   if (!response) return
 
   const managed = key.headers.get(MANAGED_HEADER) === "1"
-  await putFresh(cache, cacheKey(new Request(key.url, { method: "GET" }), { managed }), response)
+  // Put it back where it was. Rebuilt from the URL alone, a frame entry would lose the frame
+  // it names and land on its page's key, which is the collision this all exists to avoid.
+  const params = new URL(key.url).searchParams
+  const frame = params.get(FRAME_PARAM)
+  const format = params.get(FORMAT_PARAM)
+  await putFresh(cache, cacheKey(new Request(key.url, { method: "GET" }), { managed, frame, format }), response)
 }

data/lib/coldwire/worker/events.js

@@ -75,6 +75,13 @@ self.addEventListener("message", (event) => {
   // rides along, because it is the device's choice and the worker cannot read localStorage.
   if (type === "collect") return reply(collectGarbage(event.data))
 
+  // The ceiling, applied the moment somebody picks one. Deliberate, so unlike a sweep it
+  // does not stand down without a connection.
+  if (type === "trim") return reply(applyCeiling(event.data.maxSize))
+
+  // What the page must leave out of its own tally to agree with what a sweep can take.
+  if (type === "spared") return reply(sparedUrls())
+
   // What a page missed by not listening yet, and whether it is still going on.
   if (type === "syncState") return reply({ ok: true, running: Boolean(syncing), last: lastSyncMessage })
 

data/lib/coldwire/worker/inspect.js

@@ -46,8 +46,14 @@ async function describeCached(request, response) {
 async function entrySize(response) {
   if (!response) return 0
 
-  const declared = Number(response.headers.get("Content-Length"))
-  if (Number.isFinite(declared) && declared >= 0) return declared
+  // `get` answers null for a missing header, and Number(null) is 0 — which is finite, and not
+  // negative, so it sails through the guard and reports the entry as weighing nothing. Rails
+  // sends a great deal of HTML chunked, with no Content-Length at all, so this is not an edge
+  // case: it is most pages. A collector measuring them at zero never reaches its ceiling and
+  // quietly deletes nothing, reporting success the whole time.
+  const declared = response.headers.get("Content-Length")
+  const bytes = declared === null ? NaN : Number(declared)
+  if (Number.isFinite(bytes) && bytes >= 0) return bytes
 
   return (await response.clone().blob()).size
 }
@@ -61,18 +67,111 @@ async function entrySize(response) {
 // would find the entry either way, but every distinct query string would still write its own
 // copy — a map that rewrites lat/lng/zoom on each pan would bury the cache in near-duplicates
 // of one page.
-function cacheKey(request, { managed = false } = {}) {
+// `frame` names the Turbo frame this response is a body for, and is what keeps a frame out of
+// the slot its page occupies. Defaults to whatever the request asked for; passed explicitly
+// where the caller knows better — a frame request answered with a whole document is a page,
+// and renewing an entry has to put it back where it already was.
+function cacheKey(request, { managed = false, frame = request.headers.get("Turbo-Frame"), format = formatOf(request) } = {}) {
   const headers = new Headers(request.headers)
   headers.set(TIMESTAMP_HEADER, String(Math.floor(Date.now() / 1000)))
   if (managed) headers.set(MANAGED_HEADER, "1")
 
   // `new Request(request, init)` downgrades a navigation request's mode for us; rebuilding
-  // from a URL string needs the method stated explicitly.
-  if (!IGNORE_SEARCH) return new Request(request, { headers })
+  // from a URL string needs the method stated explicitly. Only available while the URL is
+  // being kept as it is, which naming a variant is not: taking this path with a format to
+  // write stored a JSON body under the page's own key, which is the whole bug in miniature.
+  const named = Boolean(frame) || (format && format !== "page")
+  if (!IGNORE_SEARCH && !named) return new Request(request, { headers })
 
-  const url = new URL(request.url)
-  url.search = ""
-  return new Request(url.href, { method: "GET", headers })
+  return new Request(variantUrl(request.url, { frame, format }), { method: "GET", headers })
+}
+
+// Where a body of this kind lives. Built in one place because it is written by cacheKey and
+// looked for by matchStored, and a frame stored under a URL nothing asks for is a frame that
+// never answers.
+function variantUrl(url, { frame = null, format = null } = {}) {
+  const target = new URL(url)
+  if (IGNORE_SEARCH) target.search = ""
+  if (frame) target.searchParams.set(FRAME_PARAM, frame)
+  // A page is the default and says nothing, which is what leaves every entry stored before
+  // formats existed exactly where it was.
+  if (format && format !== "page") target.searchParams.set(FORMAT_PARAM, format)
+
+  return target.href
+}
+
+// The format a request negotiated for, as a short token.
+//
+// Read from the request rather than from the response, which is the opposite of what it should
+// be and is forced: the same derivation has to run when the entry is looked for again, and at
+// that moment there is no response to read. With ignore_query_params off a named key can only
+// be found by building its name, so a name the request cannot produce is a name nothing ever
+// finds.
+//
+// A page is the default and is left unnamed, which is what leaves every entry cached before
+// formats existed exactly where it was.
+function formatOf(request) {
+  const token = negotiatedFormat(request)
+  if (token === "page") return "page"
+
+  // A URL that already names its format has nothing to disambiguate. "/report.json" is JSON and
+  // nothing else, where "/report" is a page, a JSON body and a CSV depending on who asks, so the
+  // param there would be a second way of saying what the path already said.
+  //
+  // Only where the extension agrees with what was asked for. "/sites/acme.com" is a page whose
+  // last segment happens to contain a dot, and ".com" says nothing about a format — so that one
+  // keeps its param and stays apart from the JSON at the same URL.
+  return extensionFormat(request.url) === token ? "page" : token
+}
+
+// What the path itself declares, if anything. Unknown extensions say nothing and keep their
+// param, which is noisier than it needs to be and never wrong.
+const EXTENSION_FORMATS = {
+  json: "json", geojson: "json", css: "css", xml: "xml", rss: "xml", atom: "xml",
+  csv: "csv", ics: "calendar", pdf: "pdf", txt: "plain", md: "markdown",
+  png: "image", jpg: "image", jpeg: "image", gif: "image", webp: "image", avif: "image",
+  svg: "image", ico: "image"
+}
+
+function extensionFormat(url) {
+  const name = new URL(url).pathname.split("/").pop() || ""
+  const dot = name.lastIndexOf(".")
+  if (dot < 1) return "page"
+
+  return EXTENSION_FORMATS[name.slice(dot + 1).toLowerCase()] || "page"
+}
+
+function negotiatedFormat(request) {
+  const accept = (request.headers.get("Accept") || "").split(",")[0].split(";")[0].trim().toLowerCase()
+
+  // Nothing definite asked for. A precache, a fetch that set no Accept, a browser asking for a
+  // script or a font: all of them get the unnamed key, as they always have.
+  if (!accept || accept === "*/*" || accept.includes("html")) return "page"
+
+  const [ top, sub = "" ] = accept.split("/")
+  // image/avif and image/webp are one question asked two ways, and which one a browser puts
+  // first is not a distinction worth a second copy. The family is the answer.
+  if (top && top !== "text" && top !== "application") return top
+
+  // "application/vnd.api+json" is JSON. "text/csv" is csv.
+  const parts = sub.split("+")
+  const token = (parts.length > 1 ? parts[parts.length - 1] : parts[0]) || ""
+
+  return token.replace(/[^a-z0-9.-]/g, "") || "page"
+}
+
+// What kind of body an entry holds, read back off its key. Documents have none of these
+// params and answer to null, which is what an ordinary visit asks for.
+function variantOf(key) {
+  const params = new URL(key.url).searchParams
+  // Downloads are their own thing entirely and must never answer a page request, which
+  // ignoreSearch would otherwise let them do.
+  if (params.has(CHUNK_PARAM) || params.has(RANGE_PARAM)) return "download"
+
+  const frame = params.get(FRAME_PARAM)
+  if (frame) return `frame:${frame}`
+
+  return params.get(FORMAT_PARAM) || "page"
 }
 
 function unixTimestamp(value) {

data/lib/coldwire/worker/rules.js

@@ -96,5 +96,9 @@ function isAutoCacheable(request) {
 // network error by spec, so the app fails to launch offline rather than showing the
 // cached page. Never store one.
 function isCacheable(request, response) {
-  return request.method === "GET" && response.ok && !response.redirected
+  if (request.method !== "GET" || !response.ok || response.redirected) return false
+
+  // A stream is a list of changes to make to a page, not a page. Stored, it would sit in the
+  // slot the page occupies and be replayed later against a DOM it was never written for.
+  return !(response.headers.get("Content-Type") || "").includes(STREAM_TYPE)
 }