Persistence & GerbilGate

Name: Gerbil
Author: Gerbil

Gerbil caches model weights on-device so they download once and load instantly afterward, and the <GerbilGate> component gates your app behind that download with a splash screen while the engine warms up.

Persistence

Gerbil caches downloaded model weights in IndexedDB automatically. The engine owns this — there is nothing extra to configure. The first time you create the engine it downloads the model; every run after that loads straight from the on-device cache, with no network and no re-download.

On iOS especially, the browser can evict cached data under storage pressure. To keep your model cached across visits, request persistent storage — once granted, the cache survives eviction:

persistent-storage.ts

01import {
02  requestPersistentStorage,
03  getStorageStatus,
04} from "@tryhamster/gerbil/browser";
05
06// Ask the browser to keep cached data across visits.
07// On iOS this is most reliably granted from the Home Screen (PWA).
08const persisted = await requestPersistentStorage();
09console.log(persisted); // true once the browser grants it
10
11// Inspect the current storage status (persisted flag + usage/quota).
12const status = await getStorageStatus();
13console.log(status);

Before kicking off a download, you can check whether a model of a given size will fit in the remaining quota. canCacheModel(sizeMB) answers that directly, and checkStorageQuota() returns the raw usage and quota numbers so you can surface them in your UI:

storage-quota.ts

01import {
02  canCacheModel,
03  checkStorageQuota,
04} from "@tryhamster/gerbil/browser";
05
06// Will a ~550 MB model fit in the remaining quota?
07const fit = await canCacheModel(550);
08if (!fit.fits) {
09  // Warn the user, free up space, or pick a smaller model.
10}
11
12// Or read the raw numbers (all in MB) and decide yourself.
13const { usedMB, quotaMB } = await checkStorageQuota(550);
14console.log(`Using ${usedMB} of ${quotaMB} MB`);

The four helpers: requestPersistentStorage(), getStorageStatus(), canCacheModel(sizeMB), and checkStorageQuota() all live in @tryhamster/gerbil/browser.

For how weights are stored and reused across runs, see the Caching guide. For the iOS and PWA specifics of persistent storage, see the Mobile & PWA guide.

GerbilGate

<GerbilGate> is a React component (added in 1.0.2, exported from @tryhamster/gerbil/hooks) that gates your app behind the model download. Wrap your app in it: while the engine downloads and initializes, it shows a splash/loading screen; once the engine is ready, it renders its children. Your UI only mounts when on-device inference is live, so no child component ever has to handle a not-yet-loaded model.

Because the gate stays mounted for the lifetime of your app, it also keeps the shared engine warm. Client-side navigation never re-uploads the weights to the GPU and never trips the engine’s ~30s teardown window — every route change keeps inference instantly available.

basic-gate.tsx

01import { GerbilGate } from "@tryhamster/gerbil/hooks";
02
03export default function Root() {
04  return (
05    <GerbilGate
06      model="mlx-community/Qwen3.5-0.8B-4bit"
07      fallback={<div>Loading…</div>}
08    >
09      <App />
10    </GerbilGate>
11  );
12}

The full prop surface:

gerbil-gate-props.ts

01interface GerbilGateProps {
02  model?: string;
03  children: ReactNode;
04  fallback?: GateSlot;        // splash while loading
05  errorFallback?: GateSlot;   // shown on error
06  enableVision?: boolean;
07  dtype?: "auto" | "f32" | "q4";
08  maxSeqLen?: number;
09}
10
11// A slot is either static UI or a render function that receives live state.
12type GateSlot =
13  | ReactNode
14  | ((s: {
15      progress: number | null;   // 0–100, or null if unknown
16      status: string | null;     // e.g. "Downloading model…"
17      error: unknown;
18      errorKind: EngineErrorKind | null;
19    }) => ReactNode);

Splash page

Pass a render function to fallback to build a real splash screen with live progress. It receives progress (0–100, or null while the total is unknown) and a human-readable status. Use errorFallback the same way to render a recovery screen keyed off errorKind:

splash-gate.tsx

01import { GerbilGate } from "@tryhamster/gerbil/hooks";
02import { Splash } from "./Splash";
03import { ErrorScreen } from "./ErrorScreen";
04import { App } from "./App";
05
06export default function Root() {
07  return (
08    <GerbilGate
09      model="mlx-community/Qwen3.5-0.8B-4bit"
10      fallback={({ progress, status }) => (
11        <Splash>
12          {status} {progress != null && `${progress}%`}
13        </Splash>
14      )}
15      errorFallback={({ error, errorKind }) => (
16        <ErrorScreen kind={errorKind} />
17      )}
18    >
19      <App />
20    </GerbilGate>
21  );
22}

Combine the two. GerbilGate keeps the engine warm and persistence keeps the weights cached, so the model downloads only once: the splash appears on the very first visit, and every later load is instant and works offline.