first commit

docs/foundation/data/react-packer/src/hooks/use-packed-image/use-packed-image.md

@@ -0,0 +1,79 @@
+# `usePackedImage` — image-tuned packed-resource hook
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`usePackedImage` is a thin wrapper around `usePackedResource` that
+pre-fills sensible defaults for image assets: caching is enabled (images
+tend to be re-used across renders) and the manager's MIME allow-list is
+narrowed to `image/`-prefixed types so a misconfigured archive serving
+HTML or JavaScript under a virtual image URL fails fast at the loader
+boundary rather than the `<img>` tag.
+
+The hook returns the same `UsePackedResourceReturn` shape as the generic
+hook, so it is drop-in for any component that already consumes
+`usePackedResource`.
+
+## Features
+
+- `cache: true` default — caller can opt out with `{ cache: false }`.
+- `allowedMimePrefixes: ["image/"]` default — caller can broaden or
+  narrow.
+- Forwards `verifyKey`, `verifyChecksum`, and `signal` untouched.
+- Identical return shape to `usePackedResource` for trivial swapping.
+
+## Usage: Basic
+
+```tsx
+import { usePackedImage } from "@suaveplan/react-packer";
+
+function Avatar({ src }: { src: string | null }) {
+    const { url, loading } = usePackedImage(src);
+    if (loading) return <div className="avatar avatar--loading" />;
+    return url !== null ? <img alt="" className="avatar" src={url} /> : null;
+}
+```
+
+## Usage: Advanced
+
+```tsx
+import { usePackedImage } from "@suaveplan/react-packer";
+
+function SignedAvatar({
+    src,
+    key,
+}: {
+    src: string;
+    key: Uint8Array;
+}) {
+    const { url, error } = usePackedImage(src, {
+        verifyChecksum: true,
+        verifyKey: key,
+        allowedMimePrefixes: ["image/avif", "image/webp"],
+    });
+    if (error !== null) return <span>{error.code}</span>;
+    return url !== null ? <img alt="" src={url} /> : null;
+}
+```
+
+## API Reference
+
+- `usePackedImage(packedUrl, options?): UsePackedResourceReturn`
+- Behaviour is identical to `usePackedResource` except defaults differ:
+  - `cache` defaults to `true`.
+  - `allowedMimePrefixes` defaults to `["image/"]`.
+- All other options pass through unchanged.
+
+## Implementation Notes
+
+- Defaults apply only when the caller omits the key — explicit `false`
+  or an empty array opt out of caching / MIME enforcement respectively.
+- The MIME allow-list is honoured by the manager's loader, not by the
+  hook itself; non-image archives surface as
+  `ReactPackerError(LOAD_FAILED)` with the underlying
+  `PackerBrowserError(UNSUPPORTED_RESOURCE_TYPE)` on `.cause`.
+- The constant `IMAGE_MIME_PREFIXES` is module-local and frozen via
+  `ReadonlyArray` typing so consumers cannot mutate the default.