# detection/from-magic-bytes

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs --> - helpers — Low-level byte-inspection utilities used……
- [helpers](./helpers.md) — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
- [registry](./registry.md) — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
- helpers — Low-level byte-inspection utilities used……

- [helpers](./helpers.md) — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
- [registry](./registry.md) — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…

- helpers — Low-level byte-inspection utilities used……

- [helpers](./helpers.md) — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
- [registry](./registry.md) — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…

- helpers — Low-level byte-inspection utilities used…

- [helpers](./helpers.md) — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
- [registry](./registry.md) — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
- [helpers](./helpers.md) — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
- [registry](./registry.md) — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…

## Purpose

Implements magic-byte (file signature) detection for MIME types. Maintains a registry of byte-pattern matchers sorted by priority, and provides functions to find the best match, all matches, or reset the registry. Magic-byte detection has the highest confidence (0.95) in the unified `detect()` function because byte signatures are objective evidence that cannot be spoofed by file naming or HTTP headers.

## Features

- `detectFromMagicBytes(bytes)` — returns the highest-priority matching MIME type
- `detectAllFromMagicBytes(bytes)` — returns all matching MIME types sorted by priority
- Registry sorted by descending priority for deterministic match order
- Accepts any `Uint8Array` or `ArrayBuffer`-backed view
- Returns `undefined` (not throws) when no signature matches
- Supports minimum-bytes threshold per signature — skips signatures when the input is too short

## Usage: Basic Example

```typescript
import { detectFromMagicBytes } from "@suaveplan/mime/detection/from-magic-bytes/from-magic-bytes";

// PNG magic bytes: 89 50 4E 47 0D 0A 1A 0A
const pngBytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
const result = detectFromMagicBytes(pngBytes);
console.log(result?.mime);     // "image/png"
console.log(result?.priority); // 100
```

## Usage: Advanced Example

```typescript
import {
    detectFromMagicBytes,
    detectAllFromMagicBytes,
} from "@suaveplan/mime/detection/from-magic-bytes/from-magic-bytes";

// Detect all matching signatures (useful for ambiguous formats like MP4 variants)
const mp4Bytes = new Uint8Array([...]);
const allMatches = detectAllFromMagicBytes(mp4Bytes);
for (const match of allMatches) {
    console.log(match.mime, match.priority);
}

// Returns undefined for unrecognized byte sequences
const random = new Uint8Array([0x00, 0x01, 0x02, 0x03]);
console.log(detectFromMagicBytes(random)); // undefined
```

## API Reference

### `detectFromMagicBytes(bytes: Uint8Array): SignatureMatch | undefined`

| Parameter | Type | Description |
|-----------|------|-------------|
| `bytes` | `Uint8Array` | Byte buffer to inspect (first N bytes of a file). |

**Returns:** The highest-priority `SignatureMatch` (`mime`, `priority`), or `undefined`.

### `detectAllFromMagicBytes(bytes: Uint8Array): SignatureMatch[]`

Returns all matching signatures sorted by descending priority.

## Implementation Notes

The registry is sorted once whenever a new signature is registered, using a stable sort on `priority` (descending). Detection iterates the sorted array and returns the first match (for `detectFromMagicBytes`) or all matches (for `detectAllFromMagicBytes`). Signatures with a `minBytes` threshold are skipped when the input buffer is too short, enabling detection on partial reads without false negatives from truncated magic sequences.