Initial Commit

packages/foundation/data/media/src/signatures/signatures.md

@@ -0,0 +1,71 @@
+# Signatures
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the magic-byte signature registry that powers byte-level detection.
+The module ships a frozen `BUILTIN_SIGNATURES` list covering common image
+(PNG, JPEG, GIF, BMP, WEBP, RIFF), video (MP4/MOV, WebM/MKV), and audio
+(MP3, FLAC, OGG) formats, plus a mutable `SignatureRegistry` class that
+lets downstream consumers add or remove entries without forking the
+package.
+
+## Features
+
+- Frozen built-in registry covering twelve canonical formats.
+- `SignatureRegistry` class with `register`, `unregister`, `list`,
+  `match`, and `detect` methods.
+- Per-entry `offset` so ftyp-style signatures (MP4) and RIFF chunk markers
+  (WebP) can match at non-zero positions.
+- Duplicate-label detection: `register` throws
+  `MEDIA.DUPLICATE_SIGNATURE` if a second entry uses the same label.
+- Byte validation: registration rejects empty byte arrays and non-byte
+  numbers with `MEDIA.INVALID_SIGNATURE`.
+- Process-wide `defaultSignatureRegistry` seeded with the built-ins.
+
+## Usage: Basic
+
+```ts
+import { defaultSignatureRegistry } from "@suaveplan/media";
+
+const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a]);
+const sig = defaultSignatureRegistry.match(png);
+console.log(sig?.label); // "PNG"
+```
+
+## Usage: Advanced
+
+```ts
+import { SignatureRegistry } from "@suaveplan/media";
+
+const reg = new SignatureRegistry();
+reg.register({
+    type: "image",
+    label: "AVIF",
+    bytes: [0x66, 0x74, 0x79, 0x70, 0x61, 0x76, 0x69, 0x66],
+    offset: 4,
+});
+const type = reg.detect(myBytes);
+```
+
+## API Reference
+
+- `BUILTIN_SIGNATURES` — readonly array of twelve canonical signatures.
+- `SignatureRegistry` — mutable registry class.
+  - `register(sig)` — add entry; throws on duplicate label / invalid bytes.
+  - `unregister(label)` — remove by label; returns whether removed.
+  - `list()` — frozen snapshot.
+  - `match(input)` — first matching `MediaSignature` or `null`.
+  - `detect(input)` — `MediaType`, defaulting to `"unknown"`.
+- `defaultSignatureRegistry` — process-wide default.
+
+## Implementation Notes
+
+`match` honours each signature's `offset` so non-zero-anchored formats
+work correctly. The built-in list orders longer / more-specific
+signatures before shorter ones (RIFF is listed after WEBP because the
+WEBP marker lives inside a RIFF container at offset 8). The registry's
+internal array is private so external mutation cannot break ordering.