omni-viewer-core 0.1.0

package/dist/parsers/pptx/vscode.d.ts

@@ -0,0 +1,4 @@
+import type { SlideDeck } from '../slide-model.js';
+import type { ParseOptions, ParseOutcome } from '../types.js';
+/** VS Code's full-fidelity PPTX parser, adapted from a file path to bytes. */
+export declare function parsePptxVscode(input: Uint8Array, options?: ParseOptions): Promise<ParseOutcome<SlideDeck>>;

package/dist/parsers/pptx/vscode.js

@@ -0,0 +1,18 @@
+import { PptxXmlParser } from './vscode-parser.js';
+/** VS Code's full-fidelity PPTX parser, adapted from a file path to bytes. */
+export async function parsePptxVscode(input, options = {}) {
+    const started = Date.now();
+    const diagnostics = [];
+    if (options.signal?.aborted)
+        return { result: { status: 'failed', failure: { code: 'aborted', retryable: true, messageKey: 'diag.aborted' }, diagnostics }, execution: { workerUsed: false, hardLimitEnforced: false, elapsedMillis: 0 } };
+    if (input.byteLength > (options.limits?.maxInputBytes ?? 50 * 1024 * 1024))
+        return { result: { status: 'failed', failure: { code: 'limit-exceeded', retryable: false, messageKey: 'diag.limit-exceeded.input' }, diagnostics }, execution: { workerUsed: false, hardLimitEnforced: false, elapsedMillis: Date.now() - started } };
+    try {
+        const parsed = await PptxXmlParser.parse(input);
+        const slides = parsed.slides;
+        return { result: { status: 'ok', document: { slides, totalSlides: parsed.totalSlides, ...(slides[0] ? { slideSize: { widthPx: slides[0].widthPx, heightPx: slides[0].heightPx } } : {}) }, diagnostics }, execution: { workerUsed: false, hardLimitEnforced: false, elapsedMillis: Date.now() - started } };
+    }
+    catch {
+        return { result: { status: 'failed', failure: { code: 'invalid-format', retryable: false, messageKey: 'diag.ppt.invalid-format' }, diagnostics }, execution: { workerUsed: false, hardLimitEnforced: false, elapsedMillis: Date.now() - started } };
+    }
+}

package/dist/parsers/pptx/zip-reader.d.ts

@@ -0,0 +1,3 @@
+import type { ParseOptions } from '../types.js';
+import type { PptxZipReader } from './index.js';
+export declare function openPptxZip(input: Uint8Array, options?: ParseOptions): Promise<PptxZipReader>;

package/dist/parsers/pptx/zip-reader.js

@@ -0,0 +1,20 @@
+const EOCD = 0x06054b50, CDFH = 0x02014b50, LFH = 0x04034b50;
+function entries(input) { 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 - 65557); p--)
+    if (v.getUint32(p, true) === EOCD) {
+        eocd = p;
+        break;
+    } if (eocd < 0)
+    throw new Error('Invalid ZIP'); const count = v.getUint16(eocd + 10, true), out = []; let p = v.getUint32(eocd + 16, true); for (let i = 0; i < count; i++) {
+    if (p + 46 > input.length || v.getUint32(p, true) !== CDFH)
+        break;
+    const nameLen = v.getUint16(p + 28, true), extra = v.getUint16(p + 30, true), comment = v.getUint16(p + 32, true);
+    out.push({ name: new TextDecoder().decode(input.subarray(p + 46, p + 46 + nameLen)), method: v.getUint16(p + 10, true), compressedSize: v.getUint32(p + 20, true), localOffset: v.getUint32(p + 42, true) });
+    p += 46 + nameLen + extra + comment;
+} return out; }
+async function inflate(data) { const stream = new Blob([new Uint8Array(data).buffer]).stream().pipeThrough(new DecompressionStream('deflate-raw')); return new Uint8Array(await new Response(stream).arrayBuffer()); }
+export async function openPptxZip(input, options = {}) { const list = entries(input), byName = new Map(list.map(e => [e.name, e])); let decompressed = 0; const read = async (path) => { if (options.signal?.aborted)
+    throw new DOMException('Aborted', 'AbortError'); const e = byName.get(path); if (!e)
+    return; const v = new DataView(input.buffer, input.byteOffset, input.byteLength), p = e.localOffset; if (p + 30 > input.length || v.getUint32(p, true) !== LFH)
+    throw new Error('Invalid ZIP entry'); const start = p + 30 + v.getUint16(p + 26, true) + v.getUint16(p + 28, true), compressed = input.slice(start, start + e.compressedSize); const value = e.method === 0 ? compressed : e.method === 8 ? await inflate(compressed) : undefined; if (!value)
+    throw new Error('Unsupported ZIP compression'); decompressed += value.length; if (decompressed > (options.limits?.maxDecompressedBytes ?? 256 * 1024 * 1024))
+    throw new Error('ZIP limit'); return value; }; return { list: async () => list.map(e => e.name), bytes: read, text: async (path) => { const value = await read(path); return value ? new TextDecoder().decode(value) : undefined; } }; }

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

@@ -0,0 +1,90 @@
+export interface ProtoRange {
+    startLine: number;
+    endLine: number;
+}
+export interface ProtoField {
+    name: string;
+    type: string;
+    label: string;
+    number: number;
+    repeated: boolean;
+    optional: boolean;
+    map: boolean;
+    oneof?: string;
+    options: string[];
+    documentation: string;
+    line: number;
+}
+export interface ProtoMessage {
+    kind: 'message';
+    name: string;
+    fullName: string;
+    documentation: string;
+    fields: ProtoField[];
+    messages: ProtoMessage[];
+    enums: ProtoEnum[];
+    oneofs: string[];
+    reserved: string[];
+    range: ProtoRange;
+}
+export interface ProtoEnumValue {
+    name: string;
+    number: number;
+    documentation: string;
+    line: number;
+}
+export interface ProtoEnum {
+    kind: 'enum';
+    name: string;
+    fullName: string;
+    documentation: string;
+    values: ProtoEnumValue[];
+    range: ProtoRange;
+}
+export interface ProtoRpc {
+    name: string;
+    requestType: string;
+    responseType: string;
+    requestStream: boolean;
+    responseStream: boolean;
+    documentation: string;
+    line: number;
+}
+export interface ProtoService {
+    kind: 'service';
+    name: string;
+    fullName: string;
+    documentation: string;
+    rpcs: ProtoRpc[];
+    range: ProtoRange;
+}
+export interface ProtoReference {
+    from: string;
+    fromKind: 'field' | 'rpc' | 'import';
+    name: string;
+    to: string;
+    line: number;
+}
+export interface ProtoModel {
+    fileName: string;
+    syntax: string;
+    packageName: string;
+    imports: string[];
+    messages: ProtoMessage[];
+    enums: ProtoEnum[];
+    services: ProtoService[];
+    references: ProtoReference[];
+    warnings: string[];
+    stats: {
+        messages: number;
+        enums: number;
+        services: number;
+        rpcs: number;
+        fields: number;
+        imports: number;
+    };
+}
+/** Parse a proto2/proto3 schema without loading protoc or executing schema code. */
+export declare function parseProto(source: string, fileName?: string): ProtoModel;
+export declare function flattenProtoMessages(messages: readonly ProtoMessage[]): ProtoMessage[];
+export declare function allProtoTypes(model: ProtoModel): Array<ProtoMessage | ProtoEnum | ProtoService>;

package/dist/parsers/proto/index.js

@@ -0,0 +1,197 @@
+const scalarTypes = new Set(['double', 'float', 'int32', 'int64', 'uint32', 'uint64', 'sint32', 'sint64', 'fixed32', 'fixed64', 'sfixed32', 'sfixed64', 'bool', 'string', 'bytes']);
+const declarationPattern = /^(.+?)\s+([A-Za-z_][\w]*)\s*=\s*([0-9]+)\s*(?:\[([^\]]*)\])?\s*;/;
+const labeledFieldPattern = /^(optional|required|repeated)\s+(.+?)$/;
+/** Parse a proto2/proto3 schema without loading protoc or executing schema code. */
+export function parseProto(source, fileName = '') {
+    const lines = source.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
+    const model = { fileName, syntax: '', packageName: '', imports: [], messages: [], enums: [], services: [], references: [], warnings: [], stats: { messages: 0, enums: 0, services: 0, rpcs: 0, fields: 0, imports: 0 } };
+    const stack = [];
+    const docs = [];
+    let inBlockComment = false;
+    let blockComment = [];
+    const consumeDocs = () => { const value = docs.join('\n').trim(); docs.length = 0; return value; };
+    const currentMessage = () => { for (let i = stack.length - 1; i >= 0; i--)
+        if (stack[i].kind === 'message')
+            return stack[i].node; return undefined; };
+    const currentEnum = () => stack.at(-1)?.kind === 'enum' ? stack.at(-1).node : undefined;
+    const currentService = () => stack.at(-1)?.kind === 'service' ? stack.at(-1).node : undefined;
+    const currentOneof = () => stack.at(-1)?.kind === 'oneof' ? stack.at(-1).name : undefined;
+    lines.forEach((rawLine, index) => {
+        const lineNumber = index + 1;
+        let line = rawLine.trim();
+        if (inBlockComment) {
+            const end = line.indexOf('*/');
+            if (end < 0) {
+                blockComment.push(cleanDocLine(line));
+                return;
+            }
+            blockComment.push(cleanDocLine(line.slice(0, end)));
+            docs.push(blockComment.join('\n').trim());
+            blockComment = [];
+            inBlockComment = false;
+            line = line.slice(end + 2).trim();
+        }
+        if (!line)
+            return;
+        if (line.startsWith('//')) {
+            docs.push(line.replace(/^\/\/\s?/, ''));
+            return;
+        }
+        if (line.startsWith('/*')) {
+            const end = line.indexOf('*/', 2);
+            if (end < 0) {
+                inBlockComment = true;
+                blockComment = [cleanDocLine(line.slice(2))];
+                return;
+            }
+            docs.push(cleanDocLine(line.slice(2, end)));
+            line = line.slice(end + 2).trim();
+        }
+        line = stripInlineComment(line).trim();
+        if (!line)
+            return;
+        let match = line.match(/^syntax\s*=\s*"([^"]+)"\s*;/);
+        if (match) {
+            model.syntax = match[1];
+            consumeDocs();
+            return;
+        }
+        match = line.match(/^package\s+([\w.]+)\s*;/);
+        if (match) {
+            model.packageName = match[1];
+            consumeDocs();
+            return;
+        }
+        match = line.match(/^import\s+(?:public\s+|weak\s+)?["']([^"']+)["']\s*;/);
+        if (match) {
+            const imported = match[1];
+            model.imports.push(imported);
+            model.references.push({ from: fileName || 'current file', fromKind: 'import', name: imported, to: imported, line: lineNumber });
+            consumeDocs();
+            return;
+        }
+        match = line.match(/^message\s+([A-Za-z_]\w*)\s*\{/);
+        if (match) {
+            const parent = currentMessage();
+            const fullName = qualify(match[1], parent?.fullName || model.packageName);
+            const node = { kind: 'message', name: match[1], fullName, documentation: consumeDocs(), fields: [], messages: [], enums: [], oneofs: [], reserved: [], range: { startLine: lineNumber, endLine: lineNumber } };
+            parent ? parent.messages.push(node) : model.messages.push(node);
+            stack.push({ kind: 'message', name: node.name, fullName, node });
+            return;
+        }
+        match = line.match(/^enum\s+([A-Za-z_]\w*)\s*\{/);
+        if (match) {
+            const parent = currentMessage();
+            const fullName = qualify(match[1], parent?.fullName || model.packageName);
+            const node = { kind: 'enum', name: match[1], fullName, documentation: consumeDocs(), values: [], range: { startLine: lineNumber, endLine: lineNumber } };
+            parent ? parent.enums.push(node) : model.enums.push(node);
+            stack.push({ kind: 'enum', name: node.name, fullName, node });
+            return;
+        }
+        match = line.match(/^service\s+([A-Za-z_]\w*)\s*\{/);
+        if (match) {
+            const fullName = qualify(match[1], model.packageName);
+            const node = { kind: 'service', name: match[1], fullName, documentation: consumeDocs(), rpcs: [], range: { startLine: lineNumber, endLine: lineNumber } };
+            model.services.push(node);
+            stack.push({ kind: 'service', name: node.name, fullName, node });
+            return;
+        }
+        match = line.match(/^oneof\s+([A-Za-z_]\w*)\s*\{/);
+        if (match) {
+            currentMessage()?.oneofs.push(match[1]);
+            stack.push({ kind: 'oneof', name: match[1], fullName: match[1] });
+            consumeDocs();
+            return;
+        }
+        const enumNode = currentEnum();
+        match = line.match(/^([A-Za-z_]\w*)\s*=\s*(-?\d+)\s*(?:\[[^\]]*\])?\s*;/);
+        if (enumNode && match) {
+            enumNode.values.push({ name: match[1], number: Number(match[2]), documentation: consumeDocs(), line: lineNumber });
+            return;
+        }
+        const service = currentService();
+        match = line.match(/^rpc\s+([A-Za-z_]\w*)\s*\(\s*(stream\s+)?([.\w]+)\s*\)\s+returns\s*\(\s*(stream\s+)?([.\w]+)\s*\)/);
+        if (service && match) {
+            const rpc = { name: match[1], requestType: cleanType(match[3]), responseType: cleanType(match[5]), requestStream: !!match[2], responseStream: !!match[4], documentation: consumeDocs(), line: lineNumber };
+            service.rpcs.push(rpc);
+            model.references.push({ from: `${service.fullName}.${rpc.name}`, fromKind: 'rpc', name: 'request', to: rpc.requestType, line: lineNumber }, { from: `${service.fullName}.${rpc.name}`, fromKind: 'rpc', name: 'response', to: rpc.responseType, line: lineNumber });
+            if (line.includes('{'))
+                stack.push({ kind: 'block', name: '', fullName: '' });
+            return;
+        }
+        const message = currentMessage();
+        if (message) {
+            match = line.match(/^reserved\s+(.+);/);
+            if (match) {
+                message.reserved.push(match[1]);
+                consumeDocs();
+                return;
+            }
+            const field = parseField(line, lineNumber, consumeDocs(), currentOneof());
+            if (field) {
+                message.fields.push(field);
+                if (!scalarTypes.has(cleanType(field.type)) && !field.map)
+                    model.references.push({ from: message.fullName, fromKind: 'field', name: field.name, to: cleanType(field.type), line: lineNumber });
+                return;
+            }
+        }
+        if (line.includes('}')) {
+            for (let n = count(line, '}'); n > 0; n--) {
+                const frame = stack.pop();
+                if (frame?.node)
+                    frame.node.range.endLine = lineNumber;
+            }
+            consumeDocs();
+            return;
+        }
+        if (line.endsWith('{') && !/^rpc\b/.test(line))
+            stack.push({ kind: 'block', name: '', fullName: '' });
+        consumeDocs();
+    });
+    model.stats = buildStats(model);
+    model.warnings = buildWarnings(model);
+    return model;
+}
+function parseField(line, lineNumber, documentation, oneof) {
+    if (line.startsWith('option ') || line.startsWith('extensions '))
+        return null;
+    let candidate = line;
+    let label = '';
+    const labeled = candidate.match(labeledFieldPattern);
+    if (labeled) {
+        label = labeled[1];
+        candidate = labeled[2];
+    }
+    const match = candidate.match(declarationPattern);
+    if (!match)
+        return null;
+    const type = match[1];
+    return { name: match[2], type, label, number: Number(match[3]), repeated: label === 'repeated', optional: label === 'optional', map: type.startsWith('map<'), ...(oneof ? { oneof } : {}), options: match[4]?.split(',').map(v => v.trim()).filter(Boolean) ?? [], documentation, line: lineNumber };
+}
+export function flattenProtoMessages(messages) { return messages.flatMap(message => [message, ...flattenProtoMessages(message.messages)]); }
+export function allProtoTypes(model) { const messages = flattenProtoMessages(model.messages); return [...messages, ...model.enums, ...messages.flatMap(message => message.enums), ...model.services]; }
+function buildStats(model) { const messages = flattenProtoMessages(model.messages); return { messages: messages.length, enums: model.enums.length + messages.reduce((n, m) => n + m.enums.length, 0), services: model.services.length, rpcs: model.services.reduce((n, s) => n + s.rpcs.length, 0), fields: messages.reduce((n, m) => n + m.fields.length, 0), imports: model.imports.length }; }
+function buildWarnings(model) { const warnings = []; const messages = flattenProtoMessages(model.messages); const names = new Set([...messages.map(m => m.fullName), ...model.enums.map(e => e.fullName), ...messages.flatMap(m => m.enums.map(e => e.fullName))]); const shorts = new Set([...names].map(n => n.split('.').at(-1))); for (const message of messages) {
+    const numbers = new Map();
+    for (const field of message.fields) {
+        const previous = numbers.get(field.number);
+        if (previous)
+            warnings.push(`${message.fullName} reuses field number ${field.number} for ${previous} and ${field.name}.`);
+        numbers.set(field.number, field.name);
+    }
+} for (const ref of model.references.filter(r => r.fromKind !== 'import')) {
+    const target = cleanType(ref.to);
+    if (!scalarTypes.has(target) && !names.has(target) && !shorts.has(target.split('.').at(-1)))
+        warnings.push(`${ref.from} references ${ref.to} on line ${ref.line}, but it is not declared in this file.`);
+} if (!model.syntax)
+    warnings.push('No syntax declaration found.'); return warnings; }
+function qualify(name, prefix) { return prefix ? `${prefix}.${name}` : name; }
+function cleanType(type) { return type.replace(/^\./, '').trim(); }
+function cleanDocLine(value) { return value.replace(/^\s*\*\s?/, '').trim(); }
+function count(value, char) { return [...value].filter(v => v === char).length; }
+function stripInlineComment(line) { let quoted = false; for (let i = 0; i < line.length - 1; i++) {
+    if (line[i] === '"' && line[i - 1] !== '\\')
+        quoted = !quoted;
+    if (!quoted && line[i] === '/' && line[i + 1] === '/')
+        return line.slice(0, i);
+} return line; }

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

@@ -0,0 +1,16 @@
+export interface PsdHeader {
+    version: 1 | 2;
+    channels: number;
+    height: number;
+    width: number;
+    depth: number;
+    colorMode: number;
+    colorModeName: string;
+    pixelCount: number;
+    warnings: string[];
+}
+export interface PsdParseOptions {
+    maxBytes?: number;
+    maxPixels?: number;
+}
+export declare function parsePsdHeader(data: Uint8Array, options?: PsdParseOptions): PsdHeader;

package/dist/parsers/psd/index.js

@@ -0,0 +1,10 @@
+const MODES = { 0: 'Bitmap', 1: 'Grayscale', 2: 'Indexed', 3: 'RGB', 4: 'CMYK', 7: 'Multichannel', 8: 'Duotone', 9: 'Lab' };
+export function parsePsdHeader(data, options = {}) { const maxBytes = options.maxBytes ?? 128 * 1024 * 1024; if (data.byteLength > maxBytes)
+    throw new Error(`PSD exceeds the ${maxBytes.toLocaleString()} byte limit.`); if (data.length < 26)
+    throw new Error('PSD header is truncated.'); const sig = String.fromCharCode(...data.subarray(0, 4)); if (sig !== '8BPS')
+    throw new Error('Invalid PSD signature.'); const v = new DataView(data.buffer, data.byteOffset, data.byteLength), version = v.getUint16(4, false); if (version !== 1 && version !== 2)
+    throw new Error(`Unsupported PSD version ${version}.`); const channels = v.getUint16(12, false), height = v.getUint32(14, false), width = v.getUint32(18, false), depth = v.getUint16(22, false), colorMode = v.getUint16(24, false), pixelCount = width * height, maxPixels = options.maxPixels ?? 100_000_000; if (!width || !height || width > (version === 1 ? 30_000 : 300_000) || height > (version === 1 ? 30_000 : 300_000))
+    throw new Error('Invalid PSD canvas dimensions.'); if (pixelCount > maxPixels)
+    throw new Error(`PSD canvas exceeds the ${maxPixels.toLocaleString()} pixel limit.`); const warnings = []; if (![1, 8, 16, 32].includes(depth))
+    warnings.push(`Unusual channel depth: ${depth} bits.`); if (!MODES[colorMode])
+    warnings.push(`Unknown color mode ${colorMode}.`); return { version: version, channels, height, width, depth, colorMode, colorModeName: MODES[colorMode] ?? 'Unknown', pixelCount, warnings }; }

package/dist/parsers/shapefile/dbf.d.ts

@@ -0,0 +1,23 @@
+export type DbfValue = string | number | boolean | null;
+export interface DbfField {
+    name: string;
+    /** dBASE type code: C(haracter), N(umeric), F(loat), L(ogical), D(ate)… */
+    type: string;
+    length: number;
+    decimals: number;
+}
+export interface DbfTable {
+    fields: DbfField[];
+    records: Array<Record<string, DbfValue>>;
+    recordCount: number;
+    warnings: string[];
+}
+export interface DbfParseOptions {
+    maxBytes?: number;
+    maxRecords?: number;
+    /** Text encoding of character fields. DBF predates Unicode; utf-8 with
+     *  latin-1 fallback covers the practical corpus. */
+    encoding?: string;
+    signal?: AbortSignal;
+}
+export declare function parseDbf(data: Uint8Array, options?: DbfParseOptions): DbfTable;

package/dist/parsers/shapefile/dbf.js

@@ -0,0 +1,112 @@
+// dBASE (.dbf) attribute table parser — the sidecar that carries per-feature
+// attributes for an ESRI Shapefile. Record order matches .shp record order.
+const FIELD_DESCRIPTOR_SIZE = 32;
+const HEADER_TERMINATOR = 0x0d;
+const DELETED_FLAG = 0x2a;
+export function parseDbf(data, options = {}) {
+    const maxBytes = options.maxBytes ?? 64 * 1024 * 1024;
+    const maxRecords = options.maxRecords ?? 10_000;
+    if (options.signal?.aborted)
+        throw new Error('aborted');
+    if (data.byteLength > maxBytes)
+        throw new Error(`DBF exceeds the ${maxBytes.toLocaleString()} byte limit.`);
+    if (data.byteLength < 32)
+        throw new Error('DBF header is truncated.');
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const declaredRecords = view.getUint32(4, true);
+    const headerSize = view.getUint16(8, true);
+    const recordSize = view.getUint16(10, true);
+    if (headerSize < 33 || headerSize > data.byteLength)
+        throw new Error('DBF header size is invalid.');
+    if (recordSize < 1)
+        throw new Error('DBF record size is invalid.');
+    const decoder = createDecoder(options.encoding);
+    const warnings = [];
+    const fields = [];
+    let cursor = 32;
+    while (cursor + FIELD_DESCRIPTOR_SIZE <= headerSize && data[cursor] !== HEADER_TERMINATOR) {
+        const nameBytes = data.subarray(cursor, cursor + 11);
+        const nul = nameBytes.indexOf(0);
+        const name = decoder.decode(nameBytes.subarray(0, nul === -1 ? 11 : nul)).trim();
+        fields.push({
+            name: name || `FIELD_${fields.length}`,
+            type: String.fromCharCode(data[cursor + 11]),
+            length: data[cursor + 16],
+            decimals: data[cursor + 17]
+        });
+        cursor += FIELD_DESCRIPTOR_SIZE;
+    }
+    if (fields.length === 0)
+        throw new Error('DBF contains no field descriptors.');
+    const fieldsSize = fields.reduce((sum, field) => sum + field.length, 0);
+    if (fieldsSize + 1 > recordSize)
+        warnings.push('DBF field lengths exceed the declared record size.');
+    const records = [];
+    let offset = headerSize;
+    let truncated = false;
+    while (offset + recordSize <= data.byteLength && records.length < maxRecords) {
+        if (options.signal?.aborted)
+            throw new Error('aborted');
+        if (data[offset] === 0x1a)
+            break; // EOF marker
+        const deleted = data[offset] === DELETED_FLAG;
+        if (!deleted) {
+            const record = {};
+            let at = offset + 1;
+            for (const field of fields) {
+                if (at + field.length > data.byteLength) {
+                    truncated = true;
+                    break;
+                }
+                record[field.name] = decodeValue(decoder.decode(data.subarray(at, at + field.length)), field);
+                at += field.length;
+            }
+            if (truncated)
+                break;
+            records.push(record);
+        }
+        offset += recordSize;
+    }
+    if (truncated)
+        warnings.push('DBF parsing stopped at a truncated record.');
+    if (declaredRecords > maxRecords && records.length >= maxRecords) {
+        warnings.push(`Attribute preview is limited to ${maxRecords.toLocaleString()} of ${declaredRecords.toLocaleString()} records.`);
+    }
+    else if (records.length < declaredRecords && !truncated) {
+        warnings.push(`DBF declares ${declaredRecords.toLocaleString()} records; ${records.length.toLocaleString()} were readable.`);
+    }
+    return { fields, records, recordCount: declaredRecords, warnings };
+}
+function decodeValue(raw, field) {
+    const text = raw.replace(/\0/g, '').trim();
+    switch (field.type) {
+        case 'N':
+        case 'F': {
+            if (!text)
+                return null;
+            const value = Number(text);
+            return Number.isFinite(value) ? value : null;
+        }
+        case 'L':
+            if (/^[YyTt]$/.test(text))
+                return true;
+            if (/^[NnFf]$/.test(text))
+                return false;
+            return null;
+        case 'D':
+            return /^\d{8}$/.test(text) ? `${text.slice(0, 4)}-${text.slice(4, 6)}-${text.slice(6, 8)}` : (text || null);
+        default:
+            return text;
+    }
+}
+function createDecoder(encoding) {
+    for (const candidate of [encoding, 'utf-8', 'latin1']) {
+        if (!candidate)
+            continue;
+        try {
+            return new TextDecoder(candidate);
+        }
+        catch { /* try next */ }
+    }
+    return new TextDecoder();
+}

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

@@ -0,0 +1,44 @@
+export type ShpPosition = [number, number];
+export type ShpGeometry = {
+    type: 'Point';
+    coordinates: ShpPosition;
+} | {
+    type: 'MultiPoint';
+    coordinates: ShpPosition[];
+} | {
+    type: 'LineString';
+    coordinates: ShpPosition[];
+} | 
+/** First ring is the outer boundary; remaining rings are holes. */
+{
+    type: 'Polygon';
+    coordinates: ShpPosition[][];
+} | {
+    type: 'MultiLineString';
+    coordinates: ShpPosition[][];
+} | 
+/** Each polygon contains an outer ring followed by zero or more holes. */
+{
+    type: 'MultiPolygon';
+    coordinates: ShpPosition[][][];
+};
+export interface ShapefileFeature {
+    id: number;
+    geometry: ShpGeometry | null;
+}
+export interface ShapefileModel {
+    shapeType: number;
+    shapeTypeName: string;
+    fileLengthBytes: number;
+    bbox: [number, number, number, number] | null;
+    features: ShapefileFeature[];
+    vertexCount: number;
+    warnings: string[];
+}
+export interface ShapefileParseOptions {
+    maxBytes?: number;
+    maxFeatures?: number;
+    maxVertices?: number;
+    signal?: AbortSignal;
+}
+export declare function parseShapefile(data: Uint8Array, options?: ShapefileParseOptions): ShapefileModel;