Initial Commit

packages/foundation/data/react-packer/src/hooks/use-packed-audio/use-packed-audio.md

@@ -0,0 +1,81 @@
+# `usePackedAudio` — audio-tuned packed-resource hook
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`usePackedAudio` is the audio analogue of `usePackedImage`. It binds a
+packed audio asset URL to a React component's lifecycle, defaults to
+caching the underlying bytes (audio cues are typically re-triggered),
+and narrows the manager's MIME allow-list to `audio/`-prefixed types so
+misconfigured archives serving non-audio bytes fail fast at the loader
+rather than at `<audio>` decode time.
+
+The return shape matches `UsePackedResourceReturn` so callers swap
+between variant hooks without touching downstream rendering code.
+
+## Features
+
+- `cache: true` default; opt out per call.
+- `allowedMimePrefixes: ["audio/"]` default.
+- Forwards `verifyKey`, `verifyChecksum`, and `signal` to the underlying
+  generic hook.
+- Identical return shape to `usePackedResource`.
+
+## Usage: Basic
+
+```tsx
+import { usePackedAudio } from "@suaveplan/react-packer";
+
+function CueButton({ cue }: { cue: string | null }) {
+    const { url, loading } = usePackedAudio(cue);
+    if (loading || url === null) return <button disabled>…</button>;
+    return (
+        <button type="button" onClick={() => new Audio(url).play()}>
+            Play
+        </button>
+    );
+}
+```
+
+## Usage: Advanced
+
+```tsx
+import { usePackedAudio } from "@suaveplan/react-packer";
+
+function SignedCue({
+    cue,
+    verifyKey,
+}: {
+    cue: string;
+    verifyKey: Uint8Array;
+}) {
+    const { url, error, reload } = usePackedAudio(cue, {
+        verifyChecksum: true,
+        verifyKey,
+        allowedMimePrefixes: ["audio/ogg", "audio/webm"],
+    });
+    if (error !== null) return <button onClick={reload}>Retry</button>;
+    return url !== null ? <audio controls src={url} /> : null;
+}
+```
+
+## API Reference
+
+- `usePackedAudio(packedUrl, options?): UsePackedResourceReturn`
+- Defaults differ from `usePackedResource`:
+  - `cache` defaults to `true`.
+  - `allowedMimePrefixes` defaults to `["audio/"]`.
+- All other options pass through.
+
+## Implementation Notes
+
+- Explicit caller options always win. Passing `{ cache: false }`
+  disables caching for that hook instance; passing
+  `{ allowedMimePrefixes: [] }` opts out of MIME enforcement entirely.
+- The default MIME prefix is checked against the response's
+  `Content-Type` by the loader; the hook itself does not parse MIME.
+- Audio decoding remains the consumer's responsibility — the hook only
+  produces the Blob URL.