feat: let the user download and free the cached engine

Author: Endika

src/bootstrap/Container.ts

@@ -5,6 +5,7 @@ import type { ISignClassifier } from '@domain/recognition/services/ISignClassifi
 import { IndexedDBCustomSignRepository } from '@infrastructure/persistence/indexeddb/IndexedDBCustomSignRepository';
 import { HandshapeAlphabetClassifier } from '@infrastructure/recognition/HandshapeAlphabetClassifier';
 import { PrototypeSignClassifier } from '@infrastructure/recognition/PrototypeSignClassifier';
+import { EngineCacheStorage } from '@infrastructure/storage/EngineCacheStorage';
 import { MediaPipeLandmarkSource } from '@infrastructure/vision/MediaPipeLandmarkSource';
 
 /**
@@ -17,6 +18,7 @@ export class Container {
   readonly taught = new PrototypeSignClassifier(this.customSigns);
   readonly teach = new TeachCustomSignUseCase(this.customSigns);
   readonly manageCustomSigns = new ManageCustomSignsUseCase(this.customSigns);
+  readonly engineStorage = new EngineCacheStorage();
   readonly classifiers: readonly ISignClassifier[];
   readonly recognize: RecognizeSignsUseCase;
 

src/infrastructure/storage/EngineCacheStorage.ts

@@ -0,0 +1,68 @@
+/** Must match the `runtimeCaching` cacheName in `vite.config.ts`. */
+const CACHE_NAME = 'esku-engine';
+
+export interface EngineStorageReport {
+  readonly cachedBytes: number;
+  readonly entries: number;
+}
+
+/**
+ * Inspects and frees the cached recognition engine.
+ *
+ * The engine is roughly 29 MB of WASM and model weights, cached on first use so the app
+ * works offline afterwards. That is a real amount of a phone's storage to take without
+ * asking, and someone who only wanted to try fingerspelling once should be able to get it
+ * back.
+ *
+ * Deliberately does not touch taught signs: those are the user's own recordings, they live
+ * in IndexedDB, and losing them to a "free up space" button would be a data-loss trap.
+ */
+export class EngineCacheStorage {
+  isSupported(): boolean {
+    return typeof caches !== 'undefined';
+  }
+
+  async report(): Promise<EngineStorageReport> {
+    if (!this.isSupported()) return { cachedBytes: 0, entries: 0 };
+
+    const cache = await caches.open(CACHE_NAME);
+    const requests = await cache.keys();
+
+    let cachedBytes = 0;
+    for (const request of requests) {
+      const response = await cache.match(request);
+      if (response) cachedBytes += await sizeOf(response);
+    }
+
+    return { cachedBytes, entries: requests.length };
+  }
+
+  /** Returns false when there was nothing cached to begin with. */
+  async clear(): Promise<boolean> {
+    if (!this.isSupported()) return false;
+    return caches.delete(CACHE_NAME);
+  }
+}
+
+/**
+ * Content-Length first, body second.
+ *
+ * Reading the blob is exact but pulls the whole 11 MB WASM into memory just to measure it;
+ * the header avoids that whenever the server sent one, which GitHub Pages does.
+ */
+async function sizeOf(response: Response): Promise<number> {
+  const declared = Number(response.headers.get('content-length'));
+  if (Number.isFinite(declared) && declared > 0) return declared;
+
+  try {
+    return (await response.clone().blob()).size;
+  } catch {
+    return 0;
+  }
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes <= 0) return '0 MB';
+  const megabytes = bytes / (1024 * 1024);
+  return megabytes < 10 ? `${megabytes.toFixed(1)} MB` : `${Math.round(megabytes)} MB`;
+}

src/infrastructure/storage/__tests__/EngineCacheStorage.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { EngineCacheStorage, formatBytes } from '../EngineCacheStorage';
+
+describe('formatBytes', () => {
+  it('reads a large engine in whole megabytes', () => {
+    expect(formatBytes(29 * 1024 * 1024)).toBe('29 MB');
+  });
+
+  it('keeps a decimal below ten megabytes, where rounding would hide the difference', () => {
+    expect(formatBytes(7.5 * 1024 * 1024)).toBe('7.5 MB');
+  });
+
+  it('shows nothing cached as zero rather than a negative or NaN', () => {
+    expect(formatBytes(0)).toBe('0 MB');
+    expect(formatBytes(-1)).toBe('0 MB');
+  });
+});
+
+describe('EngineCacheStorage', () => {
+  it('reports nothing cached where the Cache API is unavailable', async () => {
+    // jsdom has no CacheStorage, which is also the real situation in a non-secure context.
+    const storage = new EngineCacheStorage();
+    expect(storage.isSupported()).toBe(false);
+    expect(await storage.report()).toEqual({ cachedBytes: 0, entries: 0 });
+  });
+
+  it('reports nothing freed rather than throwing when there is no cache to clear', async () => {
+    expect(await new EngineCacheStorage().clear()).toBe(false);
+  });
+});

src/presentation/App.ts

@@ -2,6 +2,7 @@ import { Container } from '@bootstrap/Container';
 import { CameraUnavailableError } from '@domain/landmarks/services/ILandmarkSource';
 import { UNSUPPORTED_LETTERS } from '@infrastructure/recognition/packs/lseAlphabet';
 import { LandmarkOverlay, type OverlayState } from '@presentation/components/LandmarkOverlay';
+import { StoragePanel } from '@presentation/components/StoragePanel';
 import { TeachSignPanel } from '@presentation/components/TeachSignPanel';
 
 declare const __APP_VERSION__: string;
@@ -36,6 +37,7 @@ export function renderApp(root: HTMLElement): void {
     <p class="status" id="status" role="status"></p>
 
     <div id="teach"></div>
+    <div id="storage"></div>
 
     <section class="card">
       <h2 class="card__title">Deletreo, por ahora</h2>
@@ -134,6 +136,15 @@ export function renderApp(root: HTMLElement): void {
     render(recognize.current.toText(), []);
   });
 
+  new StoragePanel(must<HTMLElement>(root, '#storage'), {
+    isSupported: () => container.engineStorage.isSupported(),
+    report: () => container.engineStorage.report(),
+    clear: () => container.engineStorage.clear(),
+    // Loading through the real source downloads exactly the WASM variant this browser will
+    // use, rather than guessing and fetching both the SIMD and no-SIMD builds.
+    preload: () => container.source.load(),
+  });
+
   new TeachSignPanel(must<HTMLElement>(root, '#teach'), {
     captureWindow: () => recognize.captureWindow(),
     cancelCapture: () => {

src/presentation/components/StoragePanel.ts

@@ -0,0 +1,115 @@
+import { formatBytes } from '@infrastructure/storage/EngineCacheStorage';
+
+export interface StoragePanelPorts {
+  isSupported(): boolean;
+  report(): Promise<{ cachedBytes: number; entries: number }>;
+  clear(): Promise<boolean>;
+  /** Fetches the engine now, so the first real use is not the first download. */
+  preload(): Promise<void>;
+}
+
+/**
+ * Lets the user see and reclaim the space the recognition engine takes.
+ *
+ * Downloading is offered up front rather than only happening on first use: knowing it is
+ * ~29 MB before it starts is the difference between a considered choice and a surprise on
+ * mobile data.
+ */
+export class StoragePanel {
+  private busy = false;
+
+  constructor(
+    private readonly root: HTMLElement,
+    private readonly ports: StoragePanelPorts,
+  ) {
+    this.render();
+    void this.refresh();
+  }
+
+  private render(): void {
+    this.root.innerHTML = `
+      <section class="card">
+        <h2 class="card__title">Espacio en el dispositivo</h2>
+        <p class="card__body">
+          El motor de reconocimiento ocupa unos 29 MB y se guarda la primera vez que lo usas,
+          para que después funcione sin conexión. Puedes descargarlo ahora o liberarlo cuando
+          quieras: se volverá a bajar solo la próxima vez que enciendas la cámara.
+        </p>
+
+        <p class="storage" id="storage-figure">—</p>
+
+        <div class="actions">
+          <button class="button button--quiet" id="preload" type="button">Descargar ahora</button>
+          <button class="button button--quiet" id="clear" type="button">Liberar espacio</button>
+        </div>
+
+        <p class="status" id="storage-status" role="status"></p>
+        <p class="card__body card__body--tight">
+          Los signos que le hayas enseñado no se borran con esto: son tuyos y se guardan aparte.
+        </p>
+      </section>
+    `;
+
+    this.button('preload').addEventListener('click', () => void this.preload());
+    this.button('clear').addEventListener('click', () => void this.clear());
+  }
+
+  private button(id: string): HTMLButtonElement {
+    return this.root.querySelector<HTMLButtonElement>(`#${id}`)!;
+  }
+
+  private say(message: string): void {
+    this.root.querySelector<HTMLElement>('#storage-status')!.textContent = message;
+  }
+
+  private setBusy(busy: boolean): void {
+    this.busy = busy;
+    this.button('preload').disabled = busy;
+    this.button('clear').disabled = busy;
+  }
+
+  private async preload(): Promise<void> {
+    if (this.busy) return;
+    this.setBusy(true);
+    this.say('Descargando el motor…');
+    try {
+      await this.ports.preload();
+      this.say('Motor descargado. Ya funciona sin conexión.');
+    } catch {
+      this.say('No se pudo descargar. Comprueba la conexión.');
+    } finally {
+      this.setBusy(false);
+      await this.refresh();
+    }
+  }
+
+  private async clear(): Promise<void> {
+    if (this.busy) return;
+    this.setBusy(true);
+    try {
+      const removed = await this.ports.clear();
+      this.say(
+        removed
+          ? 'Espacio liberado. Se volverá a descargar la próxima vez.'
+          : 'No había nada guardado.',
+      );
+    } finally {
+      this.setBusy(false);
+      await this.refresh();
+    }
+  }
+
+  private async refresh(): Promise<void> {
+    const figure = this.root.querySelector<HTMLElement>('#storage-figure')!;
+
+    if (!this.ports.isSupported()) {
+      figure.textContent = 'Este navegador no permite consultar el almacenamiento.';
+      this.setBusy(true);
+      return;
+    }
+
+    const { cachedBytes, entries } = await this.ports.report();
+    figure.textContent =
+      entries === 0 ? 'Nada guardado todavía' : `${formatBytes(cachedBytes)} guardados`;
+  }
+}

src/presentation/styles/global.css

@@ -355,3 +355,15 @@ body {
   color: var(--text-muted);
   font-size: 0.9rem;
 }
+
+.storage {
+  font-size: 1.4rem;
+  font-weight: 650;
+  letter-spacing: -0.02em;
+  margin: 14px 0 4px;
+}
+
+.card__body--tight {
+  font-size: 0.78rem;
+  margin-top: 10px;
+}