coldwire-rails 0.1.0

data/lib/coldwire/configuration.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Coldwire
+  # Host apps tune Coldwire through `Coldwire.configure`. Everything here has a working
+  # default except `precache_urls`, which only the host app can know.
+  class Configuration
+    # Name of the Cache API cache. Bump it to invalidate everything at once.
+    attr_accessor :cache_name
+
+    # Scope the worker claims. The worker is served from the engine mount point, so the
+    # response also sends `Service-Worker-Allowed` to widen it past that directory.
+    attr_accessor :worker_scope
+
+    # The importmap module the offline page loads. Hotwire Native reports "Turbo is not
+    # present" for any page where `window.Turbo` never appears, so the fallback has to boot
+    # Turbo — and Turbo alone, since one uncached module would fail the whole graph. nil if
+    # you are not on importmap-rails; load it yourself in the template instead.
+    attr_accessor :offline_import
+
+    # Stamp HTML served from cache with `data-coldwire-offline` and `data-coldwire-cached-at`,
+    # plus a <meta> that survives Turbo's head merge, so a page can say it is stale.
+    attr_accessor :mark_cached_pages
+
+    # Treat "/map" and "/map?zoom=9" as one cached page, matching and storing. Blunt: it also
+    # collapses `/search?q=`, so a cached result set can answer a different query.
+    attr_accessor :ignore_query_params
+
+    # What the offline settings page pings to tell online from offline, because navigator.onLine only
+    # reports whether an interface is up. Never intercepted — a probe answered from the cache
+    # would resolve with the network down, which is precisely backwards.
+    attr_accessor :probe_path
+
+    # Paths the worker does not touch at all, as prefix strings; the engine's own are added
+    # for you. The request goes straight to the network and so fails outright offline, showing
+    # the SDK's error screen rather than your offline page — which is what you want for a
+    # health check, and almost never what you want for a page.
+    #
+    # Not the same as `never_cache`, which is about storing. Compare:
+    #
+    #   never_intercept   the worker stands aside. No cache, no offline page, no fallback.
+    #   never_cache       the worker still answers, and can still show your offline page.
+    #                     It just never stores the response.
+    #
+    # So auth pages, admin, anything sensitive: `never_cache`. A probe the worker must
+    # never be able to answer from a cache: `never_intercept`.
+    attr_accessor :never_intercept
+
+    # What browsing stores. Strings are route patterns — "/sites/:id" matches that shape and
+    # nothing beneath it, "/assets/*" takes everything under it — and Regexps are tested
+    # against the path by JavaScript's RegExp, so write `^`/`$` rather than `\A`/`\z`.
+    #
+    # These are the pages worth keeping as somebody moves through the app. What one of them
+    # needs in order to render — its stylesheets, its scripts, its images — is stored with it
+    # whether or not those match anything here, because a page held without them is the
+    # offline equivalent of not holding it at all.
+    #
+    # Defaults to "/*", which is every path. An empty list stores nothing by browsing. It
+    # does not govern the precache manifest: listing a URL there is an explicit instruction.
+    attr_reader :cache_as_you_go
+
+    def cache_as_you_go=(patterns)
+      @cache_as_you_go = validate_patterns(patterns, :cache_as_you_go)
+    end
+
+    # Never stored, by any route in: not by browsing, not as a subresource of a page that
+    # references it, not by the precache manifest. The one veto.
+    attr_reader :never_cache
+
+    def never_cache=(patterns)
+      @never_cache = validate_patterns(patterns, :never_cache)
+    end
+
+    # Whether a page registers the worker at all — and so whether it caches or syncs anything.
+    # Evaluated in the view, so `request` and `current_user` are both in scope:
+    #
+    #   config.register_if = -> { hotwire_native_app? && current_user.present? }
+    attr_writer :register_if
+
+    # Default for the Offline support switch on the offline settings page. People can turn
+    # it off there, which deletes what is stored and stops anything new being saved. Unset
+    # on a device follows this; a choice they have already made is remembered.
+    attr_accessor :caching_enabled_by_default
+
+    # Who the cache belongs to, usually the signed-in user's id. When it changes between page
+    # loads the cache is dropped, which is what makes signing out and switching accounts safe:
+    # cached pages hold whatever the previous session could see.
+    attr_writer :cache_identity
+
+    # 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.
+    attr_reader :cache_origins
+
+    def cache_origins=(origins)
+      @cache_origins = Array(origins).map { |origin| validate_origin(origin) }
+    end
+
+    # URLs whose Range requests are cached piece by piece, keyed by the range — for a large
+    # immutable archive read a slice at a time, the slices you actually read are a rounding
+    # error next to the file. Same patterns as the lists above.
+    attr_reader :cache_ranges
+
+    def cache_ranges=(patterns)
+      @cache_ranges = validate_patterns(patterns, :cache_ranges) || Array(patterns)
+    end
+
+    # Large files somebody can choose to keep, each described well enough for the offline settings page
+    # to offer it without knowing what it is:
+    #
+    #   config.cache_archives = [
+    #     { url: "https://tiles.example.com/basemap.pmtiles", title: "Offline map",
+    #       description: "The whole coast, rather than only the places you have opened." }
+    #   ]
+    #
+    # A bare URL works too, with the filename as the title. Nothing downloads on its own:
+    # hundreds of megabytes over somebody's connection is their decision.
+    attr_reader :cache_archives
+
+    def cache_archives=(archives)
+      @cache_archives = Array(archives).map { |archive| normalize_archive(archive) }
+    end
+
+    # Just the URLs, for the worker — it downloads and serves; the words are the page's job.
+    def cache_archive_urls
+      cache_archives.map { |archive| archive[:url] }
+    end
+
+    # Keeping the cache current on its own. Grouped because these only mean anything together:
+    # a manifest with no interval is never 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) } }
+    #   end
+    def auto_sync
+      @auto_sync ||= AutoSync.new
+      yield(@auto_sync) if block_given?
+
+      @auto_sync
+    end
+
+    # WebKit has no Background Sync, Periodic Background Sync or Background Fetch, so nothing
+    # can wake a worker. What a page load can do is hand work to one, which then runs on
+    # without it — so syncing is triggered by an open page and paced, not scheduled.
+    class AutoSync
+      # Off unless asked for. Background fetching is a decision about somebody's data plan.
+      attr_accessor :enabled
+
+      # The pages to keep cached, evaluated in the controller so route helpers and the current
+      # user are both available.
+      attr_accessor :precache_urls
+
+      # How long to leave between syncs.
+      attr_accessor :interval
+
+      # Refetch a manifest page once its copy is older than this. nil fetches only what is
+      # missing, so pages already cached are never noticed to have changed.
+      attr_accessor :max_age
+
+      # Lanes sharing a queue: sequential would take a round trip per URL, and all at once
+      # would stall the app's own requests behind hundreds of connections.
+      attr_accessor :concurrency
+
+      def initialize
+        @enabled = false
+        @precache_urls = -> { [] }
+        @interval = 6 * 60 * 60
+        @max_age = 7 * 24 * 60 * 60
+        @concurrency = 4
+      end
+    end
+
+    def initialize
+      @cache_name = "coldwire"
+      @worker_scope = "/"
+      @probe_path = "/up"
+      @never_intercept = [ "/up" ]
+      @cache_as_you_go = [ "/*" ]
+      @never_cache = []
+      # Propshaft and Sprockets, Webpacker, Vite, and Active Storage's signed blob URLs —
+      # every one of them addressed by something that changes when the bytes do.
+      @mark_cached_pages = true
+      @offline_import = "@hotwired/turbo-rails"
+      @ignore_query_params = true
+      @register_if = -> { true }
+      @caching_enabled_by_default = true
+      @cache_identity = -> { nil }
+      @cache_origins = []
+      @cache_ranges = []
+      @cache_archives = []
+    end
+
+    # Evaluated in the view, so `request` and `current_user` are both in scope. A block that
+    # declares a parameter is handed the request as well, which keeps `->(request) { ... }`
+    # working for anyone who only cares about the headers.
+    def register?(view)
+      result = if @register_if.arity.zero?
+        view.instance_exec(&@register_if)
+      else
+        view.instance_exec(view.request, &@register_if)
+      end
+
+      result ? true : false
+    end
+
+    # `view` is the view context, so a host can write `-> { current_user&.id }`.
+    def cache_identity(view)
+      view.instance_exec(&@cache_identity).to_s
+    end
+
+    private
+
+    # Fail here rather than when the worker script is rendered, so a bad pattern surfaces at
+    # boot instead of as a 500 that quietly takes caching down with it.
+    def validate_patterns(patterns, setting)
+      Array(patterns).each do |pattern|
+        next validate_path_pattern(pattern, setting) unless pattern.is_a?(Regexp)
+
+        # `\A` and friends are reflex for a Ruby developer, and JavaScript reads them as
+        # identity escapes — `\A` quietly becomes a literal "A" and the rule never matches.
+        if pattern.source.match?(/(?<!\\)\\[AzZ]/)
+          raise ArgumentError,
+                "Coldwire evaluates #{setting} patterns with JavaScript's RegExp, which reads " \
+                "\\A, \\z and \\Z as literal letters. Use ^ and $ instead: #{pattern.inspect}"
+        end
+
+        unsupported = []
+        unsupported << "x (extended)" if pattern.options.anybits?(Regexp::EXTENDED)
+        unsupported << "m (multiline)" if pattern.options.anybits?(Regexp::MULTILINE)
+        next if unsupported.empty?
+
+        raise ArgumentError,
+              "Coldwire evaluates #{setting} patterns with JavaScript's RegExp, which has no " \
+              "equivalent for #{unsupported.join(' and ')}: #{pattern.inspect}"
+      end
+    end
+
+    # An origin and nothing more: no path, no trailing slash. Anything else silently fails to
+    # match a request's origin, which is the same quiet failure as a malformed path pattern.
+    def validate_origin(origin)
+      value = origin.to_s
+
+      begin
+        uri = URI.parse(value)
+      rescue URI::InvalidURIError
+        uri = nil
+      end
+
+      unless uri&.scheme && uri.host && uri.path.to_s.empty? && uri.query.nil?
+        raise ArgumentError,
+              "Coldwire cache_origins takes bare origins like " \
+              "\"https://tiles.example.com\": #{origin.inspect}"
+      end
+
+      value
+    end
+
+    # A Hash with a url, or a bare URL string. Title falls back to the filename, which is a
+    # poor title but a better one than a blank card.
+    def normalize_archive(archive)
+      archive = { url: archive } unless archive.is_a?(Hash)
+      archive = archive.transform_keys(&:to_sym)
+      url = archive[:url].to_s
+
+      begin
+        uri = URI.parse(url)
+      rescue URI::InvalidURIError
+        uri = nil
+      end
+
+      unless uri&.scheme && uri.host
+        raise ArgumentError,
+              "Coldwire cache_archives needs an absolute url for each entry: #{archive.inspect}"
+      end
+
+      {
+        url: url,
+        title: archive[:title].presence || File.basename(uri.path.to_s).presence || url,
+        description: archive[:description].presence
+      }
+    end
+
+    # Path patterns are route-shaped: literal segments, ":name" for exactly one segment, and a
+    # trailing "*" for the rest. Checked here because every mistake in this shape fails the
+    # same silent way — the rule simply never matches, and you find out when something you
+    # expected to be there offline is not.
+    def validate_path_pattern(pattern, setting)
+      path = pattern.to_s
+
+      unless path.start_with?("/")
+        raise ArgumentError,
+              "Coldwire #{setting} paths are matched from the root, so they start with a " \
+              "slash: #{pattern.inspect}"
+      end
+
+      parts = path.split("/").reject(&:empty?)
+
+      parts.each_with_index do |part, index|
+        next if part == "*" && index == parts.length - 1
+
+        if part == "*"
+          raise ArgumentError,
+                "Coldwire #{setting} \"*\" matches everything remaining, so it can only be " \
+                "the last segment: #{pattern.inspect}"
+        end
+
+        next if part.match?(/\A:[A-Za-z_]\w*\z/)
+        next if part.match?(/\A[^:*]+\z/)
+
+        raise ArgumentError,
+              "Coldwire #{setting} segment #{part.inspect} is not a literal, a \":name\", or " \
+              "a trailing \"*\": #{pattern.inspect}"
+      end
+    end
+  end
+end

data/lib/coldwire/debug.css

@@ -0,0 +1,197 @@
+.coldwire { --coldwire-caret: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%236b7280' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m19.5 8.25-7.5 7.5-7.5-7.5'/%3E%3C/svg%3E");
+  max-width: 42rem; margin: 0 auto; padding: 0.75rem;
+  font-family: system-ui, -apple-system, sans-serif; color: #1f2937; }
+.coldwire h1 { font-size: 1.5rem; margin: 0 0 1rem; }
+.coldwire-card { border: 1px solid #e5e7eb; border-radius: 1rem; background: #fff;
+  padding: 1rem; margin-bottom: 0.75rem; }
+.coldwire-card h2 { font-size: 0.75rem; font-weight: 600; letter-spacing: 0.04em;
+  text-transform: uppercase; color: #9ca3af; margin: 0 0 0.75rem; }
+
+/* Status: the one thing worth reading at a glance, so it gets the largest type on the
+   page and the colour. */
+.coldwire-headline { display: flex; align-items: center; gap: 0.6rem;
+  font-size: 1.125rem; font-weight: 600; }
+.coldwire-light { flex-shrink: 0; width: 0.6rem; height: 0.6rem; border-radius: 9999px;
+  background: #9ca3af; box-shadow: 0 0 0 3px rgba(156, 163, 175, 0.18); }
+.coldwire-light[data-state="online"] { background: #16a34a; box-shadow: 0 0 0 3px rgba(22, 163, 74, 0.18); }
+.coldwire-light[data-state="forced"] { background: #f59e0b; box-shadow: 0 0 0 3px rgba(245, 158, 11, 0.20); }
+.coldwire-light[data-state="offline"] { background: #dc2626; box-shadow: 0 0 0 3px rgba(220, 38, 38, 0.18); }
+/* Grey, not red: switched off is not a fault. */
+.coldwire-light[data-state="disabled"] { background: #9ca3af; box-shadow: 0 0 0 3px rgba(156, 163, 175, 0.18); }
+.coldwire-facts code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.8125rem; }
+.coldwire-facts { margin: 0.5rem 0 0; font-size: 0.875rem; color: #6b7280; line-height: 1.5; }
+
+.coldwire-head { display: flex; align-items: flex-start; justify-content: space-between; gap: 0.75rem; }
+/* Offline support lives in the status card. The rule only applies while the Online/offline
+   row is showing — with support off that row is hidden and the switch is the whole card. */
+.coldwire-head:not([hidden]) + .coldwire-setting { margin-top: 0.9rem; padding-top: 0.9rem;
+  border-top: 1px solid #e5e7eb; }
+.coldwire-card hr { border: 0; border-top: 1px solid #e5e7eb; margin: 0.9rem 0; }
+.coldwire-actions { display: flex; flex-wrap: wrap; gap: 0.5rem; }
+.coldwire-actions--spaced { margin-top: 0.75rem; }
+
+.coldwire-button { display: inline-flex; align-items: center; justify-content: center; gap: 0.5rem;
+  cursor: pointer; border: 1px solid #d1d5db; border-radius: 0.5rem; background: #fff; color: #111827;
+  padding: 0.375rem 0.75rem; font-size: 0.875rem; font-weight: 600; line-height: 1.5rem; white-space: nowrap; }
+.coldwire-button[disabled] { opacity: 0.6; cursor: default; }
+/* `hidden` is a UA rule, and any author `display` beats it — so the Delete button, which
+   sets its own, ignored the attribute and showed on an archive nobody had downloaded.
+   Stated once for the whole page rather than per component that grows a display. */
+.coldwire [hidden] { display: none !important; }
+.coldwire-button--danger { color: #b91c1c; border-color: #fecaca; }
+.coldwire-icon-button { width: 2.25rem; height: 2.25rem; padding: 0; flex-shrink: 0; }
+/* Heroicons outline, which are drawn for 1.5. Set here rather than on each svg: CSS beats
+   presentation attributes, so a value here silently wins anyway. */
+.coldwire-button svg { width: 1rem; height: 1rem; flex-shrink: 0; fill: none;
+  stroke: currentColor; stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
+.coldwire-icon-button svg { width: 1.2rem; height: 1.2rem; fill: none; stroke: currentColor;
+  stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
+/* Spins while a refresh is in flight — without it the button re-reads values that usually
+   look identical and seems to do nothing. */
+.coldwire-icon-button[data-busy] svg { animation: coldwire-spin 0.7s linear infinite; }
+
+.coldwire-spinner { width: 1rem; height: 1rem; flex-shrink: 0; border-radius: 9999px;
+  border: 2px solid #d1d5db; border-top-color: #374151; animation: coldwire-spin 0.7s linear infinite; }
+@keyframes coldwire-spin { to { transform: rotate(360deg); } }
+
+/* A real checkbox underneath, so it keeps its keyboard behaviour and its label. */
+.coldwire-switch { position: relative; display: inline-flex; flex-shrink: 0;
+  width: 2.6rem; height: 1.55rem; }
+.coldwire-switch input { position: absolute; inset: 0; width: 100%; height: 100%;
+  margin: 0; opacity: 0; cursor: pointer; }
+.coldwire-switch span { position: absolute; inset: 0; pointer-events: none; border-radius: 9999px;
+  background: #d1d5db; transition: background-color 160ms ease; }
+.coldwire-switch span::after { content: ""; position: absolute; top: 0.2rem; left: 0.2rem;
+  width: 1.15rem; height: 1.15rem; border-radius: 9999px; background: #fff;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.3); transition: transform 160ms ease; }
+/* Amber, matching the forced-offline light — the two say the same thing. */
+.coldwire-switch input:checked + span { background: #f59e0b; }
+/* Except where being on is the ordinary state rather than a deliberate degradation; green,
+   matching the online light. Same switch otherwise. */
+.coldwire-switch--on input:checked + span { background: #16a34a; }
+.coldwire-switch input:checked + span::after { transform: translateX(1.05rem); }
+.coldwire-switch input:focus-visible + span { outline: 2px solid #2563eb; outline-offset: 2px; }
+
+.coldwire-setting { display: flex; align-items: flex-start; gap: 0.85rem; cursor: pointer; }
+/* A setting that leads a card, with facts under it rather than standing alone. */
+.coldwire-setting + .coldwire-facts { margin-top: 0.9rem; }
+.coldwire-setting-title { display: block; font-weight: 600; }
+.coldwire-setting-note { display: block; margin-top: 0.15rem; font-size: 0.875rem; color: #6b7280; }
+
+.coldwire-track { height: 0.375rem; width: 100%; overflow: hidden; border-radius: 9999px; background: #e5e7eb; }
+.coldwire-bar { height: 100%; width: 100%; border-radius: 9999px; background: #374151; transition: width 200ms; }
+.coldwire-pulse { animation: coldwire-fade 1.4s ease-in-out infinite; }
+@keyframes coldwire-fade { 0%, 100% { opacity: 1; } 50% { opacity: 0.4; } }
+.coldwire-progress-label { margin-top: 0.375rem; font-size: 0.75rem; color: #6b7280; }
+
+/* Search and sort sit above the list rather than beside the heading: on a phone the two
+   controls need the full width between them, and the heading is only a label. */
+.coldwire-filters { display: flex; gap: 0.5rem; margin-bottom: 0.75rem; }
+.coldwire-input, .coldwire-select { border: 1px solid #d1d5db; border-radius: 0.5rem;
+  background-color: #fff; color: #111827; padding: 0.375rem 0.5rem; font-size: 0.875rem;
+  line-height: 1.5rem; font-family: inherit; }
+/* The search takes the slack; the select asks only for its own content. 0 min-width lets it
+   shrink inside the flex row instead of forcing the card wider than the screen. */
+.coldwire-input { flex: 1 1 auto; min-width: 0; }
+
+/* Safari stops drawing the native arrow once a select is given a background and a border,
+   so opt out of the native look entirely and draw one. Heroicons chevron-down, to match the
+   other icons on the page. */
+.coldwire-select { flex: 0 0 auto; cursor: pointer;
+  appearance: none; -webkit-appearance: none;
+  padding-right: 1.9rem;
+  background-image: var(--coldwire-caret);
+  background-repeat: no-repeat;
+  background-position: right 0.55rem center;
+  background-size: 0.85rem; }
+.coldwire-input:focus-visible, .coldwire-select:focus-visible { outline: 2px solid #6b7280;
+  outline-offset: 1px; }
+
+/* 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; }
+/* Under the filter, because it answers what the filter asks. */
+.coldwire-count { margin: 0 0 0.6rem; }
+
+.coldwire-entries { list-style: none; margin: 0; padding: 0; max-height: 32rem; overflow-y: auto; }
+.coldwire-entries li + li { margin-top: 0.5rem; }
+.coldwire-entry { display: flex; align-items: center; gap: 0.5rem; min-width: 0; }
+/* A button, not a div: the whole point is that it is tappable, and this way it is reachable
+   from a keyboard and announced as a control without any of that being reinvented. It takes
+   the slack and is allowed to shrink, so a long path ellipsises rather than pushing the
+   trash off the row. */
+.coldwire-entry-text { flex: 1 1 auto; min-width: 0; display: block; text-align: left;
+  padding: 0; border: 0; background: none; font: inherit; color: inherit; cursor: pointer; }
+.coldwire-entry-text:focus-visible { outline: 2px solid #6b7280; outline-offset: 2px;
+  border-radius: 0.25rem; }
+.coldwire-entry-forget { flex: 0 0 auto; display: inline-flex; align-items: center;
+  justify-content: center; width: 2rem; height: 2rem; padding: 0; cursor: pointer;
+  border: 0; border-radius: 0.5rem; background: none; color: #9ca3af; }
+.coldwire-entry-forget svg { width: 1rem; height: 1rem; fill: none; stroke: currentColor;
+  stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
+/* Quiet until you go for it: one of these sits on every row, and a column of red would
+   read as a warning rather than a control. */
+.coldwire-entry-forget:hover, .coldwire-entry-forget:focus-visible { color: #b91c1c;
+  background: #fef2f2; }
+.coldwire-entry-forget[disabled] { opacity: 0.5; cursor: default; }
+.coldwire-entry-url { overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.75rem; color: #1f2937; }
+.coldwire-entry-meta { margin-top: 0.125rem; font-size: 0.75rem; color: #6b7280; }
+.coldwire-empty { color: #9ca3af; font-size: 0.875rem; }
+/* Centred here rather than left to the browser. A modal <dialog> is centred by the UA's
+   `margin: auto`, and a host app's CSS reset routinely zeroes margin on everything —
+   Tailwind's preflight does — which drops the dialog into the top left corner. A definite
+   width and height are what let `margin: auto` centre on both axes. */
+.coldwire-dialog { position: fixed; inset: 0; margin: auto;
+  width: min(28rem, calc(100vw - 2rem)); height: fit-content;
+  max-height: calc(100vh - 2rem); overflow: auto;
+  border: 0; border-radius: 1rem; padding: 1rem; background: #fff; color: #1f2937;
+  font-family: inherit; }
+.coldwire-dialog::backdrop { background: rgba(17, 24, 39, 0.45); }
+.coldwire-dialog h2 { font-size: 0.75rem; font-weight: 600; letter-spacing: 0.04em;
+  text-transform: uppercase; color: #9ca3af; margin: 0 0 0.75rem; }
+/* The reason this exists: a URL too long for its row has to wrap here, anywhere it must,
+   rather than ellipsising again or pushing the dialog wider than the screen. */
+.coldwire-dialog-url { margin: 0; font-size: 0.875rem; line-height: 1.5;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace; overflow-wrap: anywhere; }
+
+/* Quiet on purpose: a list of every cached URL is a debug surface, not a setting.
+   No card, no colour, just a disclosure at the bottom for whoever needs it. */
+.coldwire-inspect { margin: 1.25rem 0 0; padding-top: 0.85rem; border-top: 1px solid #e5e7eb; }
+.coldwire-inspect summary { cursor: pointer; list-style: none; }
+.coldwire-inspect summary::-webkit-details-marker { display: none; }
+.coldwire-inspect-label { display: flex; align-items: center; gap: 0.35rem;
+  font-size: 0.75rem; font-weight: 600; letter-spacing: 0.04em;
+  text-transform: uppercase; color: #9ca3af; }
+.coldwire-inspect-label::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-inspect[open] .coldwire-inspect-label::after { transform: rotate(180deg); }
+.coldwire-inspect-hint { display: block; margin-top: 0.15rem;
+  font-size: 0.8125rem; color: #9ca3af; line-height: 1.4; }
+.coldwire-inspect-body { margin-top: 0.85rem; }
+.coldwire-inspect summary:focus-visible { outline: 2px solid #6b7280; outline-offset: 2px;
+  border-radius: 0.25rem; }
+
+/* A phone gives up a lot of its width to two sets of gutters — the page's and each card's.
+   Tighten both, and let the cards run closer to the edges where the room is worth more
+   than the margin. */
+@media (max-width: 30rem) {
+  .coldwire { padding: 0.5rem 0.25rem; }
+  .coldwire h1 { font-size: 1.375rem; margin-bottom: 0.75rem; }
+  .coldwire-card { padding: 0.75rem; border-radius: 0.75rem; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .coldwire-icon-button[data-busy] svg,
+  .coldwire-spinner,
+  .coldwire-pulse { animation: none; }
+  .coldwire-switch span,
+  .coldwire-switch span::after,
+  .coldwire-inspect-label::after { transition: none; }
+}

data/lib/coldwire/engine.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Coldwire
+  class Engine < ::Rails::Engine
+    isolate_namespace Coldwire
+
+    # Let host apps `pin "coldwire", to: "coldwire/cache_controller.js"` without knowing
+    # where the gem lives.
+    initializer "coldwire.importmap", before: "importmap" do |app|
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join("config/importmap.rb")
+        app.config.importmap.cache_sweepers << root.join("app/assets/javascripts")
+      end
+    end
+
+    initializer "coldwire.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/assets/javascripts")
+      end
+    end
+
+    # Ahead of everything, so whatever asks whether this is the native app — the layout, the
+    # helpers, `register_if` — sees the client the request actually came from.
+    initializer "coldwire.client_user_agent" do |app|
+      app.config.middleware.insert_before 0, Coldwire::ClientUserAgent
+    end
+
+    initializer "coldwire.helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        helper Coldwire::ServiceWorkerHelper
+      end
+    end
+  end
+end

data/lib/coldwire/source.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Coldwire
+  # JavaScript and CSS that ship as files and are assembled when they are rendered, so none of
+  # it has to be written inside a Ruby string.
+  module Source
+    ROOT = Pathname.new(__dir__)
+
+    # The worker is served as one script but written as several. Concatenated rather than
+    # imported, so the browser still fetches one file and function declarations hoist across
+    # the whole of it.
+    WORKER = %w[rules serve ranges archives inspect sync events].freeze
+
+    class << self
+      def worker
+        assemble(WORKER.map { |part| read("worker/#{part}.js") })
+      end
+
+      # The page-side script: the values it cannot know, then whichever parts this page needs.
+      #
+      # A property rather than a const. Turbo copies head scripts it does not recognise, and a
+      # per-request CSP nonce makes this one look new on every visit — a second `const COLDWIRE`
+      # in the same document is a SyntaxError, and the whole script dies with it.
+      def client(config, parts)
+        assemble([ "window.COLDWIRE = #{config.to_json};" ] + parts.map { |part| read("client/#{part}.js") })
+      end
+
+      def debug_css
+        read("debug.css")
+      end
+
+      private
+
+      # Spelled out rather than left to the host's locale: these files have em dashes in them,
+      # and a process running under a C locale would otherwise read them as US-ASCII and raise
+      # on the first one.
+      def read(path)
+        ROOT.join(path).read(encoding: "UTF-8")
+      end
+
+      # Each fragment is self-terminated. `})()` followed by `(function` reads as one call
+      # expression rather than two statements, and ASI does not save you.
+      def assemble(parts)
+        parts.join("\n")
+      end
+    end
+  end
+end

data/lib/coldwire/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Coldwire
+  # Read from the VERSION file at the root, which is the single place the number is written:
+  # the gemspec takes it from here rather than from a second copy, and a release only has to
+  # touch one line.
+  #
+  # `.freeze` because the frozen_string_literal pragma above covers literals in this file, not
+  # a string that arrives from IO.
+  VERSION = File.read(File.expand_path("../../VERSION", __dir__)).strip.freeze
+end