# detection/from-magic-bytes/registry

## Purpose

The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-like access: `registerSignature` to add a matcher, `getSignatures` to read the sorted list, and `resetSignatures` to clear all entries (used in tests). This module is the single source of truth for the ordered list of matchers consumed by `detectFromMagicBytes`.

## Features

- `registerSignature(sig)` — add a new signature matcher; re-sorts registry by priority
- `getSignatures()` — returns the full registry array sorted by descending priority
- `resetSignatures()` — clears all registered signatures (test isolation only)
- Priority-ordered registry: higher priority signatures are checked first
- Thread-safe within a single JavaScript execution context (no async race conditions)

## Usage: Basic Example

```typescript
import {
    registerSignature,
    getSignatures,
} from "@suaveplan/mime/detection/from-magic-bytes/registry";

registerSignature({
    mime: "application/x-my-format",
    priority: 50,
    minBytes: 4,
    match: (bytes) => bytes[0] === 0x4d && bytes[1] === 0x59,
});

console.log(getSignatures().find(s => s.mime === "application/x-my-format"));
```

## Usage: Advanced Example

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

// Custom signature for a proprietary binary format
registerSignature({
    mime: "application/x-leveldb",
    priority: 75,
    minBytes: 8,
    match: (bytes) =>
        bytes[0] === 0xff &&
        bytes[1] === 0x06 &&
        bytes[2] === 0x00 &&
        bytes[3] === 0x00,
});

// Signature with a scan offset
registerSignature({
    mime: "image/x-xcf",
    priority: 80,
    minBytes: 9,
    match: (bytes) => {
        // "gimp xcf " at offset 0
        const magic = [0x67, 0x69, 0x6d, 0x70, 0x20, 0x78, 0x63, 0x66, 0x20];
        return magic.every((b, i) => bytes[i] === b);
    },
});
```

## API Reference

### `registerSignature(sig: Signature): void`

| Parameter | Type | Description |
|-----------|------|-------------|
| `sig.mime` | `string` | MIME type this signature identifies |
| `sig.priority` | `number` | Higher values are checked first (0–100 typical range) |
| `sig.minBytes` | `number` | Minimum bytes required to run the matcher |
| `sig.match` | `(bytes: Uint8Array) => boolean` | Byte-pattern predicate |

### `getSignatures(): Signature[]`

Returns the full sorted registry array. Do not mutate the returned array directly.

### `resetSignatures(): void`

Clears all signatures. Intended for test isolation only — not safe for production use.

## Implementation Notes

The registry maintains a sorted array rather than a priority queue for simplicity. `registerSignature` performs an in-place sort after insertion, which is O(n log n) but acceptable given that signatures are registered at module load time (once per process) and detection reads are O(n) anyway. The sort is stable in modern JavaScript engines, so signatures with equal priority retain their insertion order.