coldwire-rails 0.1.0 → 0.3.0

data/docs/configuration.md

@@ -9,12 +9,25 @@ Coldwire.configure do |config|
   config.auto_sync do |sync|
     sync.enabled = false
     sync.precache_urls = -> { [] }
-    sync.interval = 6.hours
-    sync.max_age = 7.days
+    sync.interval = 1.day
+    sync.max_age = 30.days
     sync.concurrency = 4
   end
 
-  config.cache_identity = -> { nil }
+  config.garbage_collection do |gc|
+    gc.enabled = true
+    gc.max_age = 60.days
+    gc.max_size = 250.megabytes
+    gc.interval = 1.day
+  end
+
+  config.cache_identity = -> {
+    if respond_to?(:current_user)
+      current_user&.id
+    elsif defined?(Current) && Current.respond_to?(:user)
+      Current.user&.id
+    end
+  }
   config.register_if = -> { true }
   config.caching_enabled_by_default = true
   config.offline_import = "@hotwired/turbo-rails"
@@ -23,7 +36,7 @@ Coldwire.configure do |config|
   config.never_cache = []
   config.never_intercept = [ "/up" ]
 
-  config.cache_origins = []
+  config.cacheable_hosts = []
   config.cache_ranges = []
   config.cache_archives = []
 
@@ -44,17 +57,21 @@ down with it.
 |---|---|---|
 | [`auto_sync.enabled`](#autosyncenabled) | `false` | Keep the precache manifest current on an interval |
 | [`auto_sync.precache_urls`](#autosyncprecache_urls) | `-> { [] }` | The pages to fetch, evaluated against your URL helpers |
-| [`auto_sync.interval`](#autosyncinterval) | `6.hours` | How long to leave between syncs |
-| [`auto_sync.max_age`](#autosyncmax_age) | `7.days` | Refetch a cached manifest page once it is older than this |
+| [`auto_sync.interval`](#autosyncinterval) | `1.day` | How long to leave between syncs |
+| [`auto_sync.max_age`](#autosyncmax_age) | `30.days` | Refetch a cached manifest page once it is older than this |
 | [`auto_sync.concurrency`](#autosyncconcurrency) | `4` | Fetches in flight at once during a sync |
-| [`cache_identity`](#cache_identity) | `-> { nil }` | Who the cache belongs to; changing it drops the cache |
+| [`garbage_collection.enabled`](#garbage_collectionenabled) | `true` | Sweep entries nothing has used in a long time |
+| [`garbage_collection.max_age`](#garbage_collectionmax_age) | `60.days` | How long an entry may go untouched before it is collected |
+| [`garbage_collection.max_size`](#garbage_collectionmax_size) | `250.megabytes` | How much the cache may hold; over it the least recently read go first |
+| [`garbage_collection.interval`](#garbage_collectioninterval) | `1.day` | How long to leave between sweeps |
+| [`cache_identity`](#cache_identity) | `current_user` / `Current.user` | Who the cache belongs to; changing it drops the cache |
 | [`register_if`](#register_if) | `-> { true }` | Whether a page registers the worker at all |
 | [`caching_enabled_by_default`](#caching_enabled_by_default) | `true` | Starting position of the Offline support switch. Not a master on/off |
 | [`offline_import`](#offline_import) | `"@hotwired/turbo-rails"` | Importmap module the offline page loads to boot Turbo |
 | [`cache_as_you_go`](#cache_as_you_go) | `["/*"]` | Pages stored as somebody browses. `/*` is everything |
 | [`never_cache`](#never_cache) | `[]` | Never stored, by any route in. The one veto |
 | [`never_intercept`](#never_intercept) | `["/up"]` | Paths the worker does not touch at all |
-| [`cache_origins`](#cache_origins) | `[]` | Other origins the worker may cache |
+| [`cacheable_hosts`](#cacheable_hosts) | `[]` | Other hosts the worker may cache |
 | [`cache_ranges`](#cache_ranges) | `[]` | URLs whose `Range` requests are cached piece by piece |
 | [`cache_archives`](#cache_archives) | `[]` | Large files somebody can choose to download |
 | [`ignore_query_params`](#ignore_query_params) | `true` | Treat `/map` and `/map?zoom=9` as one page |
@@ -74,8 +91,8 @@ fetched, an interval with no manifest has nothing to fetch.
 config.auto_sync do |sync|
   sync.enabled = true
   sync.precache_urls = -> { Site.published.map { |site| site_path(site) } }
-  sync.interval = 6.hours
-  sync.max_age = 7.days
+  sync.interval = 1.day
+  sync.max_age = 30.days
   sync.concurrency = 4
 end
 ```
@@ -105,7 +122,7 @@ The offline settings page has a per-device switch that turns automatic syncing o
 `localStorage`. Switched off, no page holds a sync timer; **Sync now** still runs a pass.
 
 <p align="center">
-  <img src="images/offline-settings.png" alt="Offline settings: status, force offline, auto sync, and downloads" width="280">
+  <img src="images/offline-settings.png" alt="Offline settings: status, force offline, the storage limit, auto sync, and downloads" width="280">
   <img src="images/offline-settings-cached.png" alt="Offline settings: every cached entry, with search, sort, and delete" width="280">
 </p>
 
@@ -139,7 +156,7 @@ A stored page's stylesheets, scripts, and images are fetched with it, whatever t
 
 ### `auto_sync.interval`
 
-**Default:** `6.hours`
+**Default:** `1.day`
 
 How long to leave between syncs. An ActiveSupport duration works; the worker receives
 seconds. Leave this long — a sync is a burst of fetches, not something to run on every
@@ -150,7 +167,7 @@ config change follows the new value rather than the one it was born with.
 
 ### `auto_sync.max_age`
 
-**Default:** `7.days`
+**Default:** `30.days`
 
 Refetch a manifest page once its cached copy is older than this. `nil` fetches only what is
 missing, so pages already cached are never noticed to have changed.
@@ -164,20 +181,141 @@ once would stall the app's own requests behind hundreds of connections.
 
 ---
 
+## `garbage_collection`
+
+A cache that fills as people browse fills forever. Collection takes back what nothing has
+asked for in a long time.
+
+```ruby
+config.garbage_collection do |gc|
+  gc.enabled = true
+  gc.max_age = 60.days
+  gc.max_size = 250.megabytes
+  gc.interval = 1.day
+end
+```
+
+Two limits, and a sweep applies both: `max_age` takes what has gone unused, then `max_size`
+takes the least recently read of what is left until the cache fits. The second is the one that
+binds on a device that browses far more than it revisits, where nothing is ever old enough to
+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
+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
+first fetched. Storing a page renews everything it names, so the stylesheet every page in your
+app loads keeps a fresh date even though nothing ever refetches it. Without that, an asset
+would carry the date of the very first page that pulled it in and be collected while the whole
+app was still using it.
+
+Renewal rewrites from the cache — it is never a network request — and only once an entry has
+aged past a quarter of `max_age`. Under that it costs a lookup, so an ordinary navigation is
+not rewriting every asset the page names.
+
+Two things are never collected, whatever their age or how full the cache is — and neither is
+counted against `max_size`, since the ceiling has to measure what a sweep can actually act on:
+
+| | |
+|---|---|
+| **What the offline page needs** | browsing never touches it, and it is wanted precisely when there is no network |
+| **Downloaded archives** | somebody chose to spend a data plan on those; disuse does not make them safe to throw away |
+
+A sweep is paced by an open page the same way a sync is, for the same reason: nothing can wake
+a worker in a WebKit web view. It is not recorded unless it actually ran, so a device that has
+been offline for a week sweeps on its next page load with a connection.
+
+### `garbage_collection.enabled`
+
+```ruby
+config.garbage_collection { |gc| gc.enabled = false }
+```
+
+On by default, unlike [`auto_sync`](#auto_sync). Syncing spends somebody's data plan, which is
+theirs to opt into; a sweep spends nothing and the alternative is a cache that grows on their
+phone until the browser evicts the whole thing. Off, nothing is collected and nothing is
+renewed.
+
+### `garbage_collection.max_age`
+
+```ruby
+config.garbage_collection { |gc| gc.max_age = 60.days }
+```
+
+How long an entry may go untouched before a sweep takes it. `nil` collects nothing, which is
+the same as `enabled = false`.
+
+Keep it comfortably longer than [`auto_sync.max_age`](#autosyncmax_age). A manifest page is
+refetched once its copy is older than that, so as long as collection outlives refetching, a
+sync brings a page back up to date well before a sweep would consider it. The defaults leave
+60 days against 30.
+
+### `garbage_collection.max_size`
+
+```ruby
+config.garbage_collection { |gc| gc.max_size = 500.megabytes }
+```
+
+How much the cache may hold, in bytes. Past it a sweep deletes the least recently read entry,
+then the next, until what is left fits — the same clock `max_age` works from, so an entry
+renewed because a page still loads it is among the last to go rather than the first. `nil` is
+no ceiling.
+
+Measured over what a sweep is allowed to take, which is everything but the offline page's own
+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.
+
+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.
+
+### `garbage_collection.interval`
+
+```ruby
+config.garbage_collection { |gc| gc.interval = 12.hours }
+```
+
+How long to leave between sweeps. A sweep reads the cache index and deletes; there is nothing
+to pace against a network, so this is about not doing pointless work on every page load rather
+than about cost.
+
+It is also how long the cache may exceed [`max_size`](#garbage_collectionmax_size), since that
+is when the ceiling is applied. A sweep with a ceiling set costs a `match` per entry to measure
+what is there, which is why it is worth pacing at all.
+
+---
+
 ## `cache_identity`
 
-**Default:** `-> { nil }`
+**Default:** `current_user&.id` or `Current.user&.id` when either is in scope
 
 Who the cache belongs to, usually the signed-in user's id. Evaluated in the view, so
-`current_user` is in scope. Recorded in `localStorage`; when it changes between page loads
-the cache is dropped — which is what makes signing out, and switching accounts, safe.
+`current_user` is in scope — and `Current.user` if you keep the user there instead.
+Recorded in `localStorage`; when it changes between page loads the cache is dropped —
+which is what makes signing out, and switching accounts, safe.
 
 ```ruby
-config.cache_identity = -> { current_user&.id }
+config.cache_identity = -> {
+  if respond_to?(:current_user)
+    current_user&.id
+  elsif defined?(Current) && Current.respond_to?(:user)
+    Current.user&.id
+  end
+}
 ```
 
-Leave it unset and the cache persists across sessions: fine for a single-user or fully
-public app, wrong for anything else.
+That is what the installer writes. If neither helper exists, the identity is empty and the
+cache persists across sessions — fine for a single-user or fully public app. Override it
+if your signed-in user lives somewhere else.
 
 A few edges the setting already handles:
 
@@ -359,22 +497,28 @@ config.never_cache = [ %r{^/admin(/|$)}, %r{^/users/[^/]+/edit$} ]
 
 ---
 
-## `cache_origins`
+## `cacheable_hosts`
 
 **Default:** `[]`
 
-Origins besides your own that the worker may cache. Each has to send CORS headers naming
-your app, or the response arrives opaque — status 0, no headers, no readable body — and
-there is nothing worth storing. Ranged sources must also expose `Content-Range`.
+The hosts besides your own that the worker may cache. Each has to send CORS headers naming
+your app, or the response arrives opaque — status 0, no headers, no readable body — and there
+is nothing worth storing. Ranged sources must also expose `Content-Range`.
 
 ```ruby
-config.cache_origins = [ "https://tiles.example.com" ]
+config.cacheable_hosts = [ "tiles.example.com", "localhost:3001" ]
 ```
 
-Bare origins only: a scheme and a host, no path, no trailing slash. Anything else raises at
-boot, because a malformed origin silently fails to match a request's origin.
+Just the host. No scheme: a worker runs only on a secure page, and a secure page cannot fetch
+`http`, so there was never a second scheme for one to tell apart. Writing one raises at boot
+rather than being stripped — a scheme quietly accepted is a config that looks migrated and is
+not, and the error names what to write instead.
+
+A port only where it is not the default. A request is matched on its URL's `host`, against
+exactly what you wrote: `localhost:3001` matches that port and no other, and a subdomain is a
+different host.
 
-Cross-origin requests are passed through unless the origin is listed here.
+Requests to anywhere else are passed straight through — not intercepted, not stored.
 
 ---
 
@@ -392,7 +536,7 @@ config.cache_ranges = [ "/tiles/*", %r{\.pmtiles$} ]
 
 Patterns match the URL path, same as the other lists — not the full URL. A cross-origin
 tile at `https://tiles.example.com/basemap.pmtiles` is allowed only when that origin is in
-[`cache_origins`](#cache_origins) *and* its path matches a rule here.
+[`cacheable_hosts`](#cacheable_hosts) *and* its path matches a rule here.
 
 This pairs with [`cache_archives`](#cache_archives): `cache_ranges` caches the slices
 actually read, so the places you have already opened work offline, and downloading the
@@ -423,7 +567,7 @@ Files arrive in 8 MB chunks, which is what makes a dropped connection cost secon
 of the whole download. A `Range` request against a downloaded archive is answered by
 slicing the chunks.
 
-If the file lives on another origin, list that origin in [`cache_origins`](#cache_origins).
+If the file lives on another host, list it in [`cacheable_hosts`](#cacheable_hosts).
 
 ---
 
@@ -478,14 +622,24 @@ for the first paint of a cold boot, before any JS runs, and a `<meta name="coldw
 for Turbo visits, since Turbo merges the head but never copies `<html>` attributes.
 `coldwire_service_worker_tag` mirrors the meta onto `<html>` on each `turbo:load`.
 
-Any CSS can key off the attribute. With Tailwind v4, two custom variants give you
-`offline:` and `online:`:
+Any CSS can key off the attribute.
+
+### Tailwind variants
+
+With Tailwind v4, two custom variants give you `offline:` and `online:`:
 
 ```css
 @custom-variant offline (html[data-coldwire-offline] &);
 @custom-variant online (html:not([data-coldwire-offline]) &);
 ```
 
+Then show or hide content from the markup:
+
+```html
+<p class="offline:hidden">You're online.</p>
+<p class="online:hidden">You're looking at a cached page.</p>
+```
+
 From JavaScript, `window.Coldwire`:
 
 ```js

data/docs/how-it-works.md

@@ -2,7 +2,7 @@
 
 Six things break a naive offline cache in a Hotwire app. Four bite you in any browser; two
 are Hotwire Native holding you to a stricter standard. Coldwire handles all six, which is
-what lets one cache serve a plain Hotwire app, a PWA, and Hotwire Native.
+what lets one cache serve a plain Hotwire web app, a PWA, and Hotwire Native.
 
 When a visit has no cached copy and no network, people see this — a `200` that boots
 Turbo — rather than a native error screen:

data/docs/images/coldwire-logo-dark.svg

@@ -0,0 +1,57 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 626 190" width="626" height="190" role="img" aria-label="Coldwire — Offline">
+<g stroke-linejoin="round" stroke-linecap="round">
+<path d="M 57.24 107.00 C 57.44 116.36 62.24 125.20 64.00 133.00 C 65.76 125.20 70.56 116.36 70.76 107.00 Z" fill="#0B1220" stroke="#0B1220" stroke-width="3.6"/>
+<path d="M 77.60 107.00 C 77.91 121.40 85.30 135.00 88.00 147.00 C 90.70 135.00 98.09 121.40 98.40 107.00 Z" fill="#0B1220" stroke="#0B1220" stroke-width="3.6"/>
+<path d="M 104.20 107.00 C 104.43 117.80 109.97 128.00 112.00 137.00 C 114.03 128.00 119.57 117.80 119.80 107.00 Z" fill="#0B1220" stroke="#0B1220" stroke-width="3.6"/>
+<path d="M 129.32 107.00 C 129.46 113.48 132.78 119.60 134.00 125.00 C 135.22 119.60 138.54 113.48 138.68 107.00 Z" fill="#0B1220" stroke="#0B1220" stroke-width="3.6"/>
+<path d="M 57.24 107.00 C 57.44 116.36 62.24 125.20 64.00 133.00 C 65.76 125.20 70.56 116.36 70.76 107.00 Z" fill="#F0F9FF" stroke="none"/>
+<path d="M 77.60 107.00 C 77.91 121.40 85.30 135.00 88.00 147.00 C 90.70 135.00 98.09 121.40 98.40 107.00 Z" fill="#F0F9FF" stroke="none"/>
+<path d="M 104.20 107.00 C 104.43 117.80 109.97 128.00 112.00 137.00 C 114.03 128.00 119.57 117.80 119.80 107.00 Z" fill="#F0F9FF" stroke="none"/>
+<path d="M 129.32 107.00 C 129.46 113.48 132.78 119.60 134.00 125.00 C 135.22 119.60 138.54 113.48 138.68 107.00 Z" fill="#F0F9FF" stroke="none"/>
+<g fill="#0B1220" stroke="#0B1220" stroke-width="8">
+<rect x="54" y="58.80" width="96" height="57.20" rx="28.60" ry="28.60"/>
+<circle cx="54" cy="92" r="26"/>
+<circle cx="88" cy="66" r="36"/>
+<circle cx="124" cy="78" r="28"/>
+<circle cx="150" cy="94" r="22"/>
+</g>
+<g fill="#38BDF8" stroke="none">
+<rect x="54" y="58.80" width="96" height="57.20" rx="28.60" ry="28.60"/>
+<circle cx="54" cy="92" r="26"/>
+<circle cx="88" cy="66" r="36"/>
+<circle cx="124" cy="78" r="28"/>
+<circle cx="150" cy="94" r="22"/>
+</g>
+<g fill="none" stroke="#E6EDF3" stroke-width="9" stroke-linecap="round">
+<path d="M 228.62 69.98 A 22 22 0 1 0 228.62 106.02"/>
+<path d="M 254.00 88 A 22 22 0 1 0 298.00 88 A 22 22 0 1 0 254.00 88"/>
+<path d="M 320 34 L 320 110"/>
+<path d="M 346.00 88 A 22 22 0 1 0 390.00 88 A 22 22 0 1 0 346.00 88"/>
+<path d="M 390 34 L 390 110"/>
+<path d="M 410 66 L 421 110 L 432 74 L 443 110 L 454 66"/>
+<path d="M 476 66 L 476 110"/>
+<path d="M 476 42 L 476 42"/>
+<path d="M 506 66 L 506 110"/>
+<path d="M 506 82 A 20 20 0 0 1 530 66"/>
+<path d="M 590.00 88.00 L 546.00 88"/>
+<path d="M 590.00 88.00 A 22 22 0 1 0 579.00 107.05"/>
+</g>
+<g fill="none" stroke="#94A3B8" stroke-width="9" stroke-linecap="round" transform="translate(445.12 107.40) scale(0.46)">
+<path d="M 0.00 88 A 22 22 0 1 0 44.00 88 A 22 22 0 1 0 0.00 88"/>
+<path d="M 75 110 L 75 48"/>
+<path d="M 75 48 A 17 17 0 0 1 92 34"/>
+<path d="M 62 66 L 91 66"/>
+<path d="M 121 110 L 121 48"/>
+<path d="M 121 48 A 17 17 0 0 1 138 34"/>
+<path d="M 108 66 L 137 66"/>
+<path d="M 158 34 L 158 110"/>
+<path d="M 188 66 L 188 110"/>
+<path d="M 188 42 L 188 42"/>
+<path d="M 218 66 L 218 110"/>
+<path d="M 218 86 A 20 20 0 0 1 258 86"/>
+<path d="M 258 86 L 258 110"/>
+<path d="M 322.00 88.00 L 278.00 88"/>
+<path d="M 322.00 88.00 A 22 22 0 1 0 311.00 107.05"/>
+</g>
+</g>
+</svg>

data/docs/images/coldwire-logo.svg

@@ -0,0 +1,57 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 626 190" width="626" height="190" role="img" aria-label="Coldwire — Offline">
+<g stroke-linejoin="round" stroke-linecap="round">
+<path d="M 57.24 107.00 C 57.44 116.36 62.24 125.20 64.00 133.00 C 65.76 125.20 70.56 116.36 70.76 107.00 Z" fill="#0F172A" stroke="#0F172A" stroke-width="3.6"/>
+<path d="M 77.60 107.00 C 77.91 121.40 85.30 135.00 88.00 147.00 C 90.70 135.00 98.09 121.40 98.40 107.00 Z" fill="#0F172A" stroke="#0F172A" stroke-width="3.6"/>
+<path d="M 104.20 107.00 C 104.43 117.80 109.97 128.00 112.00 137.00 C 114.03 128.00 119.57 117.80 119.80 107.00 Z" fill="#0F172A" stroke="#0F172A" stroke-width="3.6"/>
+<path d="M 129.32 107.00 C 129.46 113.48 132.78 119.60 134.00 125.00 C 135.22 119.60 138.54 113.48 138.68 107.00 Z" fill="#0F172A" stroke="#0F172A" stroke-width="3.6"/>
+<path d="M 57.24 107.00 C 57.44 116.36 62.24 125.20 64.00 133.00 C 65.76 125.20 70.56 116.36 70.76 107.00 Z" fill="#E0F2FE" stroke="none"/>
+<path d="M 77.60 107.00 C 77.91 121.40 85.30 135.00 88.00 147.00 C 90.70 135.00 98.09 121.40 98.40 107.00 Z" fill="#E0F2FE" stroke="none"/>
+<path d="M 104.20 107.00 C 104.43 117.80 109.97 128.00 112.00 137.00 C 114.03 128.00 119.57 117.80 119.80 107.00 Z" fill="#E0F2FE" stroke="none"/>
+<path d="M 129.32 107.00 C 129.46 113.48 132.78 119.60 134.00 125.00 C 135.22 119.60 138.54 113.48 138.68 107.00 Z" fill="#E0F2FE" stroke="none"/>
+<g fill="#0F172A" stroke="#0F172A" stroke-width="8">
+<rect x="54" y="58.80" width="96" height="57.20" rx="28.60" ry="28.60"/>
+<circle cx="54" cy="92" r="26"/>
+<circle cx="88" cy="66" r="36"/>
+<circle cx="124" cy="78" r="28"/>
+<circle cx="150" cy="94" r="22"/>
+</g>
+<g fill="#0EA5E9" stroke="none">
+<rect x="54" y="58.80" width="96" height="57.20" rx="28.60" ry="28.60"/>
+<circle cx="54" cy="92" r="26"/>
+<circle cx="88" cy="66" r="36"/>
+<circle cx="124" cy="78" r="28"/>
+<circle cx="150" cy="94" r="22"/>
+</g>
+<g fill="none" stroke="#0F172A" stroke-width="9" stroke-linecap="round">
+<path d="M 228.62 69.98 A 22 22 0 1 0 228.62 106.02"/>
+<path d="M 254.00 88 A 22 22 0 1 0 298.00 88 A 22 22 0 1 0 254.00 88"/>
+<path d="M 320 34 L 320 110"/>
+<path d="M 346.00 88 A 22 22 0 1 0 390.00 88 A 22 22 0 1 0 346.00 88"/>
+<path d="M 390 34 L 390 110"/>
+<path d="M 410 66 L 421 110 L 432 74 L 443 110 L 454 66"/>
+<path d="M 476 66 L 476 110"/>
+<path d="M 476 42 L 476 42"/>
+<path d="M 506 66 L 506 110"/>
+<path d="M 506 82 A 20 20 0 0 1 530 66"/>
+<path d="M 590.00 88.00 L 546.00 88"/>
+<path d="M 590.00 88.00 A 22 22 0 1 0 579.00 107.05"/>
+</g>
+<g fill="none" stroke="#64748B" stroke-width="9" stroke-linecap="round" transform="translate(445.12 107.40) scale(0.46)">
+<path d="M 0.00 88 A 22 22 0 1 0 44.00 88 A 22 22 0 1 0 0.00 88"/>
+<path d="M 75 110 L 75 48"/>
+<path d="M 75 48 A 17 17 0 0 1 92 34"/>
+<path d="M 62 66 L 91 66"/>
+<path d="M 121 110 L 121 48"/>
+<path d="M 121 48 A 17 17 0 0 1 138 34"/>
+<path d="M 108 66 L 137 66"/>
+<path d="M 158 34 L 158 110"/>
+<path d="M 188 66 L 188 110"/>
+<path d="M 188 42 L 188 42"/>
+<path d="M 218 66 L 218 110"/>
+<path d="M 218 86 A 20 20 0 0 1 258 86"/>
+<path d="M 258 86 L 258 110"/>
+<path d="M 322.00 88.00 L 278.00 88"/>
+<path d="M 322.00 88.00 A 22 22 0 1 0 311.00 107.05"/>
+</g>
+</g>
+</svg>

data/docs/images/coldwire-mark-dark.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="22 22 158 142" width="158" height="142" role="img" aria-label="Coldwire">
+<g stroke-linejoin="round" stroke-linecap="round">
+<path d="M 57.24 107.00 C 57.44 116.36 62.24 125.20 64.00 133.00 C 65.76 125.20 70.56 116.36 70.76 107.00 Z" fill="#0B1220" stroke="#0B1220" stroke-width="3.6"/>
+<path d="M 77.60 107.00 C 77.91 121.40 85.30 135.00 88.00 147.00 C 90.70 135.00 98.09 121.40 98.40 107.00 Z" fill="#0B1220" stroke="#0B1220" stroke-width="3.6"/>
+<path d="M 104.20 107.00 C 104.43 117.80 109.97 128.00 112.00 137.00 C 114.03 128.00 119.57 117.80 119.80 107.00 Z" fill="#0B1220" stroke="#0B1220" stroke-width="3.6"/>
+<path d="M 129.32 107.00 C 129.46 113.48 132.78 119.60 134.00 125.00 C 135.22 119.60 138.54 113.48 138.68 107.00 Z" fill="#0B1220" stroke="#0B1220" stroke-width="3.6"/>
+<path d="M 57.24 107.00 C 57.44 116.36 62.24 125.20 64.00 133.00 C 65.76 125.20 70.56 116.36 70.76 107.00 Z" fill="#F0F9FF" stroke="none"/>
+<path d="M 77.60 107.00 C 77.91 121.40 85.30 135.00 88.00 147.00 C 90.70 135.00 98.09 121.40 98.40 107.00 Z" fill="#F0F9FF" stroke="none"/>
+<path d="M 104.20 107.00 C 104.43 117.80 109.97 128.00 112.00 137.00 C 114.03 128.00 119.57 117.80 119.80 107.00 Z" fill="#F0F9FF" stroke="none"/>
+<path d="M 129.32 107.00 C 129.46 113.48 132.78 119.60 134.00 125.00 C 135.22 119.60 138.54 113.48 138.68 107.00 Z" fill="#F0F9FF" stroke="none"/>
+<g fill="#0B1220" stroke="#0B1220" stroke-width="8">
+<rect x="54" y="58.80" width="96" height="57.20" rx="28.60" ry="28.60"/>
+<circle cx="54" cy="92" r="26"/>
+<circle cx="88" cy="66" r="36"/>
+<circle cx="124" cy="78" r="28"/>
+<circle cx="150" cy="94" r="22"/>
+</g>
+<g fill="#38BDF8" stroke="none">
+<rect x="54" y="58.80" width="96" height="57.20" rx="28.60" ry="28.60"/>
+<circle cx="54" cy="92" r="26"/>
+<circle cx="88" cy="66" r="36"/>
+<circle cx="124" cy="78" r="28"/>
+<circle cx="150" cy="94" r="22"/>
+</g>
+</g>
+</svg>

data/docs/images/coldwire-mark.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="22 22 158 142" width="158" height="142" role="img" aria-label="Coldwire">
+<g stroke-linejoin="round" stroke-linecap="round">
+<path d="M 57.24 107.00 C 57.44 116.36 62.24 125.20 64.00 133.00 C 65.76 125.20 70.56 116.36 70.76 107.00 Z" fill="#0F172A" stroke="#0F172A" stroke-width="3.6"/>
+<path d="M 77.60 107.00 C 77.91 121.40 85.30 135.00 88.00 147.00 C 90.70 135.00 98.09 121.40 98.40 107.00 Z" fill="#0F172A" stroke="#0F172A" stroke-width="3.6"/>
+<path d="M 104.20 107.00 C 104.43 117.80 109.97 128.00 112.00 137.00 C 114.03 128.00 119.57 117.80 119.80 107.00 Z" fill="#0F172A" stroke="#0F172A" stroke-width="3.6"/>
+<path d="M 129.32 107.00 C 129.46 113.48 132.78 119.60 134.00 125.00 C 135.22 119.60 138.54 113.48 138.68 107.00 Z" fill="#0F172A" stroke="#0F172A" stroke-width="3.6"/>
+<path d="M 57.24 107.00 C 57.44 116.36 62.24 125.20 64.00 133.00 C 65.76 125.20 70.56 116.36 70.76 107.00 Z" fill="#E0F2FE" stroke="none"/>
+<path d="M 77.60 107.00 C 77.91 121.40 85.30 135.00 88.00 147.00 C 90.70 135.00 98.09 121.40 98.40 107.00 Z" fill="#E0F2FE" stroke="none"/>
+<path d="M 104.20 107.00 C 104.43 117.80 109.97 128.00 112.00 137.00 C 114.03 128.00 119.57 117.80 119.80 107.00 Z" fill="#E0F2FE" stroke="none"/>
+<path d="M 129.32 107.00 C 129.46 113.48 132.78 119.60 134.00 125.00 C 135.22 119.60 138.54 113.48 138.68 107.00 Z" fill="#E0F2FE" stroke="none"/>
+<g fill="#0F172A" stroke="#0F172A" stroke-width="8">
+<rect x="54" y="58.80" width="96" height="57.20" rx="28.60" ry="28.60"/>
+<circle cx="54" cy="92" r="26"/>
+<circle cx="88" cy="66" r="36"/>
+<circle cx="124" cy="78" r="28"/>
+<circle cx="150" cy="94" r="22"/>
+</g>
+<g fill="#0EA5E9" stroke="none">
+<rect x="54" y="58.80" width="96" height="57.20" rx="28.60" ry="28.60"/>
+<circle cx="54" cy="92" r="26"/>
+<circle cx="88" cy="66" r="36"/>
+<circle cx="124" cy="78" r="28"/>
+<circle cx="150" cy="94" r="22"/>
+</g>
+</g>
+</svg>

data/docs/setup.md

@@ -6,7 +6,7 @@ provides `Turbo`. Add the gem, then let the installer wire the rest.
 ## Requirements
 
 - Rails 7.1+
-- Turbo — a plain Hotwire app, a PWA, or Hotwire Native
+- Turbo — a plain Hotwire web app, a PWA, or Hotwire Native
 - Service workers, and HTTPS (or localhost). They are same-origin, so the engine has to be
   mounted on the app's own domain
 - Hotwire Native is optional. Nothing here requires it
@@ -102,9 +102,9 @@ Every option has a working default. The full list, and what each one does, is in
 
 ## What to set first
 
-**`cache_identity`**, if anyone signs in. Cached pages hold whatever the session that
-fetched them could see. Leave this unset and the cache persists across sessions — fine for
-a single-user or fully public app, wrong for anything else.
+**`cache_identity`**, if the signed-in user is not `current_user` or `Current.user`. Cached
+pages hold whatever the session that fetched them could see. The installer already uses
+those two when they are in scope; override it if yours lives somewhere else.
 
 ```ruby
 config.cache_identity = -> { current_user&.id }
@@ -136,7 +136,8 @@ 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, force offline, and manage what is cached.
+archives, turn auto-sync off for this device, set how much storage the cache may use, force
+offline, and manage what is cached.
 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.
@@ -144,13 +145,17 @@ Put it behind whatever authentication you use by wrapping the route, or override
 `app/views/coldwire/caches/show.html.erb`.
 
 <p align="center">
-  <img src="images/offline-settings.png" alt="Offline settings: status, force offline, auto sync, and downloads" width="280">
+  <img src="images/offline-settings.png" alt="Offline settings: status, force offline, the storage limit, auto sync, and downloads" width="280">
   <img src="images/offline-settings-cached.png" alt="Offline settings: every cached entry, with search, sort, and delete" width="280">
 </p>
 
 To reach it offline, list it in `cache_as_you_go` like any other page. **Sync now** talks to
 the manifest, which is never intercepted, so that button fails while offline; **Inspect cache**,
-**Clear cache**, and **Force offline** are client-side and keep working. The URL list lives
+**Clear cache**, and **Force offline** are client-side and keep working. **Keep at most** —
+the storage ceiling, from
+[`garbage_collection.max_size`](configuration.md#garbage_collectionmax_size) — is remembered
+straight away, but the sweep it triggers needs a connection like any other, so a lowered
+ceiling applies once there is one. The URL list lives
 under Inspect cache, closed until you open it.
 
 ## Hotwire Native on iOS
@@ -171,7 +176,7 @@ app-bound mode and takes service workers with it.
 ## Optional next steps
 
 - Restrict what browsing stores with [`cache_as_you_go`](configuration.md#cache_as_you_go)
-- Nominate other origins or `Range` URLs with [`cache_origins`](configuration.md#cache_origins)
+- Nominate other hosts or `Range` URLs with [`cacheable_hosts`](configuration.md#cacheable_hosts)
   and [`cache_ranges`](configuration.md#cache_ranges)
 - Offer large files for download with [`cache_archives`](configuration.md#cache_archives)
 - Override the offline fallback by creating

data/lib/coldwire/client/collect.js

@@ -0,0 +1,49 @@
+(function () {
+  // Turbo copies head scripts it does not recognise, and a per-request CSP nonce makes this
+  // one look new on every visit — without the guard each visit wires another listener.
+  if (window.__coldwireCollect) return
+  window.__coldwireCollect = true
+
+  var store = window.coldwireStore
+  var keys = store.keys
+  var interval = COLDWIRE.collectInterval
+
+  // Nothing like the sync scheduler here on purpose. A sweep is quick, takes no network worth
+  // pacing, and two of them at once is harmless — so there is no claim to hold, no countdown
+  // to draw, and no progress to report. A stamp and a check are the whole clock.
+  function due() {
+    var last = store.number(keys.collectedAt)
+
+    return !last || Date.now() - last >= interval
+  }
+
+  function run() {
+    if (!due()) return
+    if (store.on(keys.forced)) return
+    if (!store.cachingOn()) return
+    if (!("serviceWorker" in navigator)) return
+
+    navigator.serviceWorker.ready.then(function (registration) {
+      var worker = registration.active || navigator.serviceWorker.controller
+      if (!worker) return
+
+      var channel = new MessageChannel()
+      channel.port1.onmessage = function (event) {
+        var result = event.data
+        // No connection, or force offline: nothing was swept, so leave the clock alone and
+        // let the next page find it still due.
+        if (!result || result.offline) return
+
+        store.set(keys.collectedAt, Date.now())
+      }
+      // The ceiling travels with the request: it lives in localStorage, which a worker
+      // cannot read, and it is a choice this device made rather than one the app baked in.
+      worker.postMessage({ type: "collect", maxSize: store.maxSize() }, [ channel.port2 ])
+    })
+  }
+
+  document.addEventListener("turbo:load", run)
+  window.addEventListener("online", run)
+
+  run()
+})();