Initial Commit

packages/foundation/data/mime/src/detection/from-magic-bytes/from-magic-bytes.md

@@ -0,0 +1,86 @@
+# 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.