Files

admin 9bf56a806b Move docs/ package mirror into document-navigator plugin

Relocate the ~6k-file docs tree from the repo root into
plugins/document-navigator/docs/ so the plugin is self-contained and
portable. docs/superpowers/ (specs and plans) stays at the repo root.

Moved via cp+rm rather than git mv because directory rename() fails with
EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the
identical-content files at commit time.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-05-30 01:10:00 +01:00

src

Move docs/ package mirror into document-navigator plugin

2026-05-30 01:10:00 +01:00

README.md

Move docs/ package mirror into document-navigator plugin

2026-05-30 01:10:00 +01:00

README.md

@suaveplan/mime - Structured MIME-type detection, parsing, and registry: magic-byte sniffing, RFC 7231 Content-Type parsing, IANA-sourced type database.

Summary

Structured MIME-type detection, parsing, and registry for the Suaveplan platform. Provides RFC 7231 Content-Type parsing, magic-byte file signature detection, charset sniffing, and a 150+ entry IANA-sourced type database — all in a zero-dependency, tree-shakeable package.

Documentation tree

sniff-bom — Detects character encoding from a Byte Order Mark (BOM) at the start of a binary buffer. BOM detection is the highest-c…
sniff-html-meta — Extracts a declared character encoding from an HTML <meta> tag by scanning the first 1,024 characters of an HTML docu…
sniff-xml-decl — Extracts the declared encoding from an XML or SVG document's processing instruction (`<?xml version="1.0" encoding="UTF…
content-type-equals — Provides two utility functions for comparing Content-Type values without caring about parameters: contentTypeEquals c…
format-content-type — Serializes a ParsedContentType object back into a standards-compliant Content-Type header string. Handles quoting o…
parse-content-type — Parses an RFC 7231 / RFC 9110 Content-Type header value into a structured ParsedContentType object. Handles quoted…
builtin-db — The built-in MIME type database for @suaveplan/mime. Contains over 150 MimeEntry records covering the most common w…
registry — The central in-memory MIME type database for @suaveplan/mime. Maintains two indexes over the built-in MimeEntry lis…
from-magic-bytes — (no submodules) - helpers — Low-level byte-inspection utilities used……
- archives — Registers magic-byte signatures for archive and compressed file formats with the global signature registry. Covers all…
- audio — Registers magic-byte signatures for audio formats with the global signature registry. Covers all major audio container…
- data — Registers magic-byte signatures for binary data and structured-data formats with the global signature registry. Covers…
- documents — Registers magic-byte signatures for document and data format files with the global signature registry. Covers office do…
- executables — Registers magic-byte signatures for executable binary formats with the global signature registry. Covers native executa…
- fonts — Registers magic-byte signatures for font file formats with the global signature registry. Covers all major web font and…
- images — Registers magic-byte signatures for image formats with the global signature registry. Covers all major raster and vecto…
- model3d — Registers magic-byte signatures for 3D model file formats with the global signature registry. Covers formats used in CA…
- video — Registers magic-byte signatures for video container formats with the global signature registry. Covers all major video…
- from-magic-bytes — (no submodules) - helpers — Low-level byte-inspection utilities used……
- helpers — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
- registry — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
detect — The unified MIME detection entry point for @suaveplan/mime. Merges evidence from three independent sources — magic by…
from-content-type — Detects the MIME type from a raw Content-Type header string. Parses the header using the full RFC 7231 parser and wra…
from-extension — Detects the MIME type from a file extension or full filename. Strips path components and leading dots, normalizes to lo…
from-stream-reader — Internal module providing the toAsyncIterable helper and the drainViaReader legacy fallback for ReadableStream so…
from-stream — Provides detectFromStream, which reads the first N bytes from any async byte source (ReadableStream<Uint8Array> or…
error-codes — Defines the stable numeric error-code registry for every error class in @suaveplan/mime. Each code is a non-overlappi…
- error-codes — Defines the stable numeric error-code registry for every error class in @suaveplan/mime. Each code is a non-overlappi…
insufficient-bytes-error — Thrown when a magic-byte detection operation receives fewer bytes than the minimum required by the signature. Carries b…
invalid-content-type-error — Thrown when a Content-Type header or media type string fails RFC 7231 validation. Carries the raw input string and op…
mime-error — The base error class for all @suaveplan/mime errors. Extends SuaveplanError from @suaveplan/error with the `MIME_…
parse-error — Thrown when a general parsing operation fails — for example, XML declaration parsing or BOM detection failures. Unlike…
unknown-mime-type-error — Thrown when a MIME type string is not found in the built-in database and no fallback is available. Carries the unrecogn…
unknown-signature-error — Thrown when a byte signature identifier is referenced but is not present in the signature registry. Used as a sentinel…
legacy — (no submodules)
- get-mime-type — (no submodules)
reverse — (no submodules)
- reverse — (no submodules)
telemetry — (no submodules)
- meters — (no submodules)

- helpers — Low-level byte-inspection utilities used……

archives — Registers magic-byte signatures for archive and compressed file formats with the global signature registry. Covers all…
audio — Registers magic-byte signatures for audio formats with the global signature registry. Covers all major audio container…
data — Registers magic-byte signatures for binary data and structured-data formats with the global signature registry. Covers…
documents — Registers magic-byte signatures for document and data format files with the global signature registry. Covers office do…
executables — Registers magic-byte signatures for executable binary formats with the global signature registry. Covers native executa…
fonts — Registers magic-byte signatures for font file formats with the global signature registry. Covers all major web font and…
images — Registers magic-byte signatures for image formats with the global signature registry. Covers all major raster and vecto…
model3d — Registers magic-byte signatures for 3D model file formats with the global signature registry. Covers formats used in CA…
video — Registers magic-byte signatures for video container formats with the global signature registry. Covers all major video…
from-magic-bytes — (no submodules)- helpers — Low-level byte-inspection utilities used……
helpers — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
registry — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
detect — The unified MIME detection entry point for @suaveplan/mime. Merges evidence from three independent sources — magic by…
from-content-type — Detects the MIME type from a raw Content-Type header string. Parses the header using the full RFC 7231 parser and wra…
from-extension — Detects the MIME type from a file extension or full filename. Strips path components and leading dots, normalizes to lo…
from-stream-reader — Internal module providing the toAsyncIterable helper and the drainViaReader legacy fallback for ReadableStream so…
from-stream — Provides detectFromStream, which reads the first N bytes from any async byte source (ReadableStream<Uint8Array> or…
insufficient-bytes-error — Thrown when a magic-byte detection operation receives fewer bytes than the minimum required by the signature. Carries b…
invalid-content-type-error — Thrown when a Content-Type header or media type string fails RFC 7231 validation. Carries the raw input string and op…
mime-error — The base error class for all @suaveplan/mime errors. Extends SuaveplanError from @suaveplan/error with the `MIME_…
parse-error — Thrown when a general parsing operation fails — for example, XML declaration parsing or BOM detection failures. Unlike…
unknown-mime-type-error — Thrown when a MIME type string is not found in the built-in database and no fallback is available. Carries the unrecogn…
unknown-signature-error — Thrown when a byte signature identifier is referenced but is not present in the signature registry. Used as a sentinel…
legacy — (no submodules)- get-mime-type — (no submodules)- reverse — (no submodules)- reverse — (no submodules)- telemetry — (no submodules)- meters — (no submodules)- error-codes — Defines the stable numeric error-code registry for every error class in @suaveplan/mime. Each code is a non-overlappi…
helpers — Low-level byte-inspection utilities used……
archives — Registers magic-byte signatures for archive and compressed file formats with the global signature registry. Covers all…
audio — Registers magic-byte signatures for audio formats with the global signature registry. Covers all major audio container…
data — Registers magic-byte signatures for binary data and structured-data formats with the global signature registry. Covers…
documents — Registers magic-byte signatures for document and data format files with the global signature registry. Covers office do…
executables — Registers magic-byte signatures for executable binary formats with the global signature registry. Covers native executa…
fonts — Registers magic-byte signatures for font file formats with the global signature registry. Covers all major web font and…
images — Registers magic-byte signatures for image formats with the global signature registry. Covers all major raster and vecto…
model3d — Registers magic-byte signatures for 3D model file formats with the global signature registry. Covers formats used in CA…
video — Registers magic-byte signatures for video container formats with the global signature registry. Covers all major video…
from-magic-bytes — (no submodules)- helpers — Low-level byte-inspection utilities used……
helpers — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
registry — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
detect — The unified MIME detection entry point for @suaveplan/mime. Merges evidence from three independent sources — magic by…
from-content-type — Detects the MIME type from a raw Content-Type header string. Parses the header using the full RFC 7231 parser and wra…
from-extension — Detects the MIME type from a file extension or full filename. Strips path components and leading dots, normalizes to lo…
from-stream-reader — Internal module providing the toAsyncIterable helper and the drainViaReader legacy fallback for ReadableStream so…
from-stream — Provides detectFromStream, which reads the first N bytes from any async byte source (ReadableStream<Uint8Array> or…
insufficient-bytes-error — Thrown when a magic-byte detection operation receives fewer bytes than the minimum required by the signature. Carries b…
invalid-content-type-error — Thrown when a Content-Type header or media type string fails RFC 7231 validation. Carries the raw input string and op…
mime-error — The base error class for all @suaveplan/mime errors. Extends SuaveplanError from @suaveplan/error with the `MIME_…
parse-error — Thrown when a general parsing operation fails — for example, XML declaration parsing or BOM detection failures. Unlike…
unknown-mime-type-error — Thrown when a MIME type string is not found in the built-in database and no fallback is available. Carries the unrecogn…
unknown-signature-error — Thrown when a byte signature identifier is referenced but is not present in the signature registry. Used as a sentinel…
legacy — (no submodules)- get-mime-type — (no submodules)- reverse — (no submodules)- reverse — (no submodules)- telemetry — (no submodules)- meters — (no submodules)- error-codes — Defines the stable numeric error-code registry for every error class in @suaveplan/mime. Each code is a non-overlappi…
helpers — Low-level byte-inspection utilities used…
archives — Registers magic-byte signatures for archive and compressed file formats with the global signature registry. Covers all…
audio — Registers magic-byte signatures for audio formats with the global signature registry. Covers all major audio container…
data — Registers magic-byte signatures for binary data and structured-data formats with the global signature registry. Covers…
documents — Registers magic-byte signatures for document and data format files with the global signature registry. Covers office do…
executables — Registers magic-byte signatures for executable binary formats with the global signature registry. Covers native executa…
fonts — Registers magic-byte signatures for font file formats with the global signature registry. Covers all major web font and…
images — Registers magic-byte signatures for image formats with the global signature registry. Covers all major raster and vecto…
model3d — Registers magic-byte signatures for 3D model file formats with the global signature registry. Covers formats used in CA…
video — Registers magic-byte signatures for video container formats with the global signature registry. Covers all major video…
from-magic-bytes — (no submodules)- helpers — Low-level byte-inspection utilities used…
helpers — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
registry — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
detect — The unified MIME detection entry point for @suaveplan/mime. Merges evidence from three independent sources — magic by…
from-content-type — Detects the MIME type from a raw Content-Type header string. Parses the header using the full RFC 7231 parser and wra…
from-extension — Detects the MIME type from a file extension or full filename. Strips path components and leading dots, normalizes to lo…
from-stream-reader — Internal module providing the toAsyncIterable helper and the drainViaReader legacy fallback for ReadableStream so…
from-stream — Provides detectFromStream, which reads the first N bytes from any async byte source (ReadableStream<Uint8Array> or…
insufficient-bytes-error — Thrown when a magic-byte detection operation receives fewer bytes than the minimum required by the signature. Carries b…
invalid-content-type-error — Thrown when a Content-Type header or media type string fails RFC 7231 validation. Carries the raw input string and op…
mime-error — The base error class for all @suaveplan/mime errors. Extends SuaveplanError from @suaveplan/error with the `MIME_…
parse-error — Thrown when a general parsing operation fails — for example, XML declaration parsing or BOM detection failures. Unlike…
unknown-mime-type-error — Thrown when a MIME type string is not found in the built-in database and no fallback is available. Carries the unrecogn…
unknown-signature-error — Thrown when a byte signature identifier is referenced but is not present in the signature registry. Used as a sentinel…
legacy — (no submodules)- get-mime-type — (no submodules)- reverse — (no submodules)- reverse — (no submodules)- telemetry — (no submodules)- meters — (no submodules)- error-codes — Defines the stable numeric error-code registry for every error class in @suaveplan/mime. Each code is a non-overlappi…
archives — Registers magic-byte signatures for archive and compressed file formats with the global signature registry. Covers all…
audio — Registers magic-byte signatures for audio formats with the global signature registry. Covers all major audio container…
data — Registers magic-byte signatures for binary data and structured-data formats with the global signature registry. Covers…
documents — Registers magic-byte signatures for document and data format files with the global signature registry. Covers office do…
executables — Registers magic-byte signatures for executable binary formats with the global signature registry. Covers native executa…
fonts — Registers magic-byte signatures for font file formats with the global signature registry. Covers all major web font and…
images — Registers magic-byte signatures for image formats with the global signature registry. Covers all major raster and vecto…
model3d — Registers magic-byte signatures for 3D model file formats with the global signature registry. Covers formats used in CA…
video — Registers magic-byte signatures for video container formats with the global signature registry. Covers all major video…
from-magic-bytes — (no submodules)- helpers — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
registry — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
detect — The unified MIME detection entry point for @suaveplan/mime. Merges evidence from three independent sources — magic by…
from-content-type — Detects the MIME type from a raw Content-Type header string. Parses the header using the full RFC 7231 parser and wra…
from-extension — Detects the MIME type from a file extension or full filename. Strips path components and leading dots, normalizes to lo…
from-stream-reader — Internal module providing the toAsyncIterable helper and the drainViaReader legacy fallback for ReadableStream so…
from-stream — Provides detectFromStream, which reads the first N bytes from any async byte source (ReadableStream<Uint8Array> or…
insufficient-bytes-error — Thrown when a magic-byte detection operation receives fewer bytes than the minimum required by the signature. Carries b…
invalid-content-type-error — Thrown when a Content-Type header or media type string fails RFC 7231 validation. Carries the raw input string and op…
mime-error — The base error class for all @suaveplan/mime errors. Extends SuaveplanError from @suaveplan/error with the `MIME_…
parse-error — Thrown when a general parsing operation fails — for example, XML declaration parsing or BOM detection failures. Unlike…
unknown-mime-type-error — Thrown when a MIME type string is not found in the built-in database and no fallback is available. Carries the unrecogn…
unknown-signature-error — Thrown when a byte signature identifier is referenced but is not present in the signature registry. Used as a sentinel…
legacy — (no submodules) - get-mime-type — (no submodules)- reverse — (no submodules) - reverse — (no submodules)- telemetry — (no submodules) - meters — (no submodules)- error-codes — Defines the stable numeric error-code registry for every error class in @suaveplan/mime. Each code is a non-overlappi…

Features

RFC 7231 Content-Type parsing — full quoted-string and OWS support
Magic-byte detection — 150+ signatures across images, audio, video, archives, documents, executables, and fonts
Stream detection — peek bytes from a ReadableStream or AsyncIterable without losing the original stream
Charset sniffing — BOM, HTML <meta> tag, and XML declaration detection
Multi-source confidence scoring — merge bytes + extension + Content-Type with agreement boost
Reverse lookup — MIME type → canonical file extension
OpenTelemetry metrics — optional OTel instrumentation
100% test coverage — every branch and statement verified

Installation

bun add @suaveplan/mime

Quick Start

import { detect } from "@suaveplan/mime";

// Multi-source detection with confidence scoring
const result = detect({
    bytes: fileBuffer,
    filename: "photo.jpg",
    contentType: "image/jpeg",
});
console.log(result.mime);       // "image/jpeg"
console.log(result.confidence); // 1.0 (all three sources agree)

Module Reference

Module	Description	Docs
`@suaveplan/mime`	Main entry: `detect()`, `parseContentType()`, `formatContentType()`	src/index.ts
`@suaveplan/mime/content-type`	RFC 7231 parser, formatter, equality/match utilities	parse-content-type.md
`@suaveplan/mime/detection/detect`	Unified multi-source detector	detect.md
`@suaveplan/mime/detection/from-stream`	Stream-based detection with head/tail replay	from-stream.md
`@suaveplan/mime/detection/from-magic-bytes`	Raw magic-byte detection API	from-magic-bytes.md
`@suaveplan/mime/charset/sniff-bom`	BOM detection from byte buffers	sniff-bom.md
`@suaveplan/mime/charset/sniff-html-meta`	HTML `<meta charset>` detection	sniff-html-meta.md
`@suaveplan/mime/charset/sniff-xml-decl`	XML encoding declaration detection	sniff-xml-decl.md
`@suaveplan/mime/db/registry`	MIME database: forward and reverse lookup	registry.md
`@suaveplan/mime/reverse`	MIME type → file extension reverse lookup	reverse.md
`@suaveplan/mime/errors`	Typed error classes	mime-error.md
`@suaveplan/mime/telemetry/meters`	Optional OTel metrics instrumentation	meters.md
`@suaveplan/mime/legacy`	`getMimeType()` compat shim	get-mime-type.md

API Examples

Content-Type Parsing

import { parseContentType, formatContentType } from "@suaveplan/mime/content-type";

const ct = parseContentType("text/html; charset=UTF-8; format=flowed");
console.log(ct.type);              // "text"
console.log(ct.subtype);           // "html"
console.log(ct.essence);           // "text/html"
console.log(ct.parameters.charset); // "utf-8" (lowercased)

console.log(formatContentType(ct)); // "text/html; charset=utf-8; format=flowed"

Magic-Byte Detection

import { detectFromMagicBytes } from "@suaveplan/mime/detection/from-magic-bytes/from-magic-bytes";

const pngBytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
const result = detectFromMagicBytes(pngBytes);
console.log(result?.mime);     // "image/png"
console.log(result?.priority); // 100

Stream Detection

import { detectFromStream } from "@suaveplan/mime/detection/from-stream";

const { mime, head, tail } = await detectFromStream(uploadStream);
console.log(mime); // e.g. "video/mp4"

// Replay the full stream (head + tail)
const chunks: Uint8Array[] = [head];
for await (const chunk of tail) chunks.push(chunk);

Charset Sniffing

import { sniffBom } from "@suaveplan/mime/charset/sniff-bom";
import { sniffHtmlMeta } from "@suaveplan/mime/charset/sniff-html-meta";

const bom = sniffBom(fileBytes);     // "utf-8" | "utf-16le" | null
const meta = sniffHtmlMeta(htmlText); // "iso-8859-1" | null

Error Handling

import { InvalidContentTypeError, UnknownMimeTypeError } from "@suaveplan/mime/errors";
import { parseContentType } from "@suaveplan/mime/content-type";

try {
    parseContentType("not valid");
} catch (err) {
    if (err instanceof InvalidContentTypeError) {
        console.error("Bad header:", err.context?.raw);
    }
}

Registering Custom Signatures

import { registerSignature } from "@suaveplan/mime/detection/from-magic-bytes/registry";

registerSignature({
    mime: "application/x-my-format",
    priority: 75,
    minBytes: 4,
    match: (bytes) =>
        bytes[0] === 0x4d && bytes[1] === 0x59 &&
        bytes[2] === 0x46 && bytes[3] === 0x4d,
});

Coverage

This package maintains 100% statement, branch, function, and line coverage — a requirement for Layer 0/1 foundation packages in Suaveplan.

License

MIT