omni-viewer-core 0.1.0

package/dist/parsers/types.d.ts

@@ -0,0 +1,103 @@
+export type ParseResult<T> = {
+    status: 'ok';
+    document: T;
+    diagnostics: Diagnostic[];
+} | {
+    status: 'partial';
+    document: T;
+    diagnostics: Diagnostic[];
+} | {
+    status: 'failed';
+    failure: ParseFailure;
+    diagnostics: Diagnostic[];
+};
+export interface ParseFailure {
+    code: 'invalid-format' | 'corrupted' | 'password-required' | 'limit-exceeded' | 'aborted' | 'missing-dependency';
+    /** true when retrying with amended input can succeed (e.g. password). */
+    retryable: boolean;
+    messageKey: string;
+    args?: Record<string, string | number>;
+}
+export interface Diagnostic {
+    severity: 'info' | 'warning' | 'error';
+    code: string;
+    /** Core catalog key (never inline English — ADR 17/28). */
+    messageKey: string;
+    args?: Record<string, string | number>;
+    /** Sheet name, page number, entry path, row range … */
+    location?: string;
+}
+export interface ParseOutcome<T> {
+    /** Deterministic — the conformance kit compares this. */
+    result: ParseResult<T>;
+    /** Environment-dependent — logging / UI badges only, never compared. */
+    execution: ExecutionReport;
+}
+export interface ExecutionReport {
+    workerUsed: boolean;
+    /** false = only cooperative (soft) limits applied in this environment. */
+    hardLimitEnforced: boolean;
+    elapsedMillis: number;
+}
+export interface ParseOptions {
+    /** Cooperative cancellation — parsers check this at loop checkpoints. */
+    signal?: AbortSignal;
+    limits?: ResourceLimits;
+}
+export interface ResourceLimits {
+    /** Enforced by the platform before loading bytes; parsers re-check as 2nd defense. */
+    maxInputBytes?: number;
+    /** Cumulative decompressed output cap (zip bomb defense). */
+    maxDecompressedBytes?: number;
+    /** Archive entries / table rows cap. */
+    maxEntries?: number;
+    /** Soft unless running in a terminatable Worker (DESIGN.md §3-①). */
+    maxParseMillis?: number;
+}
+/** Core-defined default limits; platforms may override per call. */
+export declare const DEFAULT_LIMITS: Required<Pick<ResourceLimits, 'maxInputBytes' | 'maxEntries' | 'maxParseMillis'>>;
+export type LimitViolation = {
+    kind: 'aborted';
+} | {
+    kind: 'time';
+    elapsedMillis: number;
+} | {
+    kind: 'entries';
+    count: number;
+} | {
+    kind: 'decompressed';
+    bytes: number;
+};
+/**
+ * Cooperative limit tracking (DESIGN.md §3-①). Parsers call `checkpoint()`
+ * inside their record/row/chunk loops; a non-null return means stop now and
+ * report `partial`/`failed`. Wall-clock use is confined to the tracker so the
+ * *decision points* stay deterministic given the same limits and inputs
+ * (time-based stops are inherently soft and excluded from conformance
+ * fixtures).
+ */
+export declare class LimitTracker {
+    private readonly limits;
+    private readonly signal?;
+    private readonly startedAt;
+    private entries;
+    private decompressedBytes;
+    constructor(limits: ResourceLimits, signal?: AbortSignal | undefined);
+    addEntries(n: number): void;
+    addDecompressedBytes(n: number): void;
+    get entryCount(): number;
+    elapsedMillis(): number;
+    checkpoint(): LimitViolation | null;
+}
+/**
+ * Decode input bytes as UTF-8 text (BOM tolerated; parseCsv strips it).
+ * UTF-8 decoding is deterministic across engines. Legacy encodings must use
+ * core-bundled decoding tables instead (determinism rule, ADR 41).
+ */
+export declare function decodeUtf8(data: Uint8Array): string;
+/**
+ * UTF-8 byte length of a string without allocating an encoded copy, so
+ * `maxInputBytes` can be enforced for string inputs too (allocating via
+ * TextEncoder would defeat the memory cap being checked).
+ */
+export declare function utf8ByteLength(text: string): number;

package/dist/parsers/types.js

@@ -0,0 +1,106 @@
+// Parser layer contracts (DESIGN.md §3-①).
+//
+// Determinism rule: same bytes + same ParseOptions => identical ParseResult
+// (including diagnostics) on every platform and engine. Environment-dependent
+// information lives in ExecutionReport, which conformance comparison ignores
+// (ADR 34). Input-caused failures never throw — they are `status: 'failed'`;
+// throwing is reserved for programmer errors.
+/** Core-defined default limits; platforms may override per call. */
+export const DEFAULT_LIMITS = {
+    maxInputBytes: 256 * 1024 * 1024,
+    maxEntries: 1_000_000,
+    maxParseMillis: 30_000
+};
+/**
+ * Cooperative limit tracking (DESIGN.md §3-①). Parsers call `checkpoint()`
+ * inside their record/row/chunk loops; a non-null return means stop now and
+ * report `partial`/`failed`. Wall-clock use is confined to the tracker so the
+ * *decision points* stay deterministic given the same limits and inputs
+ * (time-based stops are inherently soft and excluded from conformance
+ * fixtures).
+ */
+export class LimitTracker {
+    limits;
+    signal;
+    startedAt;
+    entries = 0;
+    decompressedBytes = 0;
+    constructor(limits, signal) {
+        this.limits = limits;
+        this.signal = signal;
+        this.startedAt = Date.now();
+    }
+    addEntries(n) {
+        this.entries += n;
+    }
+    addDecompressedBytes(n) {
+        this.decompressedBytes += n;
+    }
+    get entryCount() {
+        return this.entries;
+    }
+    elapsedMillis() {
+        return Date.now() - this.startedAt;
+    }
+    checkpoint() {
+        if (this.signal?.aborted)
+            return { kind: 'aborted' };
+        if (this.limits.maxEntries !== undefined &&
+            this.entries > this.limits.maxEntries) {
+            return { kind: 'entries', count: this.entries };
+        }
+        if (this.limits.maxDecompressedBytes !== undefined &&
+            this.decompressedBytes > this.limits.maxDecompressedBytes) {
+            return { kind: 'decompressed', bytes: this.decompressedBytes };
+        }
+        if (this.limits.maxParseMillis !== undefined) {
+            const elapsed = this.elapsedMillis();
+            if (elapsed > this.limits.maxParseMillis) {
+                return { kind: 'time', elapsedMillis: elapsed };
+            }
+        }
+        return null;
+    }
+}
+/**
+ * Decode input bytes as UTF-8 text (BOM tolerated; parseCsv strips it).
+ * UTF-8 decoding is deterministic across engines. Legacy encodings must use
+ * core-bundled decoding tables instead (determinism rule, ADR 41).
+ */
+export function decodeUtf8(data) {
+    return new TextDecoder('utf-8', { fatal: false }).decode(data);
+}
+/**
+ * UTF-8 byte length of a string without allocating an encoded copy, so
+ * `maxInputBytes` can be enforced for string inputs too (allocating via
+ * TextEncoder would defeat the memory cap being checked).
+ */
+export function utf8ByteLength(text) {
+    let bytes = 0;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code < 0x80) {
+            bytes += 1;
+        }
+        else if (code < 0x800) {
+            bytes += 2;
+        }
+        else if (code >= 0xd800 && code <= 0xdbff) {
+            // Surrogate pair -> one 4-byte code point (lone surrogates encode
+            // as 3-byte replacement chars; counting 4 here is a safe upper
+            // bound only when the low surrogate follows, which we skip).
+            const next = text.charCodeAt(i + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                bytes += 4;
+                i++;
+            }
+            else {
+                bytes += 3;
+            }
+        }
+        else {
+            bytes += 3;
+        }
+    }
+    return bytes;
+}

package/dist/parsers/video/index.d.ts

@@ -0,0 +1,6 @@
+export interface VideoInfo {
+    format: string;
+    mimeType: string;
+    warnings: string[];
+}
+export declare function parseVideoInfo(fileName: string, data: Uint8Array): VideoInfo;

package/dist/parsers/video/index.js

@@ -0,0 +1,2 @@
+const MIME = { mp4: 'video/mp4', mts: 'video/mp2t', m2ts: 'video/mp2t', avi: 'video/x-msvideo', mov: 'video/quicktime', wmv: 'video/x-ms-wmv', flv: 'video/x-flv', webm: 'video/webm', mkv: 'video/x-matroska' };
+export function parseVideoInfo(fileName, data) { const ext = fileName.toLowerCase().split('.').pop() ?? ''; return { format: ext.toUpperCase() || 'VIDEO', mimeType: MIME[ext] ?? 'application/octet-stream', warnings: data.byteLength ? [] : ['The video file is empty.'] }; }

package/dist/parsers/yaml/index.d.ts

@@ -0,0 +1,16 @@
+import type { ParseOutcome } from '../types.js';
+import type { YamlDocument, YamlParserDeps } from './model.js';
+export * from './model.js';
+export declare const YAML_INPUT_OWNERSHIP: "borrows";
+export interface YamlParseOptions {
+    deps?: YamlParserDeps;
+    limits?: {
+        maxInputBytes?: number;
+        maxEntries?: number;
+        maxDocuments?: number;
+        maxDepth?: number;
+        maxAliases?: number;
+    };
+    signal?: AbortSignal;
+}
+export declare function parseYaml(input: Uint8Array | string, options?: YamlParseOptions): ParseOutcome<YamlDocument>;

package/dist/parsers/yaml/index.js

@@ -0,0 +1,58 @@
+import { decodeUtf8, utf8ByteLength } from '../types.js';
+export * from './model.js';
+export const YAML_INPUT_OWNERSHIP = 'borrows';
+export function parseYaml(input, options = {}) {
+    const started = Date.now();
+    const bytes = typeof input === 'string' ? utf8ByteLength(input) : input.byteLength;
+    const max = options.limits?.maxInputBytes ?? 10 * 1024 * 1024;
+    const finish = (result) => ({ result, execution: { workerUsed: false, hardLimitEnforced: false, elapsedMillis: Date.now() - started } });
+    if (bytes > max)
+        return finish({ status: 'failed', failure: { code: 'limit-exceeded', retryable: false, messageKey: 'diag.limit-exceeded.input', args: { maxBytes: max } }, diagnostics: [] });
+    if (options.signal?.aborted)
+        return finish({ status: 'failed', failure: { code: 'aborted', retryable: true, messageKey: 'diag.aborted' }, diagnostics: [] });
+    if (!options.deps)
+        return finish({ status: 'failed', failure: { code: 'missing-dependency', retryable: true, messageKey: 'diag.yaml.missing-dependency' }, diagnostics: [] });
+    const text = typeof input === 'string' ? input : decodeUtf8(input);
+    const diagnostics = [];
+    try {
+        const ast = options.deps.parse(text);
+        const maxDocs = options.limits?.maxDocuments ?? 100;
+        const docs = [];
+        for (let i = 0; i < Math.min(ast.length, maxDocs); i++) {
+            if (options.signal?.aborted)
+                return finish(docs.length ? { status: 'partial', document: { text, documents: docs }, diagnostics: [...diagnostics, { severity: 'warning', code: 'yaml.aborted', messageKey: 'diag.aborted' }] } : { status: 'failed', failure: { code: 'aborted', retryable: true, messageKey: 'diag.aborted' }, diagnostics });
+            const sourceDoc = ast[i];
+            const errors = sourceDoc?.errors ?? [];
+            for (const error of errors) {
+                const pos = error.linePos?.[0];
+                diagnostics.push({ severity: 'error', code: 'yaml.invalid', messageKey: 'diag.yaml.invalid', location: pos ? `line:${pos.line}:${pos.col}` : `document:${i + 1}` });
+            }
+            const node = options.deps.normalize ? options.deps.normalize(sourceDoc, i) : normalizeUnknown(sourceDoc, `$doc[${i}]`);
+            const violation = validateTree(node, options.limits?.maxEntries ?? 100_000, options.limits?.maxDepth ?? 100, options.limits?.maxAliases ?? 10_000);
+            if (violation)
+                diagnostics.push({ severity: 'warning', code: violation, messageKey: `diag.${violation}`, location: `document:${i + 1}` });
+            docs.push(node);
+        }
+        if (ast.length > maxDocs)
+            diagnostics.push({ severity: 'warning', code: 'yaml.document-limit', messageKey: 'diag.yaml.document-limit', args: { count: maxDocs } });
+        return finish(diagnostics.length ? { status: 'partial', document: { text, documents: docs }, diagnostics } : { status: 'ok', document: { text, documents: docs }, diagnostics });
+    }
+    catch (error) {
+        return finish({ status: 'failed', failure: { code: 'invalid-format', retryable: false, messageKey: 'diag.yaml.invalid' }, diagnostics: [{ severity: 'error', code: 'yaml.invalid', messageKey: 'diag.yaml.invalid', location: String(error) }] });
+    }
+}
+function normalizeUnknown(value, path, key = '$') { if (Array.isArray(value))
+    return { kind: 'seq', key, path, children: value.map((v, i) => normalizeUnknown(v, `${path}[${i}]`, String(i))) }; if (value !== null && typeof value === 'object')
+    return { kind: 'map', key, path, children: Object.entries(value).map(([k, v]) => normalizeUnknown(v, `${path}.${k}`, k)) }; return { kind: 'scalar', key, path, value: value, raw: String(value) }; }
+function validateTree(root, maxNodes, maxDepth, maxAliases) { let nodes = 0, aliases = 0; const stack = [{ node: root, depth: 0 }]; while (stack.length) {
+    const item = stack.pop();
+    nodes++;
+    if (nodes > maxNodes)
+        return 'yaml.node-limit';
+    if (item.depth > maxDepth)
+        return 'yaml.depth-limit';
+    if (item.node.kind === 'alias' && ++aliases > maxAliases)
+        return 'yaml.alias-limit';
+    for (const child of item.node.children ?? [])
+        stack.push({ node: child, depth: item.depth + 1 });
+} return null; }

package/dist/parsers/yaml/model.d.ts

@@ -0,0 +1,22 @@
+export type YamlNodeKind = 'map' | 'seq' | 'scalar' | 'alias';
+export interface YamlNode {
+    kind: YamlNodeKind;
+    key: string;
+    path: string;
+    value?: string | boolean | number | null;
+    raw?: string;
+    range?: readonly number[] | undefined;
+    anchorId?: string | undefined;
+    aliasOf?: string;
+    children?: YamlNode[];
+}
+export interface YamlDocument {
+    text: string;
+    documents: YamlNode[];
+}
+export interface YamlParserDeps {
+    /** Must parse with YAML 1.2 core schema and return YAML AST documents. */
+    parse(text: string): readonly unknown[];
+    /** Optional platform adapter to normalize its YAML AST into safe core nodes. */
+    normalize?(document: unknown, index: number): YamlNode;
+}

package/dist/parsers/yaml/model.js

@@ -0,0 +1 @@
+export {};

package/dist/parsers/yaml/self-loading.d.ts

@@ -0,0 +1,3 @@
+import type { YamlParserDeps } from './model.js';
+/** Dynamic optional-peer loader; base parser/viewer modules never import yaml. */
+export declare function loadYamlParserDeps(): Promise<YamlParserDeps>;

package/dist/parsers/yaml/self-loading.js

@@ -0,0 +1,19 @@
+/** Dynamic optional-peer loader; base parser/viewer modules never import yaml. */
+export async function loadYamlParserDeps() {
+    const yaml = await import('yaml');
+    const normalize = (node, path, key = '$') => {
+        const n = node;
+        if (n.contents !== undefined)
+            return normalize(n.contents, path, key);
+        const common = { key, path, range: n.range, anchorId: n.anchor };
+        if (n.type === 'ALIAS' || n.constructor?.name === 'Alias')
+            return { ...common, kind: 'alias', aliasOf: String(n.source ?? '') };
+        if (Array.isArray(n.items)) {
+            const pairs = n.items.every(item => item && typeof item === 'object' && 'key' in item);
+            return { ...common, kind: pairs ? 'map' : 'seq', children: n.items.map((item, i) => { const pair = item; const childKey = pairs ? String(pair.key?.value ?? pair.key?.source ?? i) : String(i); return normalize(pairs ? pair.value : item, pairs ? `${path}.${childKey}` : `${path}[${i}]`, childKey); }) };
+        }
+        const value = n.value ?? node;
+        return { ...common, kind: 'scalar', value: value, raw: n.source === undefined ? String(value) : String(n.source) };
+    };
+    return { parse: (text) => yaml.parseAllDocuments(text, { schema: 'core', customTags: [] }), normalize: (document, index) => normalize(document, `$doc[${index}]`) };
+}

package/dist/parsers/zip-scan.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Total uncompressed bytes declared by a ZIP central directory.
+ *
+ * Returns `null` when the input is not recognizably a ZIP, and `Infinity` when
+ * ZIP64 markers or structural inconsistencies make the total unknowable from
+ * the 32-bit central-directory fields (always over any finite limit).
+ */
+export declare function declaredZipUncompressedBytes(input: Uint8Array): number | null;

package/dist/parsers/zip-scan.js

@@ -0,0 +1,80 @@
+// Declared-size pre-scan for ZIP containers. Sums the uncompressed sizes
+// recorded in the central directory *before* any inflate runs, so archives
+// whose headers admit an oversized payload (zip bombs) are rejected up front
+// without allocating anything. A crafted archive can lie in these fields, so
+// callers that hand the bytes to a library with its own inflater (SheetJS,
+// JSZip, docx-preview) must still treat this as a first line of defense, not
+// a hard guarantee.
+const EOCD = 0x06054b50;
+const CDFH = 0x02014b50;
+const LFH = 0x04034b50;
+const CENTRAL_DIRECTORY_DIGITAL_SIGNATURE = 0x05054b50;
+/** EOCD is 22 bytes plus a comment of at most 0xffff bytes. */
+const EOCD_SEARCH_SPAN = 22 + 0xffff;
+/**
+ * Total uncompressed bytes declared by a ZIP central directory.
+ *
+ * Returns `null` when the input is not recognizably a ZIP, and `Infinity` when
+ * ZIP64 markers or structural inconsistencies make the total unknowable from
+ * the 32-bit central-directory fields (always over any finite limit).
+ */
+export function declaredZipUncompressedBytes(input) {
+    if (input.length < 22)
+        return null;
+    const v = new DataView(input.buffer, input.byteOffset, input.byteLength);
+    let eocd = -1;
+    for (let p = input.length - 22; p >= Math.max(0, input.length - EOCD_SEARCH_SPAN); p--) {
+        if (v.getUint32(p, true) !== EOCD)
+            continue;
+        // A signature-like byte sequence inside the ZIP comment is not an EOCD.
+        // The real EOCD comment must end exactly at the end of the input.
+        if (p + 22 + v.getUint16(p + 20, true) !== input.length)
+            continue;
+        eocd = p;
+        break;
+    }
+    if (eocd < 0) {
+        // Office ZIP containers start with a local-file header. If that marker
+        // is present but a complete EOCD is not, treat the truncated/malformed
+        // archive as unbounded instead of allowing the downstream inflater to
+        // decide whether it can recover partial entries.
+        return v.getUint32(0, true) === LFH ? Number.POSITIVE_INFINITY : null;
+    }
+    const disk = v.getUint16(eocd + 4, true);
+    const centralDisk = v.getUint16(eocd + 6, true);
+    const diskCount = v.getUint16(eocd + 8, true);
+    const count = v.getUint16(eocd + 10, true);
+    const centralSize = v.getUint32(eocd + 12, true);
+    let p = v.getUint32(eocd + 16, true);
+    if (disk === 0xffff || centralDisk === 0xffff || diskCount === 0xffff ||
+        count === 0xffff || centralSize === 0xffffffff || p === 0xffffffff)
+        return Number.POSITIVE_INFINITY; // ZIP64
+    // Multi-disk archives cannot be bounded from this single input.
+    if (disk !== 0 || centralDisk !== 0 || diskCount !== count)
+        return Number.POSITIVE_INFINITY;
+    const centralEnd = p + centralSize;
+    if (p > eocd || centralEnd !== eocd)
+        return Number.POSITIVE_INFINITY;
+    let total = 0;
+    for (let i = 0; i < count; i++) {
+        if (p + 46 > centralEnd || v.getUint32(p, true) !== CDFH) {
+            return Number.POSITIVE_INFINITY;
+        }
+        const size = v.getUint32(p + 24, true);
+        if (size === 0xffffffff)
+            return Number.POSITIVE_INFINITY; // ZIP64
+        total += size;
+        const next = p + 46 + v.getUint16(p + 28, true) + v.getUint16(p + 30, true) + v.getUint16(p + 32, true);
+        if (next > centralEnd)
+            return Number.POSITIVE_INFINITY;
+        p = next;
+    }
+    // A central-directory digital signature is permitted after the file
+    // headers and is included in the EOCD central-directory byte count.
+    if (p < centralEnd && p + 6 <= centralEnd && v.getUint32(p, true) === CENTRAL_DIRECTORY_DIGITAL_SIGNATURE) {
+        p += 6 + v.getUint16(p + 4, true);
+    }
+    if (p !== centralEnd)
+        return Number.POSITIVE_INFINITY;
+    return total;
+}

package/dist/registry/container.d.ts

@@ -0,0 +1,17 @@
+export type ContainerKind = 'zip' | 'ole';
+/** Local file header 'PK\x03\x04' — the start of every OOXML/ODF/zip file. */
+export declare const ZIP_MAGIC: readonly [80, 75, 3, 4];
+/** Empty ZIP end-of-central-directory record. */
+export declare const EMPTY_ZIP_MAGIC: readonly [80, 75, 5, 6];
+/** OLE2 / Compound File Binary signature. */
+export declare const OLE_MAGIC: readonly [208, 207, 17, 224, 161, 177, 26, 225];
+/** Longest container signature — how many leading bytes a probe needs to sniff. */
+export declare const CONTAINER_SNIFF_BYTES = 262;
+/**
+ * Which container an office extension lives in. Used in stage-1 detection to
+ * verify a trusted extension against the actual bytes and to route ambiguous
+ * containers. Extend this as word/ppt/hwpx land (they share the same map).
+ */
+export declare const OFFICE_CONTAINER_BY_EXT: Readonly<Record<string, ContainerKind>>;
+/** Classify the container from leading bytes, or null when neither matches. */
+export declare function sniffContainer(bytes: Uint8Array): ContainerKind | null;

package/dist/registry/container.js

@@ -0,0 +1,49 @@
+// Container-format signatures and the office extension → container map
+// (DESIGN.md §7-3, docs/viewers/excel.md §5). ZIP (xlsx/xlsm/docx/pptx/hwpx…)
+// and OLE/CFB (xls/doc/ppt/hwp…) each share one signature across many formats,
+// so the leading bytes only tell us the *container* — which viewer it holds is
+// resolved by probeContainer (stage 2). Excel is the first such viewer; the
+// office family inherits this contract.
+/** Local file header 'PK\x03\x04' — the start of every OOXML/ODF/zip file. */
+export const ZIP_MAGIC = [0x50, 0x4b, 0x03, 0x04];
+/** Empty ZIP end-of-central-directory record. */
+export const EMPTY_ZIP_MAGIC = [0x50, 0x4b, 0x05, 0x06];
+/** OLE2 / Compound File Binary signature. */
+export const OLE_MAGIC = [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1];
+/** Longest container signature — how many leading bytes a probe needs to sniff. */
+export const CONTAINER_SNIFF_BYTES = 262; // TAR's `ustar` reaches byte 261
+/**
+ * Which container an office extension lives in. Used in stage-1 detection to
+ * verify a trusted extension against the actual bytes and to route ambiguous
+ * containers. Extend this as word/ppt/hwpx land (they share the same map).
+ */
+export const OFFICE_CONTAINER_BY_EXT = {
+    xlsx: 'zip',
+    xlsm: 'zip',
+    xlsb: 'zip', // binary workbook — still an OOXML-style zip with an xl/ tree
+    ods: 'zip', // OpenDocument spreadsheet — zip with a spreadsheet mimetype
+    xls: 'ole',
+    pptx: 'zip',
+    ppt: 'ole',
+    docx: 'zip',
+    doc: 'ole',
+    hwpx: 'zip',
+    hwp: 'ole'
+};
+function startsWith(bytes, magic) {
+    if (bytes.byteLength < magic.length)
+        return false;
+    for (let i = 0; i < magic.length; i++) {
+        if (bytes[i] !== magic[i])
+            return false;
+    }
+    return true;
+}
+/** Classify the container from leading bytes, or null when neither matches. */
+export function sniffContainer(bytes) {
+    if (startsWith(bytes, ZIP_MAGIC) || startsWith(bytes, EMPTY_ZIP_MAGIC))
+        return 'zip';
+    if (startsWith(bytes, OLE_MAGIC))
+        return 'ole';
+    return null;
+}

package/dist/registry/index.d.ts

@@ -0,0 +1,133 @@
+import type { ServiceId } from '../host/index.js';
+import { type ContainerKind } from './container.js';
+/** One contiguous byte run at a fixed offset. */
+export interface MagicByteRun {
+    offset: number;
+    bytes: readonly number[];
+}
+/** A signature matches when *every* run matches (AND). A descriptor's
+ *  `magicSignatures` list matches when *any* signature matches (OR) — this is
+ *  how one viewer covers several formats (e.g. the image viewer's PNG/JPEG/
+ *  GIF/BMP/WebP), and how a multi-part signature like WebP's `RIFF`@0 + `WEBP`@8
+ *  is expressed (docs/viewers/image.md §1). */
+export type MagicSignature = readonly MagicByteRun[];
+export interface ViewerDescriptor {
+    id: string;
+    displayNameKey: string;
+    /** Lower-case, no leading dot. */
+    extensions: string[];
+    priority: number;
+    /** Leading file bytes that must match when sniff bytes are provided
+     *  (e.g. '%PDF-'). A mismatch excludes the viewer (docs/viewers/pdf.md). */
+    magicPrefix?: readonly number[];
+    /** Offset-aware alternative to magicPrefix for viewers that span multiple
+     *  formats or need non-zero offsets. Excludes the viewer when sniff bytes
+     *  are present and no signature matches. */
+    magicSignatures?: readonly MagicSignature[];
+    requiredServices: readonly ServiceId[];
+    optionalServices: readonly ServiceId[];
+}
+/** 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 declare const IMAGE_MAGIC_SIGNATURES: readonly MagicSignature[];
+export declare const AVRO_MAGIC_SIGNATURES: readonly MagicSignature[];
+export declare const BAG_MAGIC_SIGNATURES: readonly MagicSignature[];
+export declare const STP_MAGIC_SIGNATURES: readonly MagicSignature[];
+export declare const DB3_MAGIC_SIGNATURES: readonly MagicSignature[];
+export declare const BLF_MAGIC_SIGNATURES: readonly MagicSignature[];
+export declare const MF4_MAGIC_SIGNATURES: readonly MagicSignature[];
+export declare const PCAP_MAGIC_SIGNATURES: readonly MagicSignature[];
+export declare const PCAPNG_MAGIC_SIGNATURES: readonly MagicSignature[];
+export declare const PSD_MAGIC_SIGNATURES: readonly MagicSignature[];
+export declare const SHAPEFILE_MAGIC_SIGNATURES: readonly MagicSignature[];
+/**
+ * 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 declare const REQUIRED_SNIFF_BYTES: number;
+export declare const CSV_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const FALLBACK_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const PDF_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const PARQUET_MAGIC_SIGNATURES: readonly MagicSignature[];
+export declare const PARQUET_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const AVRO_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const BAG_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const STP_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const DB3_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const REQIF_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const HDF5_MAGIC_PREFIX: readonly [137, 72, 68, 70, 13, 10, 26, 10];
+export declare const HDF5_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const MAT_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const AUDIO_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const VIDEO_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const DBC_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const ARXML_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const A2L_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const ASC_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const BLF_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const MF4_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const PCAP_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const PCAPNG_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const MERMAID_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const PLANTUML_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const SHAPEFILE_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const PSD_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const JSON_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const TOML_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const JSONL_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const YAML_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const PROTO_VIEWER_DESCRIPTOR: ViewerDescriptor;
+/**
+ * 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 declare const EXCEL_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const PPT_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const WORD_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const HWP_VIEWER_DESCRIPTOR: ViewerDescriptor;
+/**
+ * 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 declare const IMAGE_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const MARKDOWN_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const ARCHIVE_MAGIC_SIGNATURES: readonly MagicSignature[];
+/** Archive is intentionally lower priority than Office container viewers. */
+export declare const ARCHIVE_VIEWER_DESCRIPTOR: ViewerDescriptor;
+export declare const CORE_VIEWER_DESCRIPTORS: readonly ViewerDescriptor[];
+export { looksLikeJsonDocument, looksLikeJsonl, looksLikeProto, sniffTextViewer } from './sniff.js';
+export { CONTAINER_SNIFF_BYTES, OFFICE_CONTAINER_BY_EXT, OLE_MAGIC, ZIP_MAGIC, sniffContainer, type ContainerKind } from './container.js';
+export { probeContainer } from './probe.js';
+export interface DetectionResult {
+    /** The resolved viewer, or 'fallback' when unresolved. For
+     *  'ambiguous-container' this is 'fallback' (the safe default if the caller
+     *  does not run probeContainer). */
+    viewerId: string;
+    /** 'extension' for an extension match; 'content' for a text sniff (J17);
+     *  'ambiguous-container' when the bytes are a zip/ole container the caller
+     *  should refine with probeContainer; 'fallback' when nothing matched. */
+    matchedBy: 'extension' | 'content' | 'ambiguous-container' | 'fallback';
+    /** Present only when matchedBy === 'ambiguous-container'. */
+    container?: ContainerKind;
+}
+/**
+ * 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 declare function detectViewer(fileName: string, availableServices?: ReadonlySet<ServiceId>, descriptors?: readonly ViewerDescriptor[], sniffBytes?: Uint8Array, sniffText?: string): DetectionResult;