Cache exercise images offline

Author: nyxar77

PRIVACY.md

@@ -4,6 +4,8 @@ Pulse does not collect, transmit, sell, or share personal data. It has no accoun
 
 Your exercise library, weekly programme, settings, and completion history are stored locally on your device. Pulse only sends that data elsewhere when you explicitly export or share a backup.
 
-Pulse accepts optional image and guide URLs for exercises. Opening a guide or displaying a remote image connects directly to the service you chose, which is governed by that service's privacy policy. Pulse does not receive data from those requests.
+Pulse connects to the internet only when you expand an exercise that has an image URL you supplied. The image is requested directly from that service and cached on your device for later offline viewing. Opening a guide hands its URL to your browser. Those services receive the normal connection information described by their own privacy policies; Pulse has no server and does not receive it.
+
+The image cache keeps at most 40 images and is removed when you clear Pulse's app storage. Android therefore lists network access for Pulse, but the app does not perform background syncing or contact an account, analytics, advertising, or tracking service.
 
 You can remove Pulse's stored data by clearing the app's storage or uninstalling it. Export a JSON backup first if you want to keep your programme.

README.md

@@ -6,7 +6,7 @@ Pulse is a local-first weekly workout planner for Android and the web. It is bui
 
 - Maps custom workouts onto the seven days of the week
 - Shows the workout that matches the device's current local date
-- Saves a reusable exercise library with muscles, equipment, notes, images, and guide links
+- Saves a reusable exercise library with muscles, equipment, notes, cached reference images, and guide links
 - Stores sets, reps, weight, and rest targets with drag-to-reorder priority
 - Tracks completed exercises by date
 - Imports and exports the complete programme as JSON

fastlane/metadata/android/en-US/full_description.txt

@@ -2,7 +2,7 @@ Pulse is a private, offline workout planner built around your training rules.
 
 Create custom workouts and assign them to any of the seven weekdays. Pulse uses your device's local date to show the correct workout for today, with a clear checklist for the exercises you complete.
 
-Build a reusable exercise library with custom muscle groups, equipment, tags, notes, images, and guide links. Add exercises to a workout, set their sets, reps, weight, and rest targets, then drag them into the order you want.
+Build a reusable exercise library with custom muscle groups, equipment, tags, notes, cached reference images, and guide links. Images are fetched only after you expand an exercise, then kept on the device for offline viewing. Add exercises to a workout, set their sets, reps, weight, and rest targets, then drag them into the order you want.
 
 Your programme stays on your device. There are no accounts, ads, analytics, or trackers. Export the complete ledger as JSON whenever you want a portable backup, and import it again on another device.
 

src/lib/exercise-image-cache.ts

@@ -0,0 +1,40 @@
+export const exerciseImageCacheName = "pulse-exercise-images-v1";
+export const maxCachedExerciseImages = 40;
+
+type ExerciseImageCache = Pick<Cache, "delete" | "keys" | "match" | "put">;
+
+type ExerciseImageCacheStorage = {
+  open(name: string): Promise<ExerciseImageCache>;
+};
+
+type ExerciseImageFetcher = (request: Request) => Promise<Response>;
+
+export async function loadExerciseImage(
+  request: Request,
+  cacheStorage: ExerciseImageCacheStorage = caches,
+  fetchImage: ExerciseImageFetcher = fetch,
+): Promise<Response> {
+  let cache: ExerciseImageCache | undefined;
+
+  try {
+    cache = await cacheStorage.open(exerciseImageCacheName);
+    const cached = await cache.match(request);
+    if (cached) return cached;
+  } catch {
+    // Private browsing and storage pressure can make Cache Storage unavailable.
+  }
+
+  const response = await fetchImage(request);
+  if (!cache || (!response.ok && response.type !== "opaque")) return response;
+
+  try {
+    await cache.put(request, response.clone());
+    const keys = await cache.keys();
+    const overflow = Math.max(0, keys.length - maxCachedExerciseImages);
+    await Promise.all(keys.slice(0, overflow).map((key) => cache.delete(key)));
+  } catch {
+    // A failed cache write must not block the image that already loaded.
+  }
+
+  return response;
+}

src/routes/+page.svelte

@@ -1145,7 +1145,7 @@
               ></textarea></label
             >
             <label class="wide"><span>Reference link · optional</span><input type="url" bind:value={exerciseDraft.guideUrl} placeholder="https://…" /></label>
-            <label class="wide"><span>Image link · optional</span><input type="url" bind:value={exerciseDraft.imageUrl} placeholder="https://…" /></label>
+            <label class="wide"><span>Image link · cached after first view</span><input type="url" bind:value={exerciseDraft.imageUrl} placeholder="https://…" /></label>
           </div>
           {#if exerciseFormError}<p class="exercise-form-error">
               {exerciseFormError}

src/service-worker.ts

@@ -1,6 +1,7 @@
 /// <reference lib="webworker" />
 
 import { build, files, prerendered, version } from '$service-worker';
+import { exerciseImageCacheName, loadExerciseImage } from '$lib/exercise-image-cache';
 
 const worker = globalThis as unknown as ServiceWorkerGlobalScope;
 const cacheName = `pulse-${version}`;
@@ -15,7 +16,11 @@ worker.addEventListener('install', (event) => {
 worker.addEventListener('activate', (event) => {
 	event.waitUntil(
 		Promise.all([
-			caches.keys().then((keys) => Promise.all(keys.filter((key) => key.startsWith('pulse-') && key !== cacheName).map((key) => caches.delete(key)))),
+			caches
+				.keys()
+				.then((keys) =>
+					Promise.all(keys.filter((key) => key.startsWith('pulse-') && key !== cacheName && key !== exerciseImageCacheName).map((key) => caches.delete(key)))
+				),
 			worker.clients.claim()
 		])
 	);
@@ -26,7 +31,12 @@ worker.addEventListener('fetch', (event) => {
 	if (request.method !== 'GET') return;
 
 	const url = new URL(request.url);
-	if (url.origin !== worker.location.origin) return;
+	if (url.origin !== worker.location.origin) {
+		if (request.destination === 'image' && (url.protocol === 'https:' || url.protocol === 'http:')) {
+			event.respondWith(loadExerciseImage(request));
+		}
+		return;
+	}
 
 	if (appFileSet.has(url.pathname)) {
 		event.respondWith(caches.match(request).then((cached) => cached ?? fetch(request)));

tests/exercise-image-cache.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+import {
+  exerciseImageCacheName,
+  loadExerciseImage,
+  maxCachedExerciseImages,
+} from "../src/lib/exercise-image-cache";
+
+class MemoryImageCache {
+  entries = new Map<string, Response>();
+
+  async delete(request: Request) {
+    return this.entries.delete(request.url);
+  }
+
+  async keys() {
+    return [...this.entries.keys()].map((url) => new Request(url));
+  }
+
+  async match(request: Request) {
+    return this.entries.get(request.url)?.clone();
+  }
+
+  async put(request: Request, response: Response) {
+    this.entries.set(request.url, response);
+  }
+}
+
+describe("exercise image cache", () => {
+  test("uses the cached image without another request", async () => {
+    const cache = new MemoryImageCache();
+    const request = new Request("https://example.com/press.webp");
+    cache.entries.set(request.url, new Response("cached"));
+    let fetches = 0;
+
+    const response = await loadExerciseImage(
+      request,
+      {
+        open: async (name) => {
+          expect(name).toBe(exerciseImageCacheName);
+          return cache;
+        },
+      },
+      async () => {
+        fetches += 1;
+        return new Response("network");
+      },
+    );
+
+    expect(await response.text()).toBe("cached");
+    expect(fetches).toBe(0);
+  });
+
+  test("stores fetched images and removes the oldest beyond the limit", async () => {
+    const cache = new MemoryImageCache();
+    for (let index = 0; index < maxCachedExerciseImages; index += 1) {
+      cache.entries.set(
+        `https://example.com/${index}.webp`,
+        new Response(String(index)),
+      );
+    }
+
+    const newest = new Request("https://example.com/new.webp");
+    const response = await loadExerciseImage(
+      newest,
+      { open: async () => cache },
+      async () => new Response("new"),
+    );
+
+    expect(await response.text()).toBe("new");
+    expect(cache.entries.size).toBe(maxCachedExerciseImages);
+    expect(cache.entries.has("https://example.com/0.webp")).toBeFalse();
+    expect(cache.entries.has(newest.url)).toBeTrue();
+  });
+
+  test("still loads from the network when device caching is unavailable", async () => {
+    const response = await loadExerciseImage(
+      new Request("https://example.com/row.webp"),
+      { open: async () => Promise.reject(new Error("storage unavailable")) },
+      async () => new Response("network"),
+    );
+
+    expect(await response.text()).toBe("network");
+  });
+});