Offline UX and fallbacks¶

"use strict";

const VERSION = "v7"; // bump when the fallback assets change
const FALLBACK_CACHE = `app-fallbacks-${VERSION}`;
const PAGES_CACHE = "app-pages-v1";
const API_CACHE = "app-api-v1";
const IMAGES_CACHE = "app-images-v1";

const OFFLINE_URL = "/offline.html";
const FALLBACK_IMAGE_URL = "/img/offline-placeholder.svg";
const HEALTH_PATH = "/__health";

const NAVIGATION_TIMEOUT_MS = 3500;
const API_TIMEOUT_MS = 5000;
const MAX_PAGES = 50;
const MAX_IMAGES = 120;

self.addEventListener("install", (event) => {
  event.waitUntil(
    (async () => {
      const cache = await caches.open(FALLBACK_CACHE);
      // "reload": never capture a stale copy of the fallback from the HTTP cache.
      await cache.addAll([OFFLINE_URL, FALLBACK_IMAGE_URL].map((url) => new Request(url, { cache: "reload" })));
    })()
  );
});

self.addEventListener("activate", (event) => {
  event.waitUntil(
    (async () => {
      if (self.registration.navigationPreload) {
        await self.registration.navigationPreload.enable();
      }
      const names = await caches.keys();
      await Promise.all(
        names
          .filter((name) => name.startsWith("app-fallbacks-") && name !== FALLBACK_CACHE)
          .map((name) => caches.delete(name))
      );
    })()
  );
});

self.addEventListener("fetch", (event) => {
  const { request } = event;
  const url = new URL(request.url);

  // Connectivity probes must reach the network: never answer them from a cache.
  if (url.pathname === HEALTH_PATH) return;
  // Writes are handled by the page's outbox, not replayed here.
  if (request.method !== "GET") return;

  if (request.mode === "navigate") {
    event.respondWith(handleNavigation(event));
  } else if (url.origin === self.location.origin && url.pathname.startsWith("/api/")) {
    event.respondWith(handleApi(event));
  } else if (request.destination === "image") {
    event.respondWith(handleImage(event));
  }
});

// ---- Navigations: network (with preload) -> cached page -> offline page ----

async function handleNavigation(event) {
  const network = (async () => (await event.preloadResponse) ?? fetch(event.request))();
  try {
    return await networkFirst(event, network, PAGES_CACHE, NAVIGATION_TIMEOUT_MS, MAX_PAGES);
  } catch {
    const fallbacks = await caches.open(FALLBACK_CACHE);
    return (await fallbacks.match(OFFLINE_URL)) ?? Response.error();
  }
}

// ---- API reads: network -> cached copy (marked stale) -> synthetic 503 ------

async function handleApi(event) {
  try {
    return await networkFirst(event, fetch(event.request), API_CACHE, API_TIMEOUT_MS);
  } catch {
    return new Response(JSON.stringify({ error: "offline", message: "No network and no cached copy." }), {
      status: 503,
      statusText: "Service Unavailable",
      headers: { "Content-Type": "application/json", "SW-Cache-Status": "offline-miss" },
    });
  }
}

// ---- Images: cache -> network -> placeholder -------------------------------

async function handleImage(event) {
  const cache = await caches.open(IMAGES_CACHE);
  const cached = await cache.match(event.request);
  if (cached) return cached;
  try {
    const response = await fetch(event.request);
    // Opaque cross-origin images (status 0) are cacheable, but they cost quota padding.
    if (response.ok || response.type === "opaque") {
      event.waitUntil(cache.put(event.request, response.clone()).then(() => trim(IMAGES_CACHE, MAX_IMAGES)));
    }
    return response;
  } catch {
    const fallbacks = await caches.open(FALLBACK_CACHE);
    return (await fallbacks.match(FALLBACK_IMAGE_URL)) ?? Response.error();
  }
}

// ---- Shared: network-first with a timeout that still refreshes the cache ----

/**
 * Race the network against a timer. If the timer wins and a cached copy exists,
 * answer from cache but let the network request finish and update the cache.
 * Rejects only when there is neither a network response nor a cached copy.
 */
async function networkFirst(event, networkPromise, cacheName, timeoutMs, maxEntries) {
  const { request } = event;
  const network = networkPromise.then(async (response) => {
    if (response.ok && response.type === "basic") {
      const cache = await caches.open(cacheName);
      await cache.put(request, await stamp(response.clone()));
      if (maxEntries) await trim(cacheName, maxEntries);
    }
    return response;
  });
  // Keep the worker alive until the network attempt and cache write settle.
  event.waitUntil(network.catch(() => undefined));

  let timer;
  const timeout = new Promise((resolve) => {
    timer = setTimeout(resolve, timeoutMs, "timeout");
  });
  try {
    const winner = await Promise.race([network, timeout]);
    if (winner !== "timeout") return winner;
    const cached = await caches.match(request, { cacheName });
    if (cached) return markStale(cached, "stale-timeout");
    return await network; // nothing cached: keep waiting for the slow network
  } catch {
    const cached = await caches.match(request, { cacheName });
    if (cached) return markStale(cached, "stale-offline");
    throw new Error("network and cache both missed");
  } finally {
    clearTimeout(timer);
  }
}

/** Record when the response was fetched, for "last updated" labels in the UI. */
async function stamp(response) {
  const headers = new Headers(response.headers);
  headers.set("SW-Fetched-At", new Date().toISOString());
  return new Response(await response.blob(), {
    status: response.status,
    statusText: response.statusText,
    headers,
  });
}

/** Tell the page this response came from the cache, and why. */
function markStale(response, status) {
  const headers = new Headers(response.headers);
  headers.set("SW-Cache-Status", status);
  return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
}

/** Simple FIFO cap: Cache.keys() returns entries in insertion order. */
async function trim(cacheName, maxEntries) {
  const cache = await caches.open(cacheName);
  const keys = await cache.keys();
  await Promise.all(keys.slice(0, Math.max(0, keys.length - maxEntries)).map((key) => cache.delete(key)));
}

const connectivityChannel = new BroadcastChannel("connectivity");

function reportOutcome(outcome) {
  // Fire-and-forget: every open page with a ConnectivityMonitor receives it.
  connectivityChannel.postMessage(outcome); // { ok, timedOut, durationMs }
}

// In networkFirst(): measure around the network promise.
//   const started = Date.now();
//   network.then(() => reportOutcome({ ok: true, durationMs: Date.now() - started }),
//                () => reportOutcome({ ok: false }));
//   ...and when the timer wins: reportOutcome({ ok: false, timedOut: true });

const HEALTH_URL = "/__health"; // must return 204 + Cache-Control: no-store; the SW must not answer it
const HEARTBEAT_TIMEOUT_MS = 4000;
const SLOW_MS = 2500; // slower than this counts as degraded
const FAILURES_BEFORE_OFFLINE = 2; // hysteresis against flapping
const MIN_BACKOFF_MS = 2000;
const MAX_BACKOFF_MS = 60000;

/** AbortSignal.timeout() where available; manual fallback elsewhere. */
export function timeoutSignal(ms) {
  if (typeof AbortSignal.timeout === "function") return AbortSignal.timeout(ms);
  const controller = new AbortController();
  setTimeout(() => controller.abort(new DOMException("Timed out", "TimeoutError")), ms);
  return controller.signal;
}

/** Chrome 103-123 aborted AbortSignal.timeout() with "AbortError"; newer engines use "TimeoutError". */
export const isTimeout = (error) => error?.name === "TimeoutError" || error?.name === "AbortError";

export class ConnectivityMonitor extends EventTarget {
  #state = navigator.onLine ? "online" : "offline";
  #since = Date.now();
  #failures = 0;
  #backoff = MIN_BACKOFF_MS;
  #timer = null;
  #inFlight = null;

  constructor() {
    super();
    addEventListener("offline", () => {
      this.#set("offline", "offline-event");
      this.#ensurePolling();
    });
    addEventListener("online", () => this.check("online-event")); // online = "go and check"
    document.addEventListener("visibilitychange", () => {
      if (document.visibilityState === "hidden") {
        this.#clearTimer(); // no polling in background tabs
      } else if (this.#state !== "online") {
        this.check("visible");
      }
    });
    navigator.connection?.addEventListener?.("change", () => this.check("connection-change"));
    if ("BroadcastChannel" in self) {
      // The service worker posts { ok, timedOut, durationMs } for requests it made.
      new BroadcastChannel("connectivity").addEventListener("message", ({ data }) => this.report(data));
    }
    this.#ensurePolling();
  }

  get state() {
    return this.#state;
  }

  get since() {
    return this.#since;
  }

  /** Passive signal: call with the outcome of every real request. */
  report({ ok, timedOut = false, durationMs = 0 }) {
    if (ok) {
      this.#failures = 0;
      this.#set(durationMs > SLOW_MS ? "degraded" : "online", "request");
      return;
    }
    this.#failures += 1;
    if (timedOut && this.#state === "online") this.#set("degraded", "request-timeout");
    if (this.#failures >= FAILURES_BEFORE_OFFLINE) this.check("request-failures");
    this.#ensurePolling();
  }

  /** Active probe. Concurrent callers share one in-flight request. */
  check(reason = "manual") {
    this.#inFlight ??= this.#probe(reason).finally(() => {
      this.#inFlight = null;
    });
    return this.#inFlight;
  }

  async #probe(reason) {
    if (!navigator.onLine) {
      this.#set("offline", reason); // false is authoritative
      return this.#state;
    }
    const started = performance.now();
    try {
      // The query string defeats misbehaving intermediary caches; no-store handles the HTTP cache.
      const response = await fetch(`${HEALTH_URL}?t=${Date.now()}`, {
        method: "HEAD",
        cache: "no-store",
        credentials: "omit",
        signal: timeoutSignal(HEARTBEAT_TIMEOUT_MS),
      });
      // Captive portals answer with 200 HTML or redirects: only our own 204 proves reachability.
      if (response.status !== 204) throw new Error(`health check returned ${response.status}`);
      this.#failures = 0;
      const slow = performance.now() - started > SLOW_MS || this.#isSlowNetworkHint();
      this.#set(slow ? "degraded" : "online", reason);
    } catch (error) {
      this.#failures += 1;
      const stillHopeful = isTimeout(error) && this.#failures < FAILURES_BEFORE_OFFLINE;
      this.#set(stillHopeful ? "degraded" : "offline", reason);
    }
    this.#ensurePolling();
    return this.#state;
  }

  #isSlowNetworkHint() {
    const type = navigator.connection?.effectiveType; // Chromium only
    return type === "slow-2g" || type === "2g";
  }

  #set(state, reason) {
    if (state === "online") {
      this.#backoff = MIN_BACKOFF_MS;
      this.#clearTimer(); // healthy: real requests are the heartbeat
    }
    if (state === this.#state) return;
    const previous = this.#state;
    this.#state = state;
    this.#since = Date.now();
    this.dispatchEvent(new CustomEvent("change", { detail: { state, previous, reason, since: this.#since } }));
  }

  /** Poll with exponential backoff + jitter, only while unhealthy and visible. */
  #ensurePolling() {
    if (this.#state === "online" || this.#timer !== null || document.visibilityState === "hidden") return;
    const delay = this.#backoff + Math.random() * 0.3 * this.#backoff;
    this.#backoff = Math.min(this.#backoff * 2, MAX_BACKOFF_MS);
    this.#timer = setTimeout(() => {
      this.#timer = null;
      this.check("poll");
    }, delay);
  }

  #clearTimer() {
    clearTimeout(this.#timer);
    this.#timer = null;
  }
}

export const connectivity = new ConnectivityMonitor();

import { connectivity, isTimeout, timeoutSignal } from "./connectivity.js";

/**
 * fetch() with a timeout, optional caller cancellation, and connectivity reporting.
 * @param {RequestInfo} input
 * @param {RequestInit & {timeoutMs?: number}} [options]
 */
export async function request(input, { timeoutMs = 8000, signal, ...init } = {}) {
  const timeout = timeoutSignal(timeoutMs);
  // AbortSignal.any(): Chrome 116, Firefox 124, Safari 17.4. Without it, prefer the caller's signal.
  const combined = signal ? (AbortSignal.any ? AbortSignal.any([signal, timeout]) : signal) : timeout;
  const started = performance.now();
  try {
    const response = await fetch(input, { ...init, signal: combined });
    const cacheStatus = response.headers.get("SW-Cache-Status"); // set by our service worker
    connectivity.report({
      ok: cacheStatus === null,
      timedOut: cacheStatus === "stale-timeout",
      durationMs: performance.now() - started,
    });
    return response;
  } catch (error) {
    if (signal?.aborted) throw error; // the caller cancelled: not a connectivity signal
    connectivity.report({ ok: false, timedOut: isTimeout(error) });
    throw error;
  }
}

import { connectivity } from "./connectivity.js";

const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;

const MESSAGES = {
  offline: (pending) =>
    pending > 0
      ? `You're offline. ${plural(pending, "change")} will be sent when you reconnect.`
      : "You're offline. You can keep using content saved on this device.",
  degraded: () => "Your connection is slow. Some content may be out of date.",
  restored: (pending) => (pending > 0 ? `Back online. Sending ${plural(pending, "change")}…` : "You're back online."),
};

const template = document.createElement("template");
template.innerHTML = `
  <style>
    :host { position: fixed; inset-inline: 0; inset-block-end: 0; z-index: 1000; pointer-events: none;
            padding: 0 12px max(12px, env(safe-area-inset-bottom)); }
    .banner { pointer-events: auto; display: flex; gap: 12px; align-items: center; max-width: 40rem;
              margin: 0 auto; padding: 10px 14px; border-radius: 10px;
              font: 500 0.95rem/1.4 system-ui, sans-serif;
              background: var(--offline-banner-bg, #2b2b30); color: var(--offline-banner-fg, #fff);
              box-shadow: 0 4px 16px rgb(0 0 0 / 0.25);
              transition: transform .25s ease, opacity .25s ease, visibility 0s; }
    .banner[data-state="degraded"] { background: var(--offline-banner-warn-bg, #6b4e00); }
    .banner[data-state="restored"] { background: var(--offline-banner-ok-bg, #1e5b33); }
    .banner.hidden { transform: translateY(120%); opacity: 0; visibility: hidden;
                     transition: transform .25s ease, opacity .25s ease, visibility 0s linear .25s; }
    .message { flex: 1; margin: 0; }
    button { font: inherit; color: inherit; background: transparent; border: 1px solid currentColor;
             border-radius: 6px; padding: 4px 10px; cursor: pointer; }
    button:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }
    .sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%);
               white-space: nowrap; }
    @media (prefers-reduced-motion: reduce) { .banner, .banner.hidden { transition: none; } }
  </style>
  <div class="sr-only" role="status" aria-live="polite" aria-atomic="true"></div>
  <div class="banner hidden" part="banner">
    <p class="message" aria-hidden="true"></p>
    <button type="button" class="action"></button>
  </div>`;

class OfflineBanner extends HTMLElement {
  #shadow;
  #pending = 0;
  #shown = null; // "offline" | "degraded" | "restored" | null
  #dismissed = false;
  #hideTimer = 0;
  #channel = "BroadcastChannel" in self ? new BroadcastChannel("outbox") : null;

  connectedCallback() {
    if (!this.#shadow) {
      this.#shadow = this.attachShadow({ mode: "open" });
      this.#shadow.append(template.content.cloneNode(true));
      this.#shadow.querySelector(".action").addEventListener("click", () => this.#onAction());
    }
    connectivity.addEventListener("change", this.#onConnectivity);
    this.#channel?.addEventListener("message", this.#onOutbox);
    // Outbox is optional: the global comes from outbox-core.js when the app uses offline forms.
    self.Outbox?.list()
      .then((items) => this.#onOutbox({ data: { pending: items.filter((i) => i.state === "pending").length } }))
      .catch(() => {});
    if (connectivity.state !== "online") this.#show(connectivity.state);
  }

  disconnectedCallback() {
    connectivity.removeEventListener("change", this.#onConnectivity);
    this.#channel?.removeEventListener("message", this.#onOutbox);
    clearTimeout(this.#hideTimer);
  }

  #onConnectivity = ({ detail: { state, previous } }) => {
    if (state === "online") {
      // "Back online" only after a real outage; recovering from "degraded" just clears the notice.
      if (previous === "offline") this.#show("restored");
      else if (this.#shown) this.#hide();
      return;
    }
    if (state === "degraded" && this.#dismissed) return;
    this.#dismissed = false;
    this.#show(state);
  };

  #onOutbox = ({ data }) => {
    if (typeof data?.pending !== "number") return;
    this.#pending = data.pending;
    if (this.#shown) this.#render(this.#shown, { announce: false }); // update the count silently
  };

  #onAction() {
    if (this.#shown === "offline") {
      connectivity.check("user-retry");
    } else {
      this.#dismissed = this.#shown === "degraded";
      this.#hide();
    }
  }

  #show(kind) {
    clearTimeout(this.#hideTimer);
    this.#render(kind, { announce: kind !== this.#shown });
    if (kind === "restored") this.#hideTimer = setTimeout(() => this.#hide(), 4000);
  }

  #render(kind, { announce }) {
    const text = MESSAGES[kind](this.#pending);
    const banner = this.#shadow.querySelector(".banner");
    const action = this.#shadow.querySelector(".action");
    this.#shown = kind;
    banner.dataset.state = kind;
    banner.classList.remove("hidden");
    this.#shadow.querySelector(".message").textContent = text;
    action.textContent = kind === "offline" ? "Retry" : "Dismiss";
    action.hidden = kind === "restored";
    if (announce) this.#shadow.querySelector("[role=status]").textContent = text;
  }

  #hide() {
    clearTimeout(this.#hideTimer);
    this.#shown = null;
    this.#shadow.querySelector(".banner").classList.add("hidden");
  }
}

customElements.define("offline-banner", OfflineBanner);

import { connectivity } from "./connectivity.js";

/**
 * Marks a control as unavailable while offline, without removing it from the tab order.
 * @param {HTMLButtonElement} button
 * @param {HTMLElement} hint An element with an id, referenced by aria-describedby.
 */
export function onlineOnly(button, hint) {
  button.setAttribute("aria-describedby", hint.id);
  const update = () => {
    const offline = connectivity.state === "offline";
    button.setAttribute("aria-disabled", String(offline));
    hint.hidden = !offline;
  };
  // Capture phase: runs before the button's own click handlers.
  button.addEventListener(
    "click",
    (event) => {
      if (button.getAttribute("aria-disabled") !== "true") return;
      event.preventDefault();
      event.stopImmediatePropagation(); // don't run the real action
      hint.hidden = false;
      connectivity.check("user-action"); // maybe we're back already
    },
    { capture: true }
  );
  connectivity.addEventListener("change", update);
  update();
}

const rtf = new Intl.RelativeTimeFormat(undefined, { numeric: "auto" });
const UNITS = [
  ["year", 31_536_000],
  ["month", 2_592_000],
  ["week", 604_800],
  ["day", 86_400],
  ["hour", 3_600],
  ["minute", 60],
];

/** "now", "5 minutes ago", "yesterday", "3 weeks ago" in the user's locale. */
export function formatAge(date, now = Date.now()) {
  const seconds = Math.round((date.getTime() - now) / 1000); // negative = in the past
  if (Math.abs(seconds) < 45) return rtf.format(0, "second"); // "now"
  for (const [unit, size] of UNITS) {
    if (Math.abs(seconds) >= size) return rtf.format(Math.round(seconds / size), unit);
  }
  return rtf.format(Math.round(seconds / 60), "minute"); // 45-59 s: "1 minute ago"
}

/** When was this response fetched from the network? */
export function fetchedAt(response) {
  const value = response.headers.get("SW-Fetched-At") ?? response.headers.get("Date");
  const date = value ? new Date(value) : null;
  return date && !Number.isNaN(date.getTime()) ? date : null;
}

const tracked = new Set();
let ticker = 0;

/**
 * Render "Updated 5 minutes ago" into a <time> element and keep it current.
 * @param {HTMLTimeElement} el
 * @param {Date} date
 * @param {{staleAfterMs?: number}} [options]
 */
export function showFreshness(el, date, { staleAfterMs = 60 * 60 * 1000 } = {}) {
  el.dateTime = date.toISOString();
  el.title = date.toLocaleString(); // exact time on hover
  el.dataset.staleAfter = String(staleAfterMs);
  update(el);
  tracked.add(el);
  ticker ||= setInterval(() => {
    for (const node of tracked) (node.isConnected ? update(node) : tracked.delete(node));
    if (tracked.size === 0) ticker = (clearInterval(ticker), 0);
  }, 30_000);
}

function update(el) {
  const date = new Date(el.dateTime);
  el.textContent = `Updated ${formatAge(date)}`;
  el.toggleAttribute("data-stale", Date.now() - date.getTime() > Number(el.dataset.staleAfter));
}