first commit

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

@@ -0,0 +1,38 @@
+# signatures/documents
+
+## Purpose
+
+Registers magic-byte signatures for document and data format files with the global signature registry. Covers office documents, structured data, e-books, and markup formats. Each signature is registered as a side effect of importing this module.
+
+## Features
+
+- PDF (`%PDF` header)
+- Microsoft Office legacy formats (DOC, XLS, PPT — OLE2 container `D0 CF 11 E0`)
+- EPUB (ZIP-based e-book container)
+- Rich Text Format (RTF)
+- SQLite database (`SQLite format 3`)
+- Apple Pages, Numbers, Keynote (ZIP-based, detected via content sniffing)
+- JSON lines and CBOR (RFC 7049) binary format
+- Protocol Buffers wire format heuristic
+
+## Usage
+
+```typescript
+import "@suaveplan/mime/detection/from-magic-bytes/signatures/documents";
+import { detectFromMagicBytes } from "@suaveplan/mime/detection/from-magic-bytes/from-magic-bytes";
+
+const pdfBytes = new Uint8Array([0x25, 0x50, 0x44, 0x46, 0x2d]); // "%PDF-"
+console.log(detectFromMagicBytes(pdfBytes)?.mime); // "application/pdf"
+```
+
+## API Reference
+
+No exported functions. All signatures are registered via `registerSignature` side effects.
+
+## Implementation Notes
+
+OLE2 Compound Document Format is the container for legacy Microsoft Office files (pre-2007 DOC/XLS/PPT). The magic bytes `D0 CF 11 E0` identify the OLE2 container but not the specific Office application — the detector returns `application/vnd.ms-office` as a generic fallback. Modern Office formats (DOCX, XLSX, PPTX) use the ZIP container and are handled in the archives signatures module.
+
+### Coverage
+
+The document signature set covers PDF (`%PDF`), Microsoft CFB-backed legacy Office (`D0 CF 11 E0 A1 B1 1A E1`), OOXML (`PK` with `[Content_Types].xml` entry — priority 105 so it beats plain ZIP), ODF, RTF (`{\\rtf`), PostScript (`%!PS`), EPUB (ZIP with `mimetype` = `application/epub+zip`), and MOBI/AZW. The 105 priority on container-based formats is critical: without it OOXML would match plain ZIP at 100 and lose granularity.