first commit

docs/foundation/data/mime/src/detection/from-magic-bytes/signatures/archives.md

@@ -0,0 +1,39 @@
+# signatures/archives
+
+## Purpose
+
+Registers magic-byte signatures for archive and compressed file formats with the global signature registry. Covers all major compression and container formats used in file distribution and backup. Each signature is registered as a side effect of importing this module.
+
+## Features
+
+- ZIP, JAR, ODF, DOCX/PPTX/XLSX (all ZIP-based)
+- GZIP, BZIP2, XZ/7-Zip, LZMA
+- RAR (v4 and v5 signatures)
+- TAR (ustar header at offset 257)
+- ZSTD (Zstandard frame magic)
+- LZ4 frame magic
+- CPIO (binary and ASCII newc variants)
+- ISO 9660 CD image (CD001 at offset 32769)
+- BZ2 single-file bzip2
+
+## Usage
+
+```typescript
+import "@suaveplan/mime/detection/from-magic-bytes/signatures/archives";
+import { detectFromMagicBytes } from "@suaveplan/mime/detection/from-magic-bytes/from-magic-bytes";
+
+const gzipBytes = new Uint8Array([0x1f, 0x8b, 0x08]);
+console.log(detectFromMagicBytes(gzipBytes)?.mime); // "application/gzip"
+```
+
+## API Reference
+
+No exported functions. All signatures are registered via `registerSignature` side effects.
+
+## Implementation Notes
+
+ZIP-based formats (JAR, ODF, Office Open XML) share the PK signature but cannot be distinguished without inspecting the ZIP directory entries — the magic-byte detector returns `application/zip` generically for all ZIP files. TAR detection looks for the `ustar` ASCII string at offset 257, which requires at least 262 bytes; shorter buffers will not match. ISO 9660 detection at offset 32769 is impractical to test and is annotated to be excluded from coverage thresholds.
+
+### Coverage
+
+The archive signature set covers ZIP (`PK\x03\x04` and `PK\x05\x06` empty-archive variant), 7z (`37 7A BC AF 27 1C`), RAR (v4 and v5 magics), GZIP (`1F 8B`), BZIP2 (`BZh`), XZ, TAR (ustar octet at offset 257), and Z-standard. Priority 100 is the default; nested container formats such as OOXML that are technically ZIP files are detected at priority 105 in `documents.ts` so they win the tie.