# `prefetch` — BackgroundFetch integration

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

The `prefetch` module wraps the Chromium `BackgroundFetchManager` API so
an application can preload an archive on idle without holding the page
open. The page side calls `prefetchPackedArchive(url, opts)` to kick off
the registration; the Service Worker listens for
`backgroundfetchsuccess` and calls `handleBackgroundFetchSuccess` to
drain the records into the same cache the rest of `@suaveplan/packer-browser`
uses. Failures and aborts route through `handleBackgroundFetchFailure`.

These helpers are PACKER-BROWSER-20's production surface. They are
feature-detected — if the browser does not implement BackgroundFetch
(`navigator.serviceWorker.ready.backgroundFetch` is undefined and no
`backgroundFetch` is injected), `prefetchPackedArchive` resolves with
`null` and the caller's flow continues with a regular fetch.

## Features

- API feature-detection — graceful `null` when BackgroundFetch is absent
- Pluggable `backgroundFetch` injection for tests
- OTel counters: `packed_resource_prefetch_success_total` and
  `packed_resource_prefetch_failure_total`
- Cache-drain helper writes every record's response into the configured
  cache (default `packed-resources-v1`) so the SW's existing fetch
  handler hits cached entries on the next request

## Usage: Basic

```ts
import { prefetchPackedArchive } from "@suaveplan/packer-browser/prefetch";

// Page side:
const reg = await prefetchPackedArchive("/big.bundle.asset");
if (reg !== null) console.log("BG fetch started:", reg.id);
```

```ts
// Service worker side:
import { handleBackgroundFetchSuccess } from "@suaveplan/packer-browser/prefetch";

self.addEventListener("backgroundfetchsuccess", (event) => {
    event.waitUntil(
        handleBackgroundFetchSuccess(event, {
            observability,
            cacheName: "packed-resources-v1",
        })
    );
});
```

## Usage: Advanced

```ts
import {
    handleBackgroundFetchFailure,
    handleBackgroundFetchSuccess,
    prefetchPackedArchive,
} from "@suaveplan/packer-browser/prefetch";

const reg = await prefetchPackedArchive("/heavy.bundle.asset", {
    id: "heavy-asset",
    options: {
        title: "Pre-loading heavy asset",
        icons: [{ src: "/icon-192.png", sizes: "192x192" }],
    },
    observability,
});

// Failure listener — counts every abort.
self.addEventListener("backgroundfetchfail", (event) =>
    handleBackgroundFetchFailure(event, { observability })
);
```

## API Reference

- `prefetchPackedArchive(archiveUrl, opts?): Promise<BackgroundFetchRegistrationLike | null>`
- `handleBackgroundFetchSuccess(event, { caches?, cacheName?, observability }): Promise<void>`
- `handleBackgroundFetchFailure(event, { observability }): void`

Every helper accepts a fully injectable cache storage / background
fetch manager so tests can exercise real failure modes (cache write
rejection, missing API, registration with zero records) without any
mocking.

## Implementation Notes

- `prefetchPackedArchive` never reads the `navigator` global directly:
  production callers receive the `BackgroundFetchManager` from
  `await navigator.serviceWorker.ready` and pass it in. This keeps the
  helper safe to call from non-DOM contexts (workers, tests).
- The success handler clones every response before writing to the cache
  so the body stream is consumed exactly once.
- Failure counter increments are emitted from BOTH
  `prefetchPackedArchive` (when the underlying `fetch()` rejects) AND
  `handleBackgroundFetchFailure` (for SW-side abort events) so dashboards
  show every failure regardless of which layer caught it.