first commit

docs/foundation/data/media/src/detection/detection.md

@@ -0,0 +1,70 @@
+# Detection
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Byte-level and filename-level media type detection. The module pairs the
+pluggable `SignatureRegistry` from `signatures/` with the MIME database
+exposed by `@suaveplan/mime` so consumers can identify image, video, and
+audio artefacts whether they have the bytes, the filename, or both.
+
+## Features
+
+- `detectMediaType(input, opts?)` — magic-byte detection via the registry.
+- `detectSignature(input, opts?)` — return the matched `MediaSignature`
+  record, not just its `type`.
+- `detectMediaTypeFromName(filename, opts?)` — MIME-database lookup.
+- `inferMimeFromSignature(sig)` — canonical MIME for a matched signature
+  with a sane fallback when no signature matched.
+- `defaultMimeForType(type)` — coarse fallback when only the
+  category is known.
+- Counters and latency histograms emitted on every invocation.
+
+## Usage: Basic
+
+```ts
+import { detectMediaType } from "@suaveplan/media";
+
+const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d]);
+detectMediaType(png); // "image"
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    detectSignature,
+    inferMimeFromSignature,
+    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 sig = detectSignature(myBytes, { registry: reg });
+const mime = inferMimeFromSignature(sig); // canonical MIME
+```
+
+## API Reference
+
+- `DetectOptions` — `{ registry?, observability? }`.
+- `detectMediaType(input, opts?)` — `MediaType`.
+- `detectSignature(input, opts?)` — `MediaSignature | null`.
+- `detectMediaTypeFromName(filename, opts?)` — `MediaType`.
+- `inferMimeFromSignature(sig)` — canonical MIME string.
+- `defaultMimeForType(type)` — coarse fallback MIME.
+
+## Implementation Notes
+
+`detectMediaType` and `detectMediaTypeFromName` both record an
+`op_latency_ms` histogram entry in a `finally` block so the cost of a
+detection call is always measured, even when the registry throws. The
+filename pathway uses `@suaveplan/mime`'s `getMimeType` so the database
+behind detection stays in lock-step with the rest of the project.