omni-viewer-core 0.1.0

package/dist/registry/index.js

@@ -0,0 +1,348 @@
+// Viewer registry — pure detection data, no dynamic loading (DESIGN.md §7,
+// ADR 21). Adapters register the viewers they enable via their own explicit
+// import map. For the pilot the descriptor list is hand-maintained from the
+// viewer metadata exports; the build-time codegen replaces this when more
+// viewers land (ADR 37).
+import { asciiLower } from '../parsers/csv/index.js';
+import { sniffTextViewer } from './sniff.js';
+import { CONTAINER_SNIFF_BYTES, OFFICE_CONTAINER_BY_EXT, sniffContainer } from './container.js';
+/** Raster image signatures (docs/viewers/image.md §1). SVG has no fixed magic
+ *  and is handled by extension + text probe in the viewer, not here. */
+export const IMAGE_MAGIC_SIGNATURES = [
+    [{ offset: 0, bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] }], // PNG
+    [{ offset: 0, bytes: [0xff, 0xd8, 0xff] }], // JPEG
+    [{ offset: 0, bytes: [0x47, 0x49, 0x46, 0x38] }], // GIF87a/89a → 'GIF8'
+    [{ offset: 0, bytes: [0x42, 0x4d] }], // BMP → 'BM'
+    [
+        { offset: 0, bytes: [0x52, 0x49, 0x46, 0x46] }, // 'RIFF'
+        { offset: 8, bytes: [0x57, 0x45, 0x42, 0x50] } // 'WEBP'
+    ]
+];
+export const AVRO_MAGIC_SIGNATURES = [[
+        { offset: 0, bytes: [0x4f, 0x62, 0x6a, 0x01] }
+    ]];
+export const BAG_MAGIC_SIGNATURES = [[
+        { offset: 0, bytes: [0x23, 0x52, 0x4f, 0x53, 0x42, 0x41, 0x47, 0x20, 0x56, 0x32, 0x2e] }
+    ]];
+export const STP_MAGIC_SIGNATURES = [[
+        { offset: 0, bytes: [0x49, 0x53, 0x4f, 0x2d, 0x31, 0x30, 0x33, 0x30, 0x33, 0x2d, 0x32, 0x31, 0x3b] }
+    ]];
+export const DB3_MAGIC_SIGNATURES = [[
+        { offset: 0, bytes: [0x53, 0x51, 0x4c, 0x69, 0x74, 0x65, 0x20, 0x66, 0x6f, 0x72, 0x6d, 0x61, 0x74, 0x20, 0x33, 0x00] }
+    ]];
+export const BLF_MAGIC_SIGNATURES = [[{ offset: 0, bytes: [0x4c, 0x4f, 0x47, 0x47] }]];
+export const MF4_MAGIC_SIGNATURES = [[{ offset: 0, bytes: [0x4d, 0x44, 0x46, 0x20, 0x20, 0x20, 0x20, 0x20] }]];
+export const PCAP_MAGIC_SIGNATURES = [
+    [{ offset: 0, bytes: [0xa1, 0xb2, 0xc3, 0xd4] }], [{ offset: 0, bytes: [0xd4, 0xc3, 0xb2, 0xa1] }],
+    [{ offset: 0, bytes: [0xa1, 0xb2, 0x3c, 0x4d] }], [{ offset: 0, bytes: [0x4d, 0x3c, 0xb2, 0xa1] }]
+];
+export const PCAPNG_MAGIC_SIGNATURES = [[{ offset: 0, bytes: [0x0a, 0x0d, 0x0d, 0x0a] }]];
+export const PSD_MAGIC_SIGNATURES = [[{ offset: 0, bytes: [0x38, 0x42, 0x50, 0x53] }]];
+export const SHAPEFILE_MAGIC_SIGNATURES = [[{ offset: 0, bytes: [0x00, 0x00, 0x27, 0x0a] }]];
+/** Farthest byte any signature needs (WebP reaches offset 8 + 4 = 12). */
+const signatureReach = (sigs) => Math.max(0, ...sigs.flat().map((run) => run.offset + run.bytes.length));
+/**
+ * How many leading bytes an adapter should sniff for detection — the longest of
+ * the longest magicPrefix (PDF, 5B), the container signatures (OLE, 8B), and the
+ * image signatures (WebP, 12B). Stage-1 uses only these; container probing
+ * (stage 2) needs the whole file to read the central directory / CFB
+ * (docs/viewers/excel.md §5).
+ */
+export const REQUIRED_SNIFF_BYTES = Math.max(5, CONTAINER_SNIFF_BYTES, signatureReach(IMAGE_MAGIC_SIGNATURES), signatureReach(AVRO_MAGIC_SIGNATURES), signatureReach(BAG_MAGIC_SIGNATURES), signatureReach(STP_MAGIC_SIGNATURES), signatureReach(DB3_MAGIC_SIGNATURES), signatureReach(MF4_MAGIC_SIGNATURES));
+export const CSV_VIEWER_DESCRIPTOR = {
+    id: 'csv',
+    displayNameKey: 'csv.tableView',
+    extensions: ['csv', 'tsv'],
+    priority: 10,
+    requiredServices: [],
+    optionalServices: ['clipboard', 'save', 'writeback']
+};
+export const FALLBACK_VIEWER_DESCRIPTOR = {
+    id: 'fallback',
+    displayNameKey: 'fallback.title.text',
+    extensions: [],
+    priority: -1,
+    requiredServices: [],
+    optionalServices: []
+};
+export const PDF_VIEWER_DESCRIPTOR = {
+    id: 'pdf',
+    displayNameKey: 'pdf.title',
+    extensions: ['pdf'],
+    priority: 20,
+    magicPrefix: [0x25, 0x50, 0x44, 0x46, 0x2d], // '%PDF-'
+    requiredServices: [],
+    optionalServices: ['save', 'writeback', 'filePick']
+};
+export const PARQUET_MAGIC_SIGNATURES = [[{ offset: 0, bytes: [0x50, 0x41, 0x52, 0x31] }]];
+export const PARQUET_VIEWER_DESCRIPTOR = { id: 'parquet', displayNameKey: 'parquet.title', extensions: ['parquet'], priority: 20, magicSignatures: PARQUET_MAGIC_SIGNATURES, requiredServices: [], optionalServices: ['clipboard', 'save'] };
+export const AVRO_VIEWER_DESCRIPTOR = { id: 'avro', displayNameKey: 'avro.title', extensions: ['avro'], priority: 20, magicSignatures: AVRO_MAGIC_SIGNATURES, requiredServices: [], optionalServices: ['clipboard'] };
+export const BAG_VIEWER_DESCRIPTOR = { id: 'bag', displayNameKey: 'bag.title', extensions: ['bag'], priority: 20, magicSignatures: BAG_MAGIC_SIGNATURES, requiredServices: [], optionalServices: ['clipboard'] };
+export const STP_VIEWER_DESCRIPTOR = { id: 'stp', displayNameKey: 'stp.title', extensions: ['stp', 'step'], priority: 20, magicSignatures: STP_MAGIC_SIGNATURES, requiredServices: [], optionalServices: ['clipboard'] };
+export const DB3_VIEWER_DESCRIPTOR = { id: 'db3', displayNameKey: 'db3.title', extensions: ['db3'], priority: 20, magicSignatures: DB3_MAGIC_SIGNATURES, requiredServices: [], optionalServices: ['clipboard'] };
+export const REQIF_VIEWER_DESCRIPTOR = { id: 'reqif', displayNameKey: 'reqif.title', extensions: ['reqif'], priority: 20, requiredServices: [], optionalServices: ['clipboard'] };
+export const HDF5_MAGIC_PREFIX = [0x89, 0x48, 0x44, 0x46, 0x0d, 0x0a, 0x1a, 0x0a];
+// HDF5 permits a user block before the signature (offset 512, 1024, ...), so
+// named files are admitted by extension and validated by the parser. A leading
+// signature still enables extensionless content routing below.
+export const HDF5_VIEWER_DESCRIPTOR = { id: 'hdf5', displayNameKey: 'hdf5.title', extensions: ['h5', 'hdf5', 'he5'], priority: 20, requiredServices: [], optionalServices: ['clipboard'] };
+export const MAT_VIEWER_DESCRIPTOR = { id: 'mat', displayNameKey: 'mat.title', extensions: ['mat'], priority: 20, requiredServices: [], optionalServices: ['clipboard'] };
+export const AUDIO_VIEWER_DESCRIPTOR = { id: 'audio', displayNameKey: 'audio.title', extensions: ['mp3', 'wav', 'pcm', 'aiff', 'aif', 'aifc', 'amr', 'awb', 'ogg', 'flac', 'ac3', 'aac', 'm4a'], priority: 20, requiredServices: [], optionalServices: [] };
+export const VIDEO_VIEWER_DESCRIPTOR = { id: 'video', displayNameKey: 'video.title', extensions: ['mp4', 'mts', 'm2ts', 'avi', 'mov', 'wmv', 'flv', 'webm', 'mkv'], priority: 20, requiredServices: [], optionalServices: [] };
+export const DBC_VIEWER_DESCRIPTOR = { id: 'dbc', displayNameKey: 'dbc.title', extensions: ['dbc'], priority: 20, requiredServices: [], optionalServices: ['clipboard'] };
+export const ARXML_VIEWER_DESCRIPTOR = { id: 'arxml', displayNameKey: 'arxml.title', extensions: ['arxml'], priority: 20, requiredServices: [], optionalServices: ['clipboard'] };
+export const A2L_VIEWER_DESCRIPTOR = { id: 'a2l', displayNameKey: 'a2l.title', extensions: ['a2l'], priority: 20, requiredServices: [], optionalServices: ['clipboard'] };
+export const ASC_VIEWER_DESCRIPTOR = { id: 'asc', displayNameKey: 'asc.title', extensions: ['asc'], priority: 20, requiredServices: [], optionalServices: ['clipboard'] };
+export const BLF_VIEWER_DESCRIPTOR = { id: 'blf', displayNameKey: 'blf.title', extensions: ['blf'], priority: 20, magicSignatures: BLF_MAGIC_SIGNATURES, requiredServices: [], optionalServices: ['clipboard'] };
+export const MF4_VIEWER_DESCRIPTOR = { id: 'mf4', displayNameKey: 'mf4.title', extensions: ['mf4'], priority: 20, magicSignatures: MF4_MAGIC_SIGNATURES, requiredServices: [], optionalServices: ['clipboard'] };
+export const PCAP_VIEWER_DESCRIPTOR = { id: 'pcap', displayNameKey: 'pcap.title', extensions: ['pcap'], priority: 20, magicSignatures: PCAP_MAGIC_SIGNATURES, requiredServices: [], optionalServices: ['clipboard'] };
+export const PCAPNG_VIEWER_DESCRIPTOR = { id: 'pcapng', displayNameKey: 'pcapng.title', extensions: ['pcapng'], priority: 20, magicSignatures: PCAPNG_MAGIC_SIGNATURES, requiredServices: [], optionalServices: ['clipboard'] };
+export const MERMAID_VIEWER_DESCRIPTOR = { id: 'mermaid', displayNameKey: 'mermaid.title', extensions: ['mmd', 'mermaid'], priority: 20, requiredServices: [], optionalServices: [] };
+export const PLANTUML_VIEWER_DESCRIPTOR = { id: 'plantuml', displayNameKey: 'plantuml.title', extensions: ['puml', 'plantuml', 'iuml'], priority: 20, requiredServices: [], optionalServices: [] };
+export const SHAPEFILE_VIEWER_DESCRIPTOR = { id: 'shapefile', displayNameKey: 'shapefile.title', extensions: ['shp'], priority: 20, magicSignatures: SHAPEFILE_MAGIC_SIGNATURES, requiredServices: [], optionalServices: [] };
+export const PSD_VIEWER_DESCRIPTOR = { id: 'psd', displayNameKey: 'psd.title', extensions: ['psd'], priority: 20, magicSignatures: PSD_MAGIC_SIGNATURES, requiredServices: [], optionalServices: [] };
+export const JSON_VIEWER_DESCRIPTOR = {
+    id: 'json',
+    displayNameKey: 'json.treeView',
+    extensions: ['json'],
+    priority: 10,
+    // JSON has no signature; extensionless content sniffing is stage-2 (J17,
+    // docs/viewers/json.md) and not part of this synchronous descriptor.
+    requiredServices: [],
+    optionalServices: ['clipboard', 'save', 'writeback']
+};
+export const TOML_VIEWER_DESCRIPTOR = {
+    id: 'toml', displayNameKey: 'toml.treeView', extensions: ['toml'], priority: 10,
+    requiredServices: [], optionalServices: ['clipboard']
+};
+export const JSONL_VIEWER_DESCRIPTOR = {
+    id: 'jsonl', displayNameKey: 'jsonl.title', extensions: ['jsonl', 'ndjson', 'jsonlines'], priority: 10,
+    requiredServices: [], optionalServices: ['clipboard', 'save', 'writeback']
+};
+export const YAML_VIEWER_DESCRIPTOR = {
+    id: 'yaml', displayNameKey: 'yaml.treeView', extensions: ['yaml', 'yml'], priority: 10,
+    requiredServices: [], optionalServices: ['clipboard']
+};
+export const PROTO_VIEWER_DESCRIPTOR = {
+    id: 'proto', displayNameKey: 'proto.title', extensions: ['proto'], priority: 10,
+    requiredServices: [], optionalServices: ['clipboard']
+};
+/**
+ * Excel spans two containers (xlsx/xlsm are zip, xls is ole), so it has no
+ * single magicPrefix — the container is verified via OFFICE_CONTAINER_BY_EXT
+ * and, when ambiguous, probeContainer (docs/viewers/excel.md §5, X-감지).
+ */
+export const EXCEL_VIEWER_DESCRIPTOR = {
+    id: 'excel',
+    displayNameKey: 'excel.tableView',
+    extensions: ['xlsx', 'xlsm', 'xlsb', 'ods', 'xls'],
+    priority: 15,
+    requiredServices: [],
+    optionalServices: ['clipboard', 'save']
+};
+export const PPT_VIEWER_DESCRIPTOR = { id: 'ppt', displayNameKey: 'ppt.title', extensions: ['pptx', 'ppt'], priority: 15, requiredServices: [], optionalServices: [] };
+export const WORD_VIEWER_DESCRIPTOR = { id: 'word', displayNameKey: 'word.title', extensions: ['docx', 'doc'], priority: 15, requiredServices: [], optionalServices: ['print', 'navigation'] };
+export const HWP_VIEWER_DESCRIPTOR = { id: 'hwp', displayNameKey: 'hwp.title', extensions: ['hwp', 'hwpx'], priority: 15, requiredServices: [], optionalServices: [] };
+/**
+ * Image viewer detection metadata (docs/viewers/image.md §1). Background removal
+ * and sprite detection are optional host services (image.md I8), never
+ * requiredServices: gating them here would exclude the image viewer on platforms
+ * that don't provide them. SVG has no fixed magic — it is admitted by extension
+ * and the viewer's text probe (decode.ts).
+ */
+export const IMAGE_VIEWER_DESCRIPTOR = {
+    id: 'image',
+    displayNameKey: 'image.title',
+    extensions: ['jpg', 'jpeg', 'png', 'gif', 'bmp', 'webp', 'svg'],
+    priority: 15,
+    magicSignatures: IMAGE_MAGIC_SIGNATURES,
+    requiredServices: [],
+    optionalServices: ['save', 'writeback', 'backgroundRemoval', 'spriteDetection']
+};
+export const MARKDOWN_VIEWER_DESCRIPTOR = {
+    id: 'markdown', displayNameKey: 'markdown.title',
+    extensions: ['md', 'markdown', 'mdown', 'mkdn', 'mkd'], priority: 10,
+    requiredServices: [], optionalServices: ['clipboard', 'navigation', 'documentAssets', 'writeback']
+};
+export const ARCHIVE_MAGIC_SIGNATURES = [
+    [{ offset: 0, bytes: [0x50, 0x4b, 0x03, 0x04] }], [{ offset: 0, bytes: [0x50, 0x4b, 0x05, 0x06] }],
+    [{ offset: 257, bytes: [0x75, 0x73, 0x74, 0x61, 0x72] }], [{ offset: 0, bytes: [0x1f, 0x8b] }],
+    [{ offset: 0, bytes: [0x42, 0x5a, 0x68] }], [{ offset: 0, bytes: [0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00] }],
+    [{ offset: 0, bytes: [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c] }], [{ offset: 0, bytes: [0x52, 0x61, 0x72, 0x21, 0x1a, 0x07, 0x00] }], [{ offset: 0, bytes: [0x52, 0x61, 0x72, 0x21, 0x1a, 0x07, 0x01, 0x00] }]
+];
+/** Archive is intentionally lower priority than Office container viewers. */
+export const ARCHIVE_VIEWER_DESCRIPTOR = {
+    id: 'archive', displayNameKey: 'archive.title',
+    extensions: ['zip', 'jar', 'apk', 'tar', 'tgz', 'tar.gz', 'tbz', 'tbz2', 'tar.bz2', 'txz', 'tar.xz', 'gz', 'bz2', 'xz', '7z', 'rar', 'dmg'],
+    priority: 5, magicSignatures: ARCHIVE_MAGIC_SIGNATURES, requiredServices: [], optionalServices: ['save']
+};
+export const CORE_VIEWER_DESCRIPTORS = [
+    PDF_VIEWER_DESCRIPTOR,
+    AUDIO_VIEWER_DESCRIPTOR,
+    VIDEO_VIEWER_DESCRIPTOR,
+    DBC_VIEWER_DESCRIPTOR,
+    ARXML_VIEWER_DESCRIPTOR,
+    A2L_VIEWER_DESCRIPTOR,
+    ASC_VIEWER_DESCRIPTOR,
+    BLF_VIEWER_DESCRIPTOR,
+    MF4_VIEWER_DESCRIPTOR,
+    PCAP_VIEWER_DESCRIPTOR,
+    PCAPNG_VIEWER_DESCRIPTOR,
+    MERMAID_VIEWER_DESCRIPTOR,
+    PLANTUML_VIEWER_DESCRIPTOR,
+    SHAPEFILE_VIEWER_DESCRIPTOR,
+    PSD_VIEWER_DESCRIPTOR,
+    PARQUET_VIEWER_DESCRIPTOR,
+    AVRO_VIEWER_DESCRIPTOR,
+    BAG_VIEWER_DESCRIPTOR,
+    STP_VIEWER_DESCRIPTOR,
+    DB3_VIEWER_DESCRIPTOR,
+    REQIF_VIEWER_DESCRIPTOR,
+    HDF5_VIEWER_DESCRIPTOR,
+    MAT_VIEWER_DESCRIPTOR,
+    PPT_VIEWER_DESCRIPTOR,
+    WORD_VIEWER_DESCRIPTOR,
+    HWP_VIEWER_DESCRIPTOR,
+    EXCEL_VIEWER_DESCRIPTOR,
+    IMAGE_VIEWER_DESCRIPTOR,
+    MARKDOWN_VIEWER_DESCRIPTOR,
+    ARCHIVE_VIEWER_DESCRIPTOR,
+    CSV_VIEWER_DESCRIPTOR,
+    JSON_VIEWER_DESCRIPTOR,
+    TOML_VIEWER_DESCRIPTOR,
+    JSONL_VIEWER_DESCRIPTOR,
+    YAML_VIEWER_DESCRIPTOR,
+    PROTO_VIEWER_DESCRIPTOR,
+    FALLBACK_VIEWER_DESCRIPTOR
+];
+export { looksLikeJsonDocument, looksLikeJsonl, looksLikeProto, sniffTextViewer } from './sniff.js';
+export { CONTAINER_SNIFF_BYTES, OFFICE_CONTAINER_BY_EXT, OLE_MAGIC, ZIP_MAGIC, sniffContainer } from './container.js';
+export { probeContainer } from './probe.js';
+/**
+ * Detection (DESIGN.md §7): ASCII-lowercased extension matching with priority
+ * tie-breaking (stage 1). When no extension matches and a text sample is
+ * provided, content sniffing (J17, 부록 B-6) classifies signature-less text
+ * formats — the extension is always trusted first (§7 point 3).
+ *
+ * Container-format viewers (excel; later word/ppt/hwpx) share zip/ole
+ * signatures, so stage-1 verifies a trusted office extension against the actual
+ * bytes: a match confirms it, a contradicting container (or a container with no
+ * matching extension) returns 'ambiguous-container' for the caller to resolve
+ * with probeContainer (stage 2, docs/viewers/excel.md §5). Services the host
+ * cannot provide exclude a viewer whose requiredServices demand them.
+ */
+export function detectViewer(fileName, availableServices = new Set(), descriptors = CORE_VIEWER_DESCRIPTORS, sniffBytes, sniffText) {
+    const lower = asciiLower(fileName);
+    const magicMatches = (d) => {
+        // No sniff bytes → trust the extension (offline-friendly, stage-1).
+        if (!sniffBytes)
+            return true;
+        if (d.magicPrefix) {
+            if (sniffBytes.byteLength < d.magicPrefix.length)
+                return false;
+            if (!d.magicPrefix.every((byte, i) => sniffBytes[i] === byte))
+                return false;
+        }
+        if (d.magicSignatures) {
+            const runMatches = (run) => sniffBytes.byteLength >= run.offset + run.bytes.length &&
+                run.bytes.every((byte, i) => sniffBytes[run.offset + i] === byte);
+            if (!d.magicSignatures.some((sig) => sig.every(runMatches)))
+                return false;
+        }
+        return true;
+    };
+    const servicesMet = (d) => d.requiredServices.every((s) => availableServices.has(s));
+    const container = sniffBytes ? sniffContainer(sniffBytes) : null;
+    const candidates = descriptors
+        .map((d) => ({ d, ext: d.extensions.find((ext) => lower.endsWith(`.${ext}`)) }))
+        .filter((c) => c.ext !== undefined)
+        .filter((c) => servicesMet(c.d))
+        // DMG has a tail signature, checked by its decoder; it cannot be
+        // represented by leading-byte magic matching.
+        .filter((c) => c.d.id === 'archive' ? archiveMagicMatches(c.ext, sniffBytes) : magicMatches(c.d))
+        .sort((a, b) => b.d.priority - a.d.priority);
+    const winner = candidates[0];
+    if (winner) {
+        const expected = OFFICE_CONTAINER_BY_EXT[winner.ext];
+        // A trusted office extension whose bytes are a *different* container is
+        // a contradiction (§7-3) — hand off to stage-2 probing. Non-container
+        // or unreadable bytes fall back to trusting the extension (offline-
+        // friendly; the parser reports invalid-format if it truly isn't one).
+        if (expected && container && container !== expected) {
+            return { viewerId: 'fallback', matchedBy: 'ambiguous-container', container };
+        }
+        return { viewerId: winner.d.id, matchedBy: 'extension' };
+    }
+    // No extension match. Container bytes are ambiguous → probe decides.
+    if (container) {
+        return { viewerId: 'fallback', matchedBy: 'ambiguous-container', container };
+    }
+    if (sniffBytes && HDF5_MAGIC_PREFIX.every((byte, index) => sniffBytes[index] === byte)) {
+        const hdf5 = descriptors.find(d => d.id === 'hdf5');
+        if (hdf5 && servicesMet(hdf5))
+            return { viewerId: 'hdf5', matchedBy: 'content' };
+    }
+    if (sniffBytes && looksLikeClassicMat(sniffBytes)) {
+        const mat = descriptors.find(d => d.id === 'mat');
+        if (mat && servicesMet(mat))
+            return { viewerId: 'mat', matchedBy: 'content' };
+    }
+    if (sniffBytes) {
+        const unambiguous = descriptors.find(d => ['avro', 'bag', 'stp', 'db3', 'blf', 'mf4', 'pcap', 'pcapng', 'shapefile', 'psd'].includes(d.id) && servicesMet(d) && magicMatches(d));
+        if (unambiguous)
+            return { viewerId: unambiguous.id, matchedBy: 'content' };
+    }
+    // Non-ZIP archive formats have unambiguous leading magic. ZIP stays on the
+    // container-probe path above so Office/HWPX gets first refusal.
+    if (sniffBytes && !ARCHIVE_VIEWER_DESCRIPTOR.extensions.some(ext => lower.endsWith(`.${ext}`)) && ARCHIVE_MAGIC_SIGNATURES.slice(2).some(sig => sig.every(run => run.bytes.every((b, i) => sniffBytes[run.offset + i] === b)))) {
+        const archive = descriptors.find(d => d.id === 'archive');
+        if (archive && servicesMet(archive))
+            return { viewerId: 'archive', matchedBy: 'content' };
+    }
+    // Stage 2 (text content sniffing) — only when the extension gave no match.
+    if (sniffText !== undefined) {
+        const sniffedId = sniffTextViewer(sniffText);
+        if (sniffedId) {
+            const d = descriptors.find((x) => x.id === sniffedId);
+            if (d && servicesMet(d))
+                return { viewerId: d.id, matchedBy: 'content' };
+        }
+    }
+    return { viewerId: 'fallback', matchedBy: 'fallback' };
+}
+function looksLikeClassicMat(bytes) {
+    if (bytes.length < 19)
+        return false;
+    let header = '';
+    for (let i = 0; i < Math.min(bytes.length, 116); i++)
+        header += String.fromCharCode(bytes[i]);
+    return /^MATLAB\s+(?:5\.0|7\.)\s+MAT-file/i.test(header);
+}
+function archiveMagicMatches(ext, bytes) {
+    if (!bytes)
+        return true;
+    const starts = (...magic) => magic.every((x, i) => bytes[i] === x);
+    const zip = starts(0x50, 0x4b, 0x03, 0x04) || starts(0x50, 0x4b, 0x05, 0x06);
+    const tar = bytes.length >= 262 && [0x75, 0x73, 0x74, 0x61, 0x72].every((x, i) => bytes[257 + i] === x);
+    const gzip = starts(0x1f, 0x8b), bzip = starts(0x42, 0x5a, 0x68), xz = starts(0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00), seven = starts(0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c), rar = starts(0x52, 0x61, 0x72, 0x21, 0x1a, 0x07);
+    // DMG has no leading magic. A standard sniff contains only the head of
+    // the file, so the registry must trust its extension; parseArchive owns
+    // validation of the `koly` signature in the final 512-byte trailer.
+    if (ext === 'dmg')
+        return true;
+    if (['zip', 'jar', 'apk'].includes(ext))
+        return zip;
+    if (ext === 'tar')
+        return tar;
+    if (['tgz', 'tar.gz', 'gz'].includes(ext))
+        return gzip;
+    if (['tbz', 'tbz2', 'tar.bz2', 'bz2'].includes(ext))
+        return bzip;
+    if (['txz', 'tar.xz', 'xz'].includes(ext))
+        return xz;
+    if (ext === '7z')
+        return seven;
+    if (ext === 'rar')
+        return rar;
+    return false;
+}

package/dist/registry/probe.d.ts

@@ -0,0 +1,3 @@
+import type { ParseOptions } from '../parsers/types.js';
+import type { ContainerKind } from './container.js';
+export declare function probeContainer(input: Uint8Array, container: ContainerKind, options?: ParseOptions): Promise<string | null>;

package/dist/registry/probe.js

@@ -0,0 +1,177 @@
+// Stage-2 container probe (DESIGN.md §7-3·ADR 16, docs/viewers/excel.md §5).
+// Given bytes already known to be a zip/ole container (sniffContainer), look
+// *inside* to decide which viewer holds it. Dependency-free and defensive —
+// any structural anomaly returns null (→ fallback), never throws, so this can
+// run before any heavy parser dependency is loaded.
+/** Default cap on entries/directory records a probe will scan. */
+const DEFAULT_PROBE_ENTRY_CAP = 4096;
+export async function probeContainer(input, container, options = {}) {
+    // Async signature for contract symmetry (§5) and future worker/streaming;
+    // the current implementations are synchronous scans over an in-memory view.
+    if (options.signal?.aborted)
+        return null;
+    return container === 'zip' ? probeZip(input, options) : probeOle(input, options);
+}
+// ─── ZIP (OOXML / ODF) ────────────────────────────────────────────────────
+// Parse the End Of Central Directory, then walk the central directory file
+// headers collecting entry names. OOXML members live under `xl/`, `word/`,
+// `ppt/`; ODF carries a `mimetype` member; a bare zip/jar matches none.
+const EOCD_SIG = 0x06054b50; // PK\x05\x06 (little-endian uint32)
+const CDFH_SIG = 0x02014b50; // PK\x01\x02
+function probeZip(input, options) {
+    const view = new DataView(input.buffer, input.byteOffset, input.byteLength);
+    const eocd = findEocd(view);
+    if (eocd < 0)
+        return null;
+    const entryCount = view.getUint16(eocd + 10, true);
+    const cdOffset = view.getUint32(eocd + 16, true);
+    const cap = Math.min(entryCount, options.limits?.maxEntries ?? DEFAULT_PROBE_ENTRY_CAP);
+    let pos = cdOffset;
+    for (let i = 0; i < cap; i++) {
+        if (options.signal?.aborted)
+            return null;
+        if (pos + 46 > view.byteLength)
+            break;
+        if (view.getUint32(pos, true) !== CDFH_SIG)
+            break;
+        const nameLen = view.getUint16(pos + 28, true);
+        const extraLen = view.getUint16(pos + 30, true);
+        const commentLen = view.getUint16(pos + 32, true);
+        const nameStart = pos + 46;
+        if (nameStart + nameLen > view.byteLength)
+            break;
+        const name = asciiName(input, nameStart, nameLen);
+        // OOXML (xlsx/xlsm/xlsb, docx, pptx) route by member-path prefix.
+        if (name.startsWith('xl/'))
+            return 'excel';
+        if (name.startsWith('word/'))
+            return 'word';
+        if (name.startsWith('ppt/'))
+            return 'ppt';
+        if (name.startsWith('Contents/') || name === 'content.hpf')
+            return 'hwp';
+        // ODF (.ods/.odt/.odp) — the stored `mimetype` member carries the type.
+        if (name === 'mimetype') {
+            const localOffset = view.getUint32(pos + 42, true);
+            const storedSize = view.getUint32(pos + 20, true);
+            const mimetype = readStoredEntry(input, view, localOffset, storedSize);
+            if (mimetype.trim() === 'application/hwp+zip')
+                return 'hwp';
+            if (mimetype.includes('spreadsheet'))
+                return 'excel';
+            if (mimetype.includes('text') || mimetype.includes('presentation'))
+                return null;
+        }
+        pos = nameStart + nameLen + extraLen + commentLen;
+    }
+    // OOXML content-types with no recognized part prefix, or a plain zip/jar.
+    return null;
+}
+/** Scan backwards for the EOCD signature (record is 22 bytes + comment). */
+function findEocd(view) {
+    const min = Math.max(0, view.byteLength - (22 + 0xffff));
+    for (let pos = view.byteLength - 22; pos >= min; pos--) {
+        if (view.getUint32(pos, true) === EOCD_SIG)
+            return pos;
+    }
+    return -1;
+}
+function asciiName(bytes, start, len) {
+    let out = '';
+    for (let i = 0; i < len; i++) {
+        out += String.fromCharCode(bytes[start + i]);
+    }
+    return out;
+}
+const LFH_SIG = 0x04034b50; // PK\x03\x04 (local file header)
+/** Read a STORED (uncompressed) entry's bytes as ASCII — used for the ODF
+ *  `mimetype` member, which spec-mandates be the first, stored entry. */
+function readStoredEntry(bytes, view, localOffset, size) {
+    if (localOffset < 0 || localOffset + 30 > view.byteLength)
+        return '';
+    if (view.getUint32(localOffset, true) !== LFH_SIG)
+        return '';
+    const nameLen = view.getUint16(localOffset + 26, true);
+    const extraLen = view.getUint16(localOffset + 28, true);
+    const dataStart = localOffset + 30 + nameLen + extraLen;
+    const end = Math.min(dataStart + size, view.byteLength);
+    if (dataStart >= end)
+        return '';
+    return asciiName(bytes, dataStart, end - dataStart);
+}
+// ─── OLE / CFB (legacy Office) ──────────────────────────────────────────────
+// Parse the Compound File header, follow the directory sector chain via the
+// FAT, and read directory entry names. Excel BIFF workbooks carry a `Workbook`
+// (BIFF8) or `Book` (BIFF5) stream.
+const CFB_ENDOFCHAIN = 0xfffffffe;
+const CFB_FREESECT = 0xffffffff;
+function probeOle(input, options) {
+    if (input.byteLength < 512)
+        return null;
+    const view = new DataView(input.buffer, input.byteOffset, input.byteLength);
+    const sectorShift = view.getUint16(30, true);
+    const sectorSize = 1 << sectorShift;
+    if (sectorSize !== 512 && sectorSize !== 4096)
+        return null;
+    const numFatSectors = view.getUint32(44, true);
+    const dirStart = view.getUint32(48, true);
+    const sectorOffset = (sid) => (sid + 1) * sectorSize;
+    const readU32 = (off) => off + 4 <= view.byteLength ? view.getUint32(off, true) : CFB_ENDOFCHAIN;
+    // Build the FAT from the header DIFAT (first 109 entries). Enough to follow
+    // the directory chain in typical office files; DIFAT-extension sectors are
+    // out of scope for a probe (returns null if the chain can't be followed).
+    const fat = [];
+    const fatSectorCount = Math.min(numFatSectors, 109);
+    for (let i = 0; i < fatSectorCount; i++) {
+        const fatSid = view.getUint32(76 + i * 4, true);
+        if (fatSid === CFB_FREESECT || fatSid === CFB_ENDOFCHAIN)
+            continue;
+        const base = sectorOffset(fatSid);
+        if (base + sectorSize > view.byteLength)
+            break;
+        for (let j = 0; j < sectorSize; j += 4)
+            fat.push(readU32(base + j));
+    }
+    if (fat.length === 0)
+        return null;
+    const decoder = new TextDecoder('utf-16le');
+    const cap = options.limits?.maxEntries ?? DEFAULT_PROBE_ENTRY_CAP;
+    let sid = dirStart;
+    let scanned = 0;
+    const seen = new Set();
+    let hasHwpFileHeader = false;
+    let hasHwpBodyText = false;
+    while (sid !== CFB_ENDOFCHAIN && sid !== CFB_FREESECT && scanned < cap) {
+        if (options.signal?.aborted)
+            return null;
+        if (sid < 0 || sid >= fat.length || seen.has(sid))
+            break; // out of range / cycle
+        seen.add(sid);
+        const base = sectorOffset(sid);
+        if (base + sectorSize > view.byteLength)
+            break;
+        for (let off = base; off + 128 <= base + sectorSize; off += 128) {
+            if (scanned++ >= cap)
+                break;
+            const nameLen = view.getUint16(off + 64, true);
+            const objType = view.getUint8(off + 66);
+            if (objType !== 1 /* storage */ && objType !== 2 /* stream */)
+                continue;
+            if (nameLen < 4 || nameLen > 64)
+                continue;
+            const name = decoder.decode(input.subarray(off, off + nameLen - 2));
+            if (objType === 2 && (name === 'Workbook' || name === 'Book'))
+                return 'excel';
+            if (objType === 2 && name === 'WordDocument')
+                return 'word';
+            if (objType === 2 && name === 'PowerPoint Document')
+                return 'ppt';
+            if (objType === 2 && name === 'FileHeader')
+                hasHwpFileHeader = true;
+            if (objType === 1 && name === 'BodyText')
+                hasHwpBodyText = true;
+        }
+        sid = fat[sid] ?? CFB_ENDOFCHAIN;
+    }
+    return hasHwpFileHeader && hasHwpBodyText ? 'hwp' : null;
+}

package/dist/registry/sniff.d.ts

@@ -0,0 +1,17 @@
+/** True if `text` parses cleanly as a single JSON object or array. */
+export declare function looksLikeJsonDocument(text: string): boolean;
+/**
+ * True if `text` looks like line-delimited JSON: at least two non-blank lines
+ * where each of the first ten parses to a JSON object or array. Blank lines are
+ * ignored so a trailing newline does not disqualify the file.
+ */
+export declare function looksLikeJsonl(text: string): boolean;
+/** Conservative Protocol Buffer schema detection for extensionless text. */
+export declare function looksLikeProto(text: string): boolean;
+/**
+ * Classify a text sample to a viewer id by content (JSONL is checked before
+ * JSON — 부록 B-6). Returns null when nothing matches. JSONL wins over JSON for
+ * multi-line object streams so a `{…}\n{…}` file is never mis-claimed as JSON;
+ * if no jsonl viewer is registered the caller falls through to fallback.
+ */
+export declare function sniffTextViewer(text: string): 'jsonl' | 'json' | 'proto' | null;

package/dist/registry/sniff.js

@@ -0,0 +1,57 @@
+// Content sniffing for signature-less text formats (J17, docs/viewers/json.md
+// 부록 B-6). JSON has no magic bytes, so extensionless JSON is detected by
+// parsing a content sample. Deterministic: uses the core JSON parser (never
+// JSON.parse, ADR 41), so the boolean is identical across engines. The
+// legacy platforms (vscode/obsidian/chrome) sniff the same way — dropping this
+// would regress them for extensionless files.
+import { parseJson } from '../parsers/json/index.js';
+/** True if `text` parses cleanly as a single JSON object or array. */
+export function looksLikeJsonDocument(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith('{') && !trimmed.startsWith('['))
+        return false;
+    const { result } = parseJson(trimmed);
+    if (result.status !== 'ok')
+        return false;
+    const kind = result.document.root.kind;
+    return kind === 'object' || kind === 'array';
+}
+/**
+ * True if `text` looks like line-delimited JSON: at least two non-blank lines
+ * where each of the first ten parses to a JSON object or array. Blank lines are
+ * ignored so a trailing newline does not disqualify the file.
+ */
+export function looksLikeJsonl(text) {
+    const lines = text.split(/\r\n|\r|\n/).filter((line) => line.trim().length > 0);
+    if (lines.length < 2)
+        return false;
+    return lines.slice(0, 10).every((line) => {
+        const { result } = parseJson(line);
+        if (result.status !== 'ok')
+            return false;
+        const kind = result.document.root.kind;
+        return kind === 'object' || kind === 'array';
+    });
+}
+/** Conservative Protocol Buffer schema detection for extensionless text. */
+export function looksLikeProto(text) {
+    const sample = text.slice(0, 64 * 1024).replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+    if (/^\s*syntax\s*=\s*["']proto[23]["']\s*;/m.test(sample))
+        return true;
+    return /^\s*(?:package\s+[\w.]+\s*;\s*)?(?:import\s+(?:(?:public|weak)\s+)?["'][^"']+["']\s*;\s*)*(?:message|enum|service)\s+[A-Za-z_]\w*\s*\{/m.test(sample);
+}
+/**
+ * Classify a text sample to a viewer id by content (JSONL is checked before
+ * JSON — 부록 B-6). Returns null when nothing matches. JSONL wins over JSON for
+ * multi-line object streams so a `{…}\n{…}` file is never mis-claimed as JSON;
+ * if no jsonl viewer is registered the caller falls through to fallback.
+ */
+export function sniffTextViewer(text) {
+    if (looksLikeJsonl(text))
+        return 'jsonl';
+    if (looksLikeJsonDocument(text))
+        return 'json';
+    if (looksLikeProto(text))
+        return 'proto';
+    return null;
+}

package/dist/styles/archive.css

@@ -0,0 +1,10 @@
+
+.omni-viewer--archive{all:initial}.omni-viewer--archive :where(header,section,aside,div,h1,h2,p,span,label,input,table,thead,tbody,tr,th,td,pre){all:revert}
+:host,.omni-viewer--archive{display:block;min-height:100%;box-sizing:border-box;color:var(--omni-fg,#d4d4d4);background:radial-gradient(circle at top left,color-mix(in srgb,var(--omni-accent,#d97706) 14%,transparent),transparent 28%),var(--omni-bg,#1e1e1e);font:13px var(--omni-font,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif)}
+.omni-viewer--archive *{box-sizing:border-box}.omni-viewer--archive{padding:28px 20px 40px}.omni-archive__hero,.omni-archive__controls,.omni-archive__stats,.omni-archive__table-wrap,.omni-archive__preview-panel{background:var(--omni-bg-secondary,#252526);border:1px solid var(--omni-border,#3c3c3c);border-radius:18px;box-shadow:0 20px 40px rgba(0,0,0,.12)}
+.omni-archive__hero{display:flex;justify-content:space-between;gap:16px;padding:24px;align-items:flex-start}.omni-archive__eyebrow{font-size:12px;letter-spacing:.18em;text-transform:uppercase;color:var(--omni-accent,#d97706);font-weight:700}.omni-archive__hero h1{margin:8px 0 6px;font-size:clamp(26px,4vw,40px);line-height:1.1}.omni-archive__subtitle,.omni-archive__preview-meta{color:var(--omni-muted-fg,#9d9d9d);line-height:1.5}.omni-archive__pills{display:flex;gap:10px;flex-wrap:wrap;justify-content:flex-end}.omni-archive__pill{padding:10px 14px;border-radius:999px;background:color-mix(in srgb,var(--omni-accent,#d97706) 16%,transparent);border:1px solid color-mix(in srgb,var(--omni-accent,#d97706) 35%,transparent);font-weight:600;white-space:nowrap}
+.omni-archive__controls,.omni-archive__stats,.omni-archive__workspace{margin-top:16px}.omni-archive__controls{padding:16px}.omni-archive__search-label{display:block;font-weight:600}.omni-archive__search{display:block;width:100%;margin-top:8px;padding:12px 14px;border-radius:12px;border:1px solid var(--omni-border,#3c3c3c);background:var(--omni-input-bg,#3c3c3c);color:var(--omni-fg,#d4d4d4);font:inherit}.omni-archive__stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:12px;padding:16px}.omni-archive__stat{padding:14px;border-radius:14px;background:color-mix(in srgb,var(--omni-bg-secondary,#252526) 76%,#000);border:1px solid var(--omni-border,#3c3c3c)}.omni-archive__stat-label{font-size:12px;text-transform:uppercase;letter-spacing:.08em;color:var(--omni-muted-fg,#9d9d9d);margin-bottom:6px}.omni-archive__stat-value{font-size:24px;font-weight:700}
+.omni-archive__workspace{display:grid;grid-template-columns:minmax(0,1.7fr) minmax(320px,.95fr);gap:16px;align-items:start}.omni-archive__table-wrap{overflow:auto;min-width:0;max-height:70vh}.omni-archive__table{width:100%;table-layout:fixed;border-collapse:collapse}.omni-archive__table th,.omni-archive__table td{padding:12px 14px;border-bottom:1px solid var(--omni-border,#3c3c3c);text-align:left;vertical-align:top;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.omni-archive__table th:first-child{width:42%}.omni-archive__table th{position:sticky;top:0;font-size:12px;text-transform:uppercase;letter-spacing:.08em;color:var(--omni-muted-fg,#9d9d9d);background:var(--omni-bg-secondary,#252526);z-index:1}.omni-archive__path{font-family:var(--omni-mono-font,"SFMono-Regular",Consolas,monospace)}.omni-archive__entry{height:43px;cursor:pointer;transition:background-color 120ms ease}.omni-archive__entry:hover{background:color-mix(in srgb,var(--omni-accent,#d97706) 8%,transparent)}.omni-archive__entry:focus-visible{outline:2px solid var(--omni-accent,#d97706);outline-offset:-2px}.omni-archive__entry.is-selected{background:color-mix(in srgb,var(--omni-accent,#d97706) 16%,transparent)}.omni-archive__empty{padding:26px 18px;text-align:center;color:var(--omni-muted-fg,#9d9d9d)}
+.omni-archive__preview-panel{padding:18px;min-height:420px;display:flex;flex-direction:column;gap:14px}.omni-archive__preview-header{display:flex;justify-content:space-between;gap:12px;align-items:flex-start}.omni-archive__preview-kicker{font-size:12px;letter-spacing:.08em;text-transform:uppercase;color:var(--omni-muted-fg,#9d9d9d);margin-bottom:6px}.omni-archive__preview-header h2{margin:0;font-size:18px;line-height:1.35;word-break:break-word}.omni-archive__preview-badge{border-radius:999px;padding:8px 12px;font-size:12px;font-weight:700;background:var(--omni-badge-bg,#3a3d41);white-space:nowrap}.omni-archive__preview-meta{margin:0}.omni-archive__preview{margin:0;flex:1;overflow:auto;white-space:pre-wrap;word-break:break-word;border-radius:14px;border:1px solid var(--omni-border,#3c3c3c);background:var(--omni-code-bg,#181818);padding:14px;color:var(--omni-fg,#d4d4d4);font:12px/1.55 var(--omni-mono-font,"SFMono-Regular",Consolas,monospace)}
+.omni-archive__save{align-self:flex-start;padding:8px 12px;border:1px solid var(--omni-border,#3c3c3c);border-radius:6px;background:var(--omni-button-bg,#3a3d41);color:var(--omni-fg,#d4d4d4);font:inherit;cursor:pointer}.omni-archive__save:hover:not(:disabled){background:var(--omni-button-hover-bg,#45494e)}.omni-archive__save:disabled{opacity:.55;cursor:not-allowed}.omni-archive__spacer td{padding:0!important;border:0!important}
+@media(max-width:720px){.omni-viewer--archive{padding:16px 10px 24px}.omni-archive__hero{flex-direction:column}.omni-archive__pills{justify-content:flex-start}.omni-archive__table th:nth-child(n+3),.omni-archive__table td:nth-child(n+3){display:none}.omni-archive__workspace{grid-template-columns:1fr}.omni-archive__preview-panel{min-height:280px}}