first commit

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

@@ -0,0 +1,36 @@
+# signatures/model3d
+
+## Purpose
+
+Registers magic-byte signatures for 3D model file formats with the global signature registry. Covers formats used in CAD, game development, and 3D printing. Each signature is registered as a side effect of importing this module.
+
+## Features
+
+- glTF binary (`.glb`) — `glTF` magic + version 2
+- STL binary and ASCII (3D printing format)
+- FBX binary (`Kaydara FBX Binary` header)
+- Collada (`.dae`) — XML-based, identified by `<?xml` prolog
+- PLY (Stanford Polygon Library)
+
+## Usage
+
+```typescript
+import "@suaveplan/mime/detection/from-magic-bytes/signatures/model3d";
+import { detectFromMagicBytes } from "@suaveplan/mime/detection/from-magic-bytes/from-magic-bytes";
+
+// glTF binary magic: 67 6C 54 46
+const glbBytes = new Uint8Array([0x67, 0x6c, 0x54, 0x46, 0x02, 0x00, 0x00, 0x00]);
+console.log(detectFromMagicBytes(glbBytes)?.mime); // "model/gltf-binary"
+```
+
+## API Reference
+
+No exported functions. All signatures are registered via `registerSignature` side effects.
+
+## Implementation Notes
+
+STL binary files have no fixed magic sequence — they start with an 80-byte header of arbitrary text. The detection heuristic checks for the absence of the ASCII string `solid` at offset 0 (which would indicate ASCII STL) combined with a plausible triangle count in bytes 80–83. ASCII STL files are identified by the `solid` keyword at offset 0. The MIME type `model/stl` is returned for both binary and ASCII STL when detected.
+
+### Coverage
+
+The 3D-model signature set covers glTF binary (`glTF` magic at offset 0), USDZ (a ZIP container with a specific first-entry layout), FBX (both ASCII `; FBX` and binary `Kaydara FBX Binary  \0`), STL (ASCII vs binary are disambiguated by header-byte heuristics), OBJ (text-sniffed), 3MF, and DAE/Collada (XML with known root element). The binary FBX magic uses 20 bytes including two trailing null bytes and a SUB character — matching that full prefix avoids false positives on other tools that write `Kaydara`-prefixed files.