# @suaveplan/react-packer - React 19 companion for @suaveplan/packer-browser — usePackedResource, usePackedImage, usePackedAudio, usePackedVideo, usePackedFont hooks plus PackedResourceProvider context. Consumes a real PackedResourceManager; React is a peer dep so non-React consumers never pay the cost.

React 19 companion for `@suaveplan/packer-browser`. Ships
`usePackedResource`, `usePackedImage`, `usePackedAudio`,
`usePackedVideo`, and `usePackedFont` hooks plus a
`PackedResourceProvider` context, so applications can consume packed
asset archives from React components without `@suaveplan/packer-browser`
having to ship React as a runtime dep.

<!-- begin:auto-docs -->
## Documentation tree

- [error-codes](./src/error-codes/error-codes.md) — Defines the canonical error-code registry and concrete error class for the React-tier packer companion. Every failure m…
  - [error-codes](./src/error-codes/error-codes.md) — Defines the canonical error-code registry and concrete error class for the React-tier packer companion. Every failure m…
- [use-packed-audio](./src/hooks/use-packed-audio/use-packed-audio.md) — `usePackedAudio` is the audio analogue of `usePackedImage`. It binds a packed audio asset URL to a React component's li…
  - [use-packed-audio](./src/hooks/use-packed-audio/use-packed-audio.md) — `usePackedAudio` is the audio analogue of `usePackedImage`. It binds a packed audio asset URL to a React component's li…
- [use-packed-font](./src/hooks/use-packed-font/use-packed-font.md) — `usePackedFont` loads a packed font asset and registers it with the document so subsequent rules referencing the suppli…
  - [use-packed-font](./src/hooks/use-packed-font/use-packed-font.md) — `usePackedFont` loads a packed font asset and registers it with the document so subsequent rules referencing the suppli…
- [use-packed-image](./src/hooks/use-packed-image/use-packed-image.md) — `usePackedImage` is a thin wrapper around `usePackedResource` that pre-fills sensible defaults for image assets: cachin…
  - [use-packed-image](./src/hooks/use-packed-image/use-packed-image.md) — `usePackedImage` is a thin wrapper around `usePackedResource` that pre-fills sensible defaults for image assets: cachin…
- [use-packed-resource](./src/hooks/use-packed-resource/use-packed-resource.md) — `usePackedResource` is the foundation hook of `@suaveplan/react-packer`. It binds a packed-archive virtual URL (e.g. `/…
  - [use-packed-resource](./src/hooks/use-packed-resource/use-packed-resource.md) — `usePackedResource` is the foundation hook of `@suaveplan/react-packer`. It binds a packed-archive virtual URL (e.g. `/…
- [use-packed-video](./src/hooks/use-packed-video/use-packed-video.md) — `usePackedVideo` binds a packed video asset URL to a React component's lifecycle. Unlike the image and audio variants,…
  - [use-packed-video](./src/hooks/use-packed-video/use-packed-video.md) — `usePackedVideo` binds a packed video asset URL to a React component's lifecycle. Unlike the image and audio variants,…
- [packed-resource-provider](./src/provider/packed-resource-provider/packed-resource-provider.md) — `PackedResourceProvider` lets a React tree explicitly inject a `PackedResourceManager` from `@suaveplan/packer-browser`…
  - [packed-resource-provider](./src/provider/packed-resource-provider/packed-resource-provider.md) — `PackedResourceProvider` lets a React tree explicitly inject a `PackedResourceManager` from `@suaveplan/packer-browser`…
<!-- end:auto-docs -->

## Install

```bash
bun add @suaveplan/react-packer @suaveplan/packer-browser
```

`react` and `react-dom` (≥ 19.0.0) are peer dependencies — the package
does not bundle them.

## Quick start

```tsx
import { createPackedResourceManager } from "@suaveplan/packer-browser";
import { PackedResourceProvider, usePackedImage } from "@suaveplan/react-packer";

const manager = createPackedResourceManager();

function App() {
    return (
        <PackedResourceProvider value={{ manager }}>
            <Logo />
        </PackedResourceProvider>
    );
}

function Logo() {
    const { url, loading, error } = usePackedImage("/assets/logo.packed");
    if (loading) return <div className="logo logo--loading" />;
    if (error !== null) return <div className="logo logo--error" />;
    return url !== null ? <img alt="logo" src={url} /> : null;
}
```

If you do not mount a `PackedResourceProvider`, hooks fall back to the
singleton at `@suaveplan/packer-browser/singleton`. Adopters that prefer
zero-config get a working manager for free; adopters that want explicit
lifecycle (tests, SSR, multi-tenant apps) mount a provider and skip the
singleton entirely.

## Features

- Five hooks: `usePackedResource` (generic), `usePackedImage`,
  `usePackedAudio`, `usePackedVideo`, `usePackedFont`.
- React 19 context provider for explicit `PackedResourceManager` and
  `MessageResolver` injection.
- `AbortSignal` honored throughout — pre-aborted signals short-circuit,
  unmount cancels the in-flight load, and changing the packed URL
  aborts the previous one.
- Stable error registry — `REACT_PACKER_CODES` + `ReactPackerError`
  branded subclass over `@suaveplan/error`.
- `cleanup` releases the cached entry on unmount so the manager's LRU
  can evict.

## Modules

- [`src/error-codes/error-codes.md`](./src/error-codes/error-codes.md)
- [`src/types/react-packer.types.md`](./src/types/react-packer.types.md)
- [`src/provider/packed-resource-provider/packed-resource-provider.md`](./src/provider/packed-resource-provider/packed-resource-provider.md)
- [`src/hooks/use-packed-resource/use-packed-resource.md`](./src/hooks/use-packed-resource/use-packed-resource.md)
- [`src/hooks/use-packed-image/use-packed-image.md`](./src/hooks/use-packed-image/use-packed-image.md)
- [`src/hooks/use-packed-audio/use-packed-audio.md`](./src/hooks/use-packed-audio/use-packed-audio.md)
- [`src/hooks/use-packed-video/use-packed-video.md`](./src/hooks/use-packed-video/use-packed-video.md)
- [`src/hooks/use-packed-font/use-packed-font.md`](./src/hooks/use-packed-font/use-packed-font.md)