coldwire-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e48a15a424535143cc620dbbe65eec4a367c9e1feaa60addc104587ee835c836
-  data.tar.gz: b85fc7cfc8b80db94b14e994afbb258cc997d0b161986738e80c33a8a49704d5
+  metadata.gz: b5e35d2c0930a9eac9b39b725205a467bda9a982b1fb543f127e3f2a0cd3adbe
+  data.tar.gz: 2bb1ad7cb8ded065ad6820885ca8429c582f0bc688a9c2eb288328e85e02591d
 SHA512:
-  metadata.gz: 543c39e2d9999a45ce8041d4c87cb2853908056611bdc189d49e0fde87309373260131f433f92715d29943fcd44eb1d429aa6f270ef639287c0d45ce86787f11
-  data.tar.gz: 31bc9a01f008bd987c79700058b49682cae9d1020e873bf9aab03949fe9d15d9619c420c7b5c9efe7032a6b07eddaa090b54d43adecd9cf2f503983d4e702632
+  metadata.gz: d15283073b65d9100749f0247c5ca4abebcdcfbbe429218499212ce67898b078a8222e6ebc533b8c1051607051e113ecf7ea12bfcc3273c16698859ce6c77e11
+  data.tar.gz: 9573b8cc389f6519222d606cdb1feb0a6019dc76024902d041f18697bb9d70fc149ddb88ce2c6ffe44da8267d25cbc232fe66758b4b8179c0eebc63fa63986ae

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [0.4.0]
+
+- Updated the offline page to restructure storage and downloads.
+- Updated the storage so when you change storage size it triggers a garbage collection.
+
 ## [0.3.0]
 
 - **`cache_origins` is `cacheable_hosts`**, and takes bare hosts: `"tiles.example.com"` rather
@@ -31,7 +36,10 @@ First release. The API may still change before 1.0.
   revisits everything. The ceiling is offered as a ladder of sizes on the offline settings
   page and remembered per device, since how much of a phone to spend is not something an app
   can know. It measures only what a sweep may take: downloaded archives are an opt-in spend
-  of somebody's data plan, so they are neither counted nor evicted.
+  of somebody's data plan, so they are neither counted nor evicted. Choosing a size applies it
+  at once rather than at the next sweep, and that pass does not wait for a connection: it is a
+  deliberate instruction about somebody's own storage, which is how Clear cache has always
+  behaved.
   On by default, unlike syncing: it spends no data. A sweep runs only with a
   connection it has confirmed by pinging `probe_path`, because deleting is the one cache
   operation with no way back. Age is measured from last use, not from when an entry was

data/README.md

@@ -25,7 +25,7 @@ Works the same in a plain  web app, an installed PWA, or Hotwire Native.
 
 ## What you get
 
-- **[Setup in 30 seconds](docs/setup.md):** Instal gem, then `bin/rails coldwire:install`. The rest has working defaults.
+- **[Setup in 30 seconds](docs/setup.md):** Install gem, then `bin/rails coldwire:install`. The rest has working defaults.
 - **[Cache as you go](docs/configuration.md#cache_as_you_go):** Defaults to all pages get cached as your navigate, customize to only cache certain parts of the app.
 - **[Auto Sycn precaching](docs/configuration.md#auto_sync):** Define urls that can be pre-cached automatically in the background.
 - **[Garbage collection](docs/configuration.md#garbage_collection):** Entries nothing has used in two months are swept, and anything over the storage ceiling goes least recently read first — so the cache doesn't grow forever. Only with a connection; anything a page still loads is renewed on the way past. People can set the ceiling for their own device on `/offline`.

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

data/app/assets/javascripts/coldwire/cache_controller.js

@@ -43,6 +43,7 @@ export default class extends Controller {
     "autoSync",
     "syncedAt",
     "syncStatus",
+    "syncDetails",
     "syncButton",
     "syncLabel",
     "search",
@@ -129,6 +130,7 @@ export default class extends Controller {
 
     if (data.state === "started") {
       this.syncRunning = true
+      this.revealSync()
       const retired = data.retired ? `, retired ${data.retired}` : ""
       this.setSyncStatus(data.pending
         ? `Syncing ${data.pending} file${data.pending === 1 ? "" : "s"}${retired}…`
@@ -143,6 +145,7 @@ export default class extends Controller {
       // A page that opened mid-run arrives here without ever having seen "started", so this
       // branch has to be able to put the page into the running state on its own.
       this.syncRunning = true
+      this.revealSync()
       this.toggleSyncing(true)
       if (this.hasProgressTarget) this.progressTarget.hidden = false
       // The bar carries the live count; the line above stays on the high-level "what".
@@ -214,6 +217,7 @@ export default class extends Controller {
   async syncNow(event) {
     event?.preventDefault()
     this.syncSettled = false
+    this.revealSync()
     // Reaching the worker takes a moment, and the ticker keeps ticking while it does.
     this.syncStarting = true
     this.toggleBusy(true)
@@ -243,6 +247,13 @@ export default class extends Controller {
     }
   }
 
+  // Everything a sync has to say lives behind the disclosure, so a run has to open it — a bar
+  // filling where nobody can see it is the same as no bar. Left open afterwards: somebody who
+  // has just watched a sync is the one person who might want the detail.
+  revealSync() {
+    if (this.hasSyncDetailsTarget) this.syncDetailsTarget.open = true
+  }
+
   setSyncStatus(text) {
     if (!this.hasSyncStatusTarget) return
 
@@ -250,24 +261,24 @@ export default class extends Controller {
     this.syncStatusTarget.hidden = !text
   }
 
+  // Inside the details, under the switch that says whether syncing is on at all. This says
+  // how often, and when it is off, that the button below still works.
   renderAutoSync() {
     if (!this.hasAutoSyncTarget) return
 
-    // The switch beside this already says whether it is on, so this line carries the one
-    // thing the switch cannot: how often.
     if (!this.autoSyncValue) {
-      this.autoSyncTarget.textContent = "Automatic syncing is off"
+      this.autoSyncTarget.textContent = "Runs only when you press Sync now."
       return
     }
 
     if (!this.autoSyncOn()) {
-      this.autoSyncTarget.textContent = "Off for this device"
+      this.autoSyncTarget.textContent = "Off for this device. Sync now still runs a pass."
       return
     }
 
     this.autoSyncTarget.textContent = this.syncIntervalValue > 0
-      ? `Syncs every ${formatInterval(this.syncIntervalValue)}`
-      : "On"
+      ? `Syncs every ${formatInterval(this.syncIntervalValue)}.`
+      : "On."
   }
 
   renderSyncedAt() {
@@ -428,6 +439,7 @@ export default class extends Controller {
       // What this page can answer by itself comes first: the cache is read directly and the
       // probe is one request. Behind the worker questions they waited out a registration that
       // may never arrive, and the page sat on "Checking…" with an empty list.
+      await this.loadSpared()
       await this.renderCache()
       await this.renderConnection()
 
@@ -835,73 +847,93 @@ export default class extends Controller {
     select.disabled = true
 
     try {
-      // A lowered ceiling that waits for the next scheduled sweep reads as a setting that did
-      // nothing. This is that same sweep, run now — and bound by the same rule, so with no
-      // connection it stands down and the line under the bar says why.
-      await this.collectNow()
+      // A ceiling that waits for the next scheduled sweep reads as a setting that did nothing,
+      // so it is applied here and now. Deliberate, so it does not stand down for want of a
+      // connection the way an automatic sweep does.
+      await this.applyCeiling()
     } finally {
       select.disabled = false
     }
   }
 
-  async collectNow() {
-    let result = null
+  async applyCeiling() {
+    // A trim over a thousand entries is a second or two, and a silent pause reads as a
+    // setting that did nothing.
+    if (this.hasUsageLabelTarget) this.usageLabelTarget.textContent = "Applying…"
 
     try {
-      result = await sendToWorker("collect", { maxSize: this.store.maxSize() }, 60000)
-    } catch {
-      // No worker controlling this page yet. The cache is unchanged and the line already
-      // says where it stands.
+      await sendToWorker("trim", { maxSize: this.store.maxSize() }, 60000)
+    } catch (error) {
+      // Say so. Swallowing this is what turned a stale worker — one registered before the app
+      // knew what a ceiling was, and still controlling this page until it is reloaded — into
+      // a setting that silently refused to bite.
+      if (this.hasUsageLabelTarget) {
+        this.usageLabelTarget.textContent = `Could not apply it: ${error.message}. Reload and try again.`
+      }
       return
     }
 
-    // Nothing was swept, so the clock stays where it is and the next page load finds the
-    // sweep still due — exactly as the head snippet treats a refused run.
-    this.sweepWaiting = Boolean(result?.offline)
-    if (!this.sweepWaiting) this.store.set(this.store.keys.collectedAt, Date.now())
-
+    await this.loadSpared()
     await this.renderCache()
   }
 
-  // What the ceiling is measured against: everything but the downloads, which are an opt-in
-  // spend of somebody's data plan and are never collected however full the cache gets — a
-  // 300 MB archive counted here would show a bar pinned full of files no sweep can touch.
+  // The worker is the only thing that knows what the offline page needs, and those entries are
+  // never collected. Read once and kept: it does not change while this page is open.
+  async loadSpared() {
+    try {
+      const result = await sendToWorker("spared", {}, 5000)
+      this.spared = new Set(result?.urls || [])
+    } catch {
+      // An older worker, or none yet. Falling back to counting everything overstates what a
+      // sweep can take, which is the safer direction for a figure somebody sets a limit from.
+      this.spared = this.spared || new Set()
+    }
+  }
+
+  // What the ceiling is measured against, which has to be what a sweep can actually take, or
+  // the bar shows an overage nothing will ever bring down. Three exclusions:
+  //
+  // Downloads, an opt-in spend of somebody's data plan, are never collected however full the
+  // cache gets — a 300 MB archive counted here would pin the bar full of untouchable files.
+  // Their sizes are on their own rows, which is where somebody reclaims that space.
+  //
+  // The offline page's own assets, which the worker spares and names for us: working them out
+  // means parsing the offline page, and only the worker holds it.
   //
-  // The worker also spares the offline page's own assets, which this cannot pick out of a
-  // list of URLs. That is a handful of files, and erring towards the larger figure is the
-  // right way round for a number somebody is deciding a limit from.
+  // Any cache but the worker's own. Bumping cache_name leaves the old one behind, and the
+  // worker only ever sweeps the one it is configured with.
   managedBytes(entries) {
-    return this.totalBytes((entries || []).filter((entry) => !entry.download))
+    const swept = window.COLDWIRE?.cacheName
+    const spared = this.spared
+
+    return this.totalBytes((entries || []).filter((entry) =>
+      !entry.download &&
+      !(spared && spared.has(entry.url)) &&
+      (!swept || !entry.cache || entry.cache === swept)))
   }
 
   renderStorage() {
     if (!this.hasUsageLabelTarget) return
 
     const limit = this.store.maxSize()
-    const used = this.managedBytes(this.entries)
+    const managed = this.managedBytes(this.entries)
 
     if (this.hasUsageTarget) this.usageTarget.hidden = limit === null
 
     if (limit === null) {
-      this.usageLabelTarget.textContent = `${formatBytes(used)} of cached pages, with no limit set.`
-      return
-    }
+      this.usageLabelTarget.textContent = `${formatBytes(managed)} of cached pages, with no limit set.`
+    } else {
+      const percent = Math.round(Math.min(managed / limit, 1) * 100)
+      if (this.hasUsageBarTarget) this.usageBarTarget.style.width = `${percent}%`
+      if (this.hasUsageTarget) this.usageTarget.setAttribute("aria-valuenow", String(percent))
 
-    const percent = Math.round(Math.min(used / limit, 1) * 100)
-    if (this.hasUsageBarTarget) this.usageBarTarget.style.width = `${percent}%`
-    if (this.hasUsageTarget) this.usageTarget.setAttribute("aria-valuenow", String(percent))
-
-    const parts = [ `${formatBytes(used)} of ${formatLimit(limit)}` ]
-    if (used > limit) {
-      // Over the ceiling is not a fault and not a promise of instant deletion: a sweep needs
-      // a connection, and says so rather than leaving somebody watching a bar that will not
-      // move.
-      parts.push(this.sweepWaiting || this.online === false
-        ? "over, waiting for a connection to sweep"
-        : "over, the oldest go on the next sweep")
-    }
+      const parts = [ `${formatBytes(managed)} of ${formatLimit(limit)} used by cached pages` ]
+      // Choosing a ceiling applies it on the spot, so this is what is left between sweeps: a
+      // cache that has grown past a ceiling nobody has touched since. The next sweep takes it.
+      if (managed > limit) parts.push("over, the oldest go on the next sweep")
 
-    this.usageLabelTarget.textContent = `${parts.join(" · ")}.`
+      this.usageLabelTarget.textContent = `${parts.join(" · ")}.`
+    }
   }
 
   renderEntries() {

data/app/views/coldwire/caches/show.html.erb

@@ -81,7 +81,7 @@
       <span>
         <span class="coldwire-setting-title">Offline support</span>
         <span class="coldwire-setting-note">
-          Cache pages so they work without a connection.
+          Enable page caching so they work without a connection.
         </span>
       </span>
     </label>
@@ -102,11 +102,84 @@
           </span>
         </span>
       </label>
+
+      <%# Syncing sits with the other two switches rather than in a card of its own: all three
+          are the same kind of thing, a choice this device makes about how Coldwire behaves. %>
+      <hr>
+
+      <% if Coldwire.config.auto_sync.enabled %>
+        <%# Only where the app configured automatic syncing at all: a switch for something that
+            was never going to happen is a switch that lies. %>
+        <label class="coldwire-setting">
+          <span class="coldwire-switch coldwire-switch--on">
+            <input type="checkbox"
+                   data-coldwire-cache-target="autoSyncToggle"
+                   data-action="change->coldwire-cache#toggleAutoSync">
+            <span aria-hidden="true"></span>
+          </span>
+          <span>
+            <span class="coldwire-setting-title">Sync on its own</span>
+            <span class="coldwire-setting-note">
+              Automatically back up pages in the background.
+            </span>
+          </span>
+        </label>
+      <% else %>
+        <p class="coldwire-facts" style="margin-top: 0;">
+          Automatically back up pages in the background.
+          <strong>Sync now</strong> runs a pass immediately.
+        </p>
+      <% end %>
+
+      <%# The clock, the button and the bar behind a disclosure. They are worth having, and
+          worth going to: under a switch you are not using they are three lines of furniture
+          on every visit. It opens itself while a sync runs, so progress is never hidden
+          behind a tap nobody knew to make. %>
+      <details class="coldwire-sync" data-coldwire-cache-target="syncDetails">
+        <summary><span>Sync details</span></summary>
+
+        <div class="coldwire-sync-body">
+          <%# How often, which the switch cannot show and the note above no longer says. %>
+          <p class="coldwire-facts" data-coldwire-cache-target="autoSync">Checking…</p>
+          <p class="coldwire-facts" data-coldwire-cache-target="syncedAt">Never synced</p>
+
+          <%# Empty until a sync has something to say, so the card does not carry a permanent
+              "Idle" that reads like debug output left in by accident. %>
+          <p class="coldwire-facts" data-coldwire-cache-target="syncStatus" hidden></p>
+
+          <div class="coldwire-actions coldwire-actions--spaced">
+            <button type="button"
+                    data-coldwire-cache-target="syncButton"
+                    class="coldwire-button"
+                    data-action="click->coldwire-cache#syncNow">
+              <span class="coldwire-spinner" data-coldwire-cache-target="spinner" aria-hidden="true" hidden></span>
+              <span data-coldwire-cache-target="syncLabel">Sync now</span>
+            </button>
+          </div>
+
+          <div style="margin-top: 0.75rem;"
+               role="progressbar"
+               aria-valuemin="0"
+               aria-valuemax="100"
+               data-coldwire-cache-target="progress"
+               hidden>
+            <div class="coldwire-track">
+              <div class="coldwire-bar" data-coldwire-cache-target="progressBar"></div>
+            </div>
+            <div class="coldwire-progress-label" data-coldwire-cache-target="progressLabel"></div>
+          </div>
+        </div>
+      </details>
     </div>
   </div>
 
   <div data-coldwire-cache-target="whenOn">
   <% gc = Coldwire.config.garbage_collection %>
+  <% archives = Coldwire.config.cache_archives %>
+  <%# Two cards, because they answer two questions. This one is what the app keeps as you
+      browse and how much of it you will allow; the next is what you chose to keep yourself.
+      One card had the first card's figure sitting a finger's width from files it does not
+      count, which read as an error in the figure. %>
   <% if gc.enabled %>
     <%# What the cache is allowed to grow to on this device. The choice is remembered here the
         way Force offline and Sync on its own are — the app sets the starting point, the person
@@ -150,94 +223,61 @@
       </div>
 
       <p class="coldwire-facts" data-coldwire-cache-target="usageLabel">Reading the cache…</p>
+
+      <% if archives.any? %>
+        <%# Said where the question comes up. Somebody reading a figure that does not match the
+            one in the header is owed the reason on the spot, not a card further down. This
+            line is about what the figure counts; what becomes of a download is the other
+            card's business, and saying it twice made both cards read as hedging. %>
+        <p class="coldwire-downloads-note">
+          Cached pages only. Downloads are counted separately, under Downloads below.
+        </p>
+      <% end %>
     </div>
   <% end %>
 
-  <div class="coldwire-card">
-    <h2>Auto Sync</h2>
+  <% if archives.any? %>
+    <%# One row per configured file, each reporting its own size. The words are the app's — the
+        page knows only that these are large, optional, and worth keeping. %>
+    <div class="coldwire-card coldwire-downloads" data-coldwire-cache-target="archives">
+      <h2>Downloads</h2>
 
-    <% if Coldwire.config.auto_sync.enabled %>
-      <%# Only where the app configured automatic syncing at all: a switch for something that
-          was never going to happen is a switch that lies. The card leads with it and lets its
-          note do the explaining, the way Force offline does. %>
-      <label class="coldwire-setting">
-        <span class="coldwire-switch coldwire-switch--on">
-          <input type="checkbox"
-                 data-coldwire-cache-target="autoSyncToggle"
-                 data-action="change->coldwire-cache#toggleAutoSync">
-          <span aria-hidden="true"></span>
-        </span>
-        <span>
-          <span class="coldwire-setting-title">Sync on its own</span>
-          <span class="coldwire-setting-note">
-            Automatically runs in the background backing up pages to be used offline.
-          </span>
-        </span>
-      </label>
-    <% else %>
-      <p class="coldwire-facts" style="margin-top: 0;">
-        Automatically runs in the background backing up pages to be used offline.
-        <strong>Sync now</strong> runs that pass immediately.
-      </p>
-    <% end %>
-
-    <p class="coldwire-facts">
-      <span data-coldwire-cache-target="autoSync">Checking…</span><br>
-      <span data-coldwire-cache-target="syncedAt">Never synced</span>
-    </p>
-
-    <%# Empty until a sync has something to say, so the card does not carry a permanent
-        "Idle" that reads like debug output left in by accident. %>
-    <p class="coldwire-facts" data-coldwire-cache-target="syncStatus" hidden></p>
-
-    <div class="coldwire-actions coldwire-actions--spaced">
-      <button type="button"
-              data-coldwire-cache-target="syncButton"
-              class="coldwire-button"
-              data-action="click->coldwire-cache#syncNow">
-        <span class="coldwire-spinner" data-coldwire-cache-target="spinner" aria-hidden="true" hidden></span>
-        <span data-coldwire-cache-target="syncLabel">Sync now</span>
-      </button>
-    </div>
+      <%# The name and what you can do about it on one line, the words underneath. The button
+          sits hard right, where the eye goes for the action, and what is happening reads under
+          both when a download is running. %>
+      <% archives.each do |archive| %>
+        <div class="coldwire-archive" data-archive-url="<%= archive[:url] %>">
+          <div class="coldwire-archive-head">
+            <div class="coldwire-archive-title"><%= archive[:title] %></div>
 
-    <div style="margin-top: 0.75rem;"
-         role="progressbar"
-         aria-valuemin="0"
-         aria-valuemax="100"
-         data-coldwire-cache-target="progress"
-         hidden>
-      <div class="coldwire-track">
-        <div class="coldwire-bar" data-coldwire-cache-target="progressBar"></div>
-      </div>
-      <div class="coldwire-progress-label" data-coldwire-cache-target="progressLabel"></div>
-    </div>
-  </div>
+            <div class="coldwire-actions coldwire-archive-actions">
+              <button type="button" class="coldwire-button"
+                      data-url="<%= archive[:url] %>"
+                      data-action="click->coldwire-cache#downloadArchive">
+                <span class="coldwire-spinner" data-archive-spinner aria-hidden="true" hidden></span>
+                <span data-archive-download-label>Download</span>
+              </button>
+              <%# Unlabelled but for its shape, as the trash is everywhere else on this page,
+                  so the pair fits beside the title rather than under it. %>
+              <button type="button"
+                      class="coldwire-button coldwire-icon-button coldwire-button--danger"
+                      title="Delete this download"
+                      aria-label="Delete <%= archive[:title] %>"
+                      data-url="<%= archive[:url] %>"
+                      data-action="click->coldwire-cache#removeArchive"
+                      data-archive-remove hidden>
+                <svg viewBox="0 0 24 24" aria-hidden="true">
+                  <path stroke-linecap="round" stroke-linejoin="round" d="<%= trash_path %>" />
+                </svg>
+              </button>
+            </div>
+          </div>
 
-  <% if Coldwire.config.cache_archives.any? %>
-    <%# One row per configured file. The words are the app's — the page knows only that these
-        are large, optional, and worth keeping. %>
-    <div class="coldwire-card" data-coldwire-cache-target="archives">
-      <% Coldwire.config.cache_archives.each do |archive| %>
-        <div class="coldwire-archive" data-archive-url="<%= archive[:url] %>">
-          <div class="coldwire-archive-title"><%= archive[:title] %></div>
+          <%# The words run the full width under both, rather than in a column the button has
+              squeezed to three syllables a line. %>
           <% if archive[:description].present? %>
             <p class="coldwire-facts"><%= archive[:description] %></p>
           <% end %>
-          <div class="coldwire-actions">
-            <button type="button" class="coldwire-button"
-                    data-url="<%= archive[:url] %>"
-                    data-action="click->coldwire-cache#downloadArchive">
-              <span class="coldwire-spinner" data-archive-spinner aria-hidden="true" hidden></span>
-              <span data-archive-download-label>Download</span>
-            </button>
-            <button type="button" class="coldwire-button coldwire-button--danger"
-                    data-url="<%= archive[:url] %>"
-                    data-action="click->coldwire-cache#removeArchive"
-                    data-archive-remove hidden>
-              Delete
-            </button>
-          </div>
-
           <p class="coldwire-facts coldwire-archive-meta" data-archive-status>Checking…</p>
 
           <div style="margin-top: 0.75rem;" role="progressbar" aria-valuemin="0" aria-valuemax="100"
@@ -247,6 +287,15 @@
           </div>
         </div>
       <% end %>
+
+      <% if gc.enabled %>
+        <%# The reassurance belongs with the files it is about: a 300 MB download sitting under
+            a storage limit raises the question of whether the app is about to take it back. %>
+        <p class="coldwire-downloads-note">
+          Yours until you delete them. <strong>Keep at most</strong> never counts a download,
+          and never clears one to make room.
+        </p>
+      <% end %>
     </div>
   <% end %>
 

data/docs/configuration.md

@@ -203,7 +203,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 +269,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 +561,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/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/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) {

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
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coldwire-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Noreaster Group, Stuart Yamartino