omni-viewer-core 0.1.0

package/dist/parsers/hdf5/index.js

@@ -0,0 +1,658 @@
+/**
+ * Minimal HDF5 (.h5/.hdf5) structure reader.
+ *
+ * It validates the file signature, decodes the superblock and walks the object
+ * header hierarchy to enumerate the groups and datasets stored in the file.
+ *
+ * Only metadata (superblock, B-trees, local heaps, object headers) is read, and
+ * it is read on demand through an {@link Hdf5Reader} rather than by loading the
+ * whole file. This keeps inspection of multi-gigabyte/terabyte HDF5 files cheap
+ * because the large dataset payloads are never touched.
+ *
+ * Superblock versions 0 and 1 use the classic B-tree + local heap + symbol
+ * table layout and are traversed fully. Superblock versions 2 and 3 use version
+ * 2 object headers ("OHDR"); compact link messages are decoded, while groups
+ * that keep their links in a fractal heap (dense storage) are reported with a
+ * warning because that index is not walked here.
+ */
+const HDF5_SIGNATURE = [0x89, 0x48, 0x44, 0x46, 0x0d, 0x0a, 0x1a, 0x0a];
+const UNDEFINED_ADDRESS = -1;
+const EMPTY = new Uint8Array(0);
+const MAX_ENTRIES = 5000;
+const MAX_DEPTH = 64;
+const MAX_NODES = 20000;
+// Object header message blocks are tiny; cap reads to guard against corrupt sizes.
+const MAX_BLOCK_BYTES = 32 * 1024 * 1024;
+/** Reader backed by an in-memory byte array. */
+export class Hdf5Uint8ArrayReader {
+    buffer;
+    size;
+    constructor(buffer) {
+        this.buffer = buffer;
+        this.size = buffer.length;
+    }
+    read(offset, length) {
+        const start = Math.max(0, offset);
+        const end = Math.min(offset + length, this.size);
+        return end <= start ? EMPTY : this.buffer.subarray(start, end);
+    }
+    close() {
+        // Nothing to release for an in-memory buffer.
+    }
+}
+const DATATYPE_CLASS_NAMES = {
+    0: 'Integer',
+    1: 'Float',
+    2: 'Time',
+    3: 'String',
+    4: 'Bitfield',
+    5: 'Opaque',
+    6: 'Compound',
+    7: 'Reference',
+    8: 'Enum',
+    9: 'Variable-length',
+    10: 'Array'
+};
+// HDF5 object header message type identifiers.
+const MSG_DATASPACE = 0x0001;
+const MSG_DATATYPE = 0x0003;
+const MSG_LINK = 0x0006;
+const MSG_DATA_LAYOUT = 0x0008;
+const MSG_CONTINUATION = 0x0010;
+const MSG_SYMBOL_TABLE = 0x0011;
+export class Hdf5Parser {
+    reader;
+    entries = [];
+    warnings = [];
+    superblock = null;
+    nodeBudget = MAX_NODES;
+    truncated = false;
+    constructor(reader) {
+        this.reader = reader;
+    }
+    /** Parses HDF5 metadata through a random-access reader without reading dataset payloads. */
+    static parseReader(reader, fileSize = formatFileSize(reader.size)) {
+        return new Hdf5Parser(reader).build(fileSize);
+    }
+    /** Parses an in-memory HDF5 byte array. */
+    static parse(buffer, fileSize = formatFileSize(buffer.byteLength)) {
+        return new Hdf5Parser(new Hdf5Uint8ArrayReader(buffer)).build(fileSize);
+    }
+    build(fileSize) {
+        const signatureOffset = this.findSignature();
+        if (signatureOffset < 0) {
+            return {
+                format: 'HDF5',
+                title: 'Hierarchical Data Format 5',
+                fileSize,
+                summary: [{ label: 'Signature', value: 'not found' }],
+                tables: [this.headerPreviewTable()],
+                warnings: ['The file does not start with the expected HDF5 signature (\\x89HDF\\r\\n\\x1a\\n).']
+            };
+        }
+        try {
+            this.superblock = this.parseSuperblock(signatureOffset);
+            if (this.superblock.rootHeaderAddress !== UNDEFINED_ADDRESS) {
+                this.visitObject(this.superblock.rootHeaderAddress, '/', 0, new Set());
+            }
+        }
+        catch (error) {
+            this.warnings.push(`Structure parsing stopped: ${error instanceof Error ? error.message : 'unknown error'}.`);
+        }
+        return this.toModel(fileSize);
+    }
+    toModel(fileSize) {
+        const sb = this.superblock;
+        const datasets = this.entries.filter(entry => entry.kind === 'Dataset');
+        const groups = this.entries.filter(entry => entry.kind === 'Group');
+        const summary = [
+            { label: 'Superblock version', value: sb ? sb.version : '-' },
+            { label: 'Groups', value: groups.length },
+            { label: 'Datasets', value: datasets.length },
+            { label: 'Size of offsets', value: sb ? sb.sizeOfOffsets : '-' }
+        ];
+        const tables = [];
+        if (sb) {
+            tables.push({
+                title: 'Superblock',
+                headers: ['Field', 'Value'],
+                rows: [
+                    ['Version', sb.version],
+                    ['Size of offsets', sb.sizeOfOffsets],
+                    ['Size of lengths', sb.sizeOfLengths],
+                    ['Base address', formatAddress(sb.baseAddress)],
+                    ['End of file address', formatAddress(sb.endOfFile)],
+                    ['Root group header', formatAddress(sb.rootHeaderAddress)]
+                ]
+            });
+        }
+        tables.push({
+            title: `Datasets (${datasets.length})`,
+            headers: ['Path', 'Shape', 'Type', 'Element bytes'],
+            rows: datasets.length > 0
+                ? datasets.map(entry => [entry.path, entry.shape, entry.type, entry.elementSize])
+                : [['-', '-', 'No datasets were decoded from the file structure.', '-']]
+        });
+        tables.push({
+            title: `Groups (${groups.length})`,
+            headers: ['Path', 'Kind'],
+            rows: groups.length > 0
+                ? groups.map(entry => [entry.path, entry.kind])
+                : [['/', 'Group']]
+        });
+        tables.push(this.headerPreviewTable());
+        const warnings = [...this.warnings];
+        if (this.truncated || this.nodeBudget <= 0) {
+            warnings.push('Traversal stopped early because the file structure exceeded the inspection limits.');
+        }
+        if (sb && (sb.version === 2 || sb.version === 3)) {
+            warnings.push('Superblock version 2/3 detected: links stored in dense (fractal heap) indexes are not enumerated.');
+        }
+        return {
+            format: 'HDF5',
+            title: 'Hierarchical Data Format 5',
+            fileSize,
+            summary,
+            tables,
+            rawPreview: this.buildTreePreview(),
+            warnings
+        };
+    }
+    headerPreviewTable() {
+        const preview = this.reader.read(0, 256);
+        return {
+            title: 'Header preview',
+            headers: ['Offset', 'Hex', 'ASCII'],
+            rows: hexRows(preview, 0, preview.length)
+        };
+    }
+    buildTreePreview() {
+        if (this.entries.length === 0) {
+            return undefined;
+        }
+        const lines = this.entries
+            .slice()
+            .sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)
+            .map(entry => {
+            const depth = entry.path === '/' ? 0 : entry.path.split('/').filter(Boolean).length;
+            const indent = '  '.repeat(Math.max(0, depth));
+            const name = entry.path === '/' ? '/' : entry.path.split('/').filter(Boolean).pop() ?? entry.path;
+            if (entry.kind === 'Dataset') {
+                return `${indent}${name}  [${entry.shape}] ${entry.type}`;
+            }
+            return `${indent}${name}/`;
+        });
+        const text = lines.join('\n');
+        return text.length > 20000 ? `${text.slice(0, 20000)}\n\n... preview truncated ...` : text;
+    }
+    findSignature() {
+        let offset = 0;
+        while (offset + HDF5_SIGNATURE.length <= this.reader.size) {
+            const buf = this.reader.read(offset, HDF5_SIGNATURE.length);
+            if (buf.length === HDF5_SIGNATURE.length && HDF5_SIGNATURE.every((byte, index) => buf[index] === byte)) {
+                return offset;
+            }
+            // The signature may follow a user block placed at 0, 512, 1024, 2048, ...
+            offset = offset === 0 ? 512 : offset * 2;
+        }
+        return -1;
+    }
+    parseSuperblock(offset) {
+        const sb = this.reader.read(offset, 256);
+        if (sb.length < 12)
+            throw new Error('truncated superblock');
+        const version = byteAt(sb, 8);
+        if (version === 0 || version === 1) {
+            const sizeOfOffsets = byteAt(sb, 13);
+            const sizeOfLengths = byteAt(sb, 14);
+            this.validateAddressSizes(sizeOfOffsets, sizeOfLengths);
+            let p = 24;
+            if (version === 1) {
+                p += 4; // Indexed storage internal node K (2 bytes) + reserved (2 bytes)
+            }
+            const baseAddress = readOffsetBuf(sb, p, sizeOfOffsets);
+            p += sizeOfOffsets;
+            p += sizeOfOffsets; // Free-space info address
+            const endOfFile = readOffsetBuf(sb, p, sizeOfOffsets);
+            p += sizeOfOffsets;
+            p += sizeOfOffsets; // Driver information block address
+            p += sizeOfOffsets; // Root symbol table entry: link name offset
+            const rootHeaderAddress = readOffsetBuf(sb, p, sizeOfOffsets);
+            return { version, sizeOfOffsets, sizeOfLengths, baseAddress, endOfFile, rootHeaderAddress };
+        }
+        if (version === 2 || version === 3) {
+            const sizeOfOffsets = byteAt(sb, 9);
+            const sizeOfLengths = byteAt(sb, 10);
+            this.validateAddressSizes(sizeOfOffsets, sizeOfLengths);
+            let p = 12;
+            const baseAddress = readOffsetBuf(sb, p, sizeOfOffsets);
+            p += sizeOfOffsets;
+            p += sizeOfOffsets; // Superblock extension address
+            const endOfFile = readOffsetBuf(sb, p, sizeOfOffsets);
+            p += sizeOfOffsets;
+            const rootHeaderAddress = readOffsetBuf(sb, p, sizeOfOffsets);
+            return { version, sizeOfOffsets, sizeOfLengths, baseAddress, endOfFile, rootHeaderAddress };
+        }
+        throw new Error(`unsupported superblock version ${version}`);
+    }
+    validateAddressSizes(sizeOfOffsets, sizeOfLengths) {
+        if (sizeOfOffsets < 1 || sizeOfOffsets > 8 || sizeOfLengths < 1 || sizeOfLengths > 8) {
+            throw new Error('invalid HDF5 offset/length size');
+        }
+    }
+    visitObject(headerAddress, path, depth, ancestors) {
+        if (headerAddress === UNDEFINED_ADDRESS || depth > MAX_DEPTH || this.entries.length >= MAX_ENTRIES) {
+            if (this.entries.length >= MAX_ENTRIES) {
+                this.truncated = true;
+            }
+            return;
+        }
+        if (ancestors.has(headerAddress)) {
+            return; // Guard against cyclic links.
+        }
+        if (--this.nodeBudget <= 0) {
+            this.truncated = true;
+            return;
+        }
+        const messages = this.readObjectHeader(headerAddress);
+        const dataspace = messages.find(message => message.type === MSG_DATASPACE);
+        const datatype = messages.find(message => message.type === MSG_DATATYPE);
+        const hasLayout = messages.some(message => message.type === MSG_DATA_LAYOUT);
+        const symbolTable = messages.find(message => message.type === MSG_SYMBOL_TABLE);
+        const linkMessages = messages.filter(message => message.type === MSG_LINK);
+        const isDataset = Boolean(datatype && (dataspace || hasLayout));
+        if (isDataset) {
+            this.entries.push({
+                path,
+                kind: 'Dataset',
+                shape: dataspace ? this.describeDataspace(dataspace.data) : 'scalar',
+                type: datatype ? this.describeDatatype(datatype.data) : 'unknown',
+                elementSize: datatype ? this.datatypeSize(datatype.data) : 0
+            });
+            return;
+        }
+        // Anything that is not a dataset is treated as a group node.
+        this.entries.push({ path, kind: 'Group', shape: '-', type: '-', elementSize: 0 });
+        const nextAncestors = new Set(ancestors).add(headerAddress);
+        const children = [];
+        if (symbolTable) {
+            children.push(...this.readSymbolTable(symbolTable.data));
+        }
+        for (const link of linkMessages) {
+            const decoded = this.decodeLinkMessage(link.data);
+            if (decoded) {
+                children.push(decoded);
+            }
+        }
+        for (const child of children) {
+            const childPath = path === '/' ? `/${child.name}` : `${path}/${child.name}`;
+            this.visitObject(child.address, childPath, depth + 1, nextAncestors);
+        }
+    }
+    readObjectHeader(address) {
+        const start = this.resolve(address);
+        if (start < 0 || start >= this.reader.size) {
+            return [];
+        }
+        if (this.matchesAscii(start, 'OHDR')) {
+            return this.readObjectHeaderV2(start);
+        }
+        return this.readObjectHeaderV1(start);
+    }
+    readObjectHeaderV1(start) {
+        const prefix = this.reader.read(start, 16);
+        if (prefix.length < 16) {
+            return [];
+        }
+        const totalMessages = readU16(prefix, 2);
+        // 16-byte prefix: version, reserved, message count, ref count, header size, padding.
+        const blocks = [{ offset: start + 16, length: readU32(prefix, 8) }];
+        return this.collectMessages(blocks, totalMessages + 256, { version2: false, creationOrderBytes: 0 });
+    }
+    readObjectHeaderV2(start) {
+        const head = this.reader.read(start, 64);
+        if (head.length < 6) {
+            return [];
+        }
+        const flags = byteAt(head, 5);
+        let p = 6;
+        if (flags & 0x20) {
+            p += 16; // Access, modification, change, and birth times.
+        }
+        if (flags & 0x10) {
+            p += 4; // Max compact / min dense attribute counts.
+        }
+        const chunkSizeBytes = 1 << (flags & 0x03);
+        const chunkSize = readLittleBuf(head, p, chunkSizeBytes);
+        p += chunkSizeBytes;
+        const trackOrder = (flags & 0x04) !== 0;
+        const blocks = [{ offset: start + p, length: chunkSize }];
+        return this.collectMessages(blocks, MAX_ENTRIES, { version2: true, creationOrderBytes: trackOrder ? 2 : 0 });
+    }
+    collectMessages(blocks, maxMessages, options) {
+        const messages = [];
+        const visited = new Set();
+        const headerSize = options.version2 ? 4 : 8;
+        let guard = 0;
+        while (blocks.length > 0 && messages.length < maxMessages && guard++ < 4096) {
+            const block = blocks.shift();
+            const region = this.reader.read(block.offset, Math.min(block.length, MAX_BLOCK_BYTES));
+            let p = 0;
+            while (p + headerSize <= region.length) {
+                const type = options.version2 ? byteAt(region, p) : readU16(region, p);
+                const size = options.version2 ? readU16(region, p + 1) : readU16(region, p + 2);
+                // Version 2 message headers add a creation-order field when the header tracks order.
+                const dataStart = p + headerSize + options.creationOrderBytes;
+                if (dataStart + size > region.length) {
+                    break;
+                }
+                const data = region.subarray(dataStart, dataStart + size);
+                if (type === MSG_CONTINUATION) {
+                    this.queueContinuation(blocks, visited, data, options.version2);
+                }
+                else {
+                    messages.push({ type, data });
+                }
+                p = dataStart + size;
+            }
+        }
+        return messages;
+    }
+    queueContinuation(blocks, visited, data, version2) {
+        const contAddress = readOffsetBuf(data, 0, this.sizeOfOffsets());
+        const contLength = readLittleBuf(data, this.sizeOfOffsets(), this.sizeOfLengths());
+        const contStart = this.resolve(contAddress);
+        if (contAddress === UNDEFINED_ADDRESS || contStart < 0 || visited.has(contStart)) {
+            return;
+        }
+        visited.add(contStart);
+        if (version2) {
+            // Version 2 continuation blocks carry an "OCHK" signature (4 bytes) + trailing checksum (4 bytes).
+            if (!this.matchesAscii(contStart, 'OCHK')) {
+                return;
+            }
+            blocks.push({ offset: contStart + 4, length: Math.max(0, contLength - 8) });
+        }
+        else {
+            blocks.push({ offset: contStart, length: contLength });
+        }
+    }
+    readSymbolTable(data) {
+        const sizeOfOffsets = this.sizeOfOffsets();
+        const btreeAddress = readOffsetBuf(data, 0, sizeOfOffsets);
+        const heapAddress = readOffsetBuf(data, sizeOfOffsets, sizeOfOffsets);
+        const heapDataStart = this.readLocalHeapDataStart(heapAddress);
+        if (heapDataStart < 0) {
+            return [];
+        }
+        const snodAddresses = [];
+        this.collectSymbolTableNodes(btreeAddress, snodAddresses, new Set());
+        const children = [];
+        for (const snodAddress of snodAddresses) {
+            children.push(...this.readSymbolTableNode(snodAddress, heapDataStart));
+        }
+        return children;
+    }
+    collectSymbolTableNodes(address, output, visited) {
+        const start = this.resolve(address);
+        if (address === UNDEFINED_ADDRESS || start < 0 || visited.has(start) || output.length > MAX_ENTRIES) {
+            return;
+        }
+        visited.add(start);
+        if (!this.matchesAscii(start, 'TREE')) {
+            return;
+        }
+        const sizeOfOffsets = this.sizeOfOffsets();
+        const sizeOfLengths = this.sizeOfLengths();
+        // Header: signature(4) + node type(1) + level(1) + entries used(2) + left(off) + right(off).
+        const headerSize = 8 + sizeOfOffsets * 2;
+        const header = this.reader.read(start, headerSize);
+        if (header.length < 8) {
+            return;
+        }
+        const nodeLevel = byteAt(header, 5);
+        const entriesUsed = readU16(header, 6);
+        // Keys and children: key0, [child, key] * entriesUsed. Group-node keys are heap offsets.
+        const regionLength = sizeOfLengths + entriesUsed * (sizeOfOffsets + sizeOfLengths);
+        const region = this.reader.read(start + headerSize, regionLength);
+        let p = sizeOfLengths; // The first key precedes the first child pointer.
+        for (let i = 0; i < entriesUsed; i++) {
+            const childAddress = readOffsetBuf(region, p, sizeOfOffsets);
+            p += sizeOfOffsets + sizeOfLengths; // Child pointer + following key.
+            if (nodeLevel > 0) {
+                this.collectSymbolTableNodes(childAddress, output, visited);
+            }
+            else if (childAddress !== UNDEFINED_ADDRESS) {
+                output.push(childAddress);
+            }
+        }
+    }
+    readSymbolTableNode(address, heapDataStart) {
+        const start = this.resolve(address);
+        if (start < 0 || !this.matchesAscii(start, 'SNOD')) {
+            return [];
+        }
+        const header = this.reader.read(start, 8);
+        if (header.length < 8) {
+            return [];
+        }
+        const count = readU16(header, 6);
+        const sizeOfOffsets = this.sizeOfOffsets();
+        const entrySize = sizeOfOffsets * 2 + 8 + 16; // Name offset + header address + cache type + reserved + scratch pad.
+        const region = this.reader.read(start + 8, count * entrySize);
+        const children = [];
+        for (let i = 0; i < count; i++) {
+            const base = i * entrySize;
+            const nameOffset = readOffsetBuf(region, base, sizeOfOffsets);
+            const headerAddress = readOffsetBuf(region, base + sizeOfOffsets, sizeOfOffsets);
+            const name = this.readHeapString(heapDataStart + nameOffset);
+            if (name && headerAddress !== UNDEFINED_ADDRESS) {
+                children.push({ name, address: headerAddress });
+            }
+        }
+        return children;
+    }
+    readLocalHeapDataStart(address) {
+        const start = this.resolve(address);
+        if (start < 0 || !this.matchesAscii(start, 'HEAP')) {
+            return -1;
+        }
+        const sizeOfOffsets = this.sizeOfOffsets();
+        const sizeOfLengths = this.sizeOfLengths();
+        // signature(4) + version(1) + reserved(3) + data segment size + free-list head + data segment address.
+        const buf = this.reader.read(start + 8 + sizeOfLengths * 2, sizeOfOffsets);
+        const dataSegmentAddress = readOffsetBuf(buf, 0, sizeOfOffsets);
+        return this.resolve(dataSegmentAddress);
+    }
+    decodeLinkMessage(data) {
+        if (data.length < 2 || data[0] !== 1) {
+            return null;
+        }
+        const flags = byteAt(data, 1);
+        let p = 2;
+        let linkType = 0;
+        if (flags & 0x08) {
+            linkType = byteAt(data, p);
+            p += 1;
+        }
+        if (flags & 0x04) {
+            p += 8; // Creation order.
+        }
+        if (flags & 0x10) {
+            p += 1; // Link name character set.
+        }
+        const lengthFieldSize = 1 << (flags & 0x03);
+        if (p + lengthFieldSize > data.length) {
+            return null;
+        }
+        const nameLength = readLittleBuf(data, p, lengthFieldSize);
+        p += lengthFieldSize;
+        if (p + nameLength > data.length) {
+            return null;
+        }
+        const name = decodeUtf8(data.subarray(p, p + nameLength));
+        p += nameLength;
+        if (linkType !== 0) {
+            return null; // Only hard links point straight at an object header.
+        }
+        const address = readOffsetBuf(data, p, this.sizeOfOffsets());
+        if (address === UNDEFINED_ADDRESS) {
+            return null;
+        }
+        return { name, address };
+    }
+    describeDataspace(data) {
+        if (data.length < 2) {
+            return 'scalar';
+        }
+        const version = byteAt(data, 0);
+        const rank = byteAt(data, 1);
+        if (rank === 0) {
+            return 'scalar';
+        }
+        const sizeOfLengths = this.sizeOfLengths();
+        // v1: version, rank, flags, reserved, reserved(4). v2: version, rank, flags, type.
+        let p = version >= 2 ? 4 : 8;
+        const dims = [];
+        for (let i = 0; i < rank && p + sizeOfLengths <= data.length; i++) {
+            dims.push(readLittleBuf(data, p, sizeOfLengths));
+            p += sizeOfLengths;
+        }
+        return dims.length > 0 ? dims.join(' × ') : `rank ${rank}`;
+    }
+    describeDatatype(data) {
+        if (data.length < 1) {
+            return 'unknown';
+        }
+        const classId = byteAt(data, 0) & 0x0f;
+        const name = DATATYPE_CLASS_NAMES[classId] ?? `class ${classId}`;
+        const size = this.datatypeSize(data);
+        if (classId === 0 || classId === 1) {
+            return `${name}${size * 8}`;
+        }
+        return name;
+    }
+    datatypeSize(data) {
+        return data.length >= 8 ? readU32(data, 4) : 0;
+    }
+    readHeapString(offset) {
+        if (offset < 0 || offset >= this.reader.size) {
+            return '';
+        }
+        const buf = this.reader.read(offset, 1024);
+        let end = 0;
+        while (end < buf.length && buf[end] !== 0) {
+            end++;
+        }
+        return decodeUtf8(buf.subarray(0, end));
+    }
+    matchesAscii(offset, signature) {
+        if (offset < 0) {
+            return false;
+        }
+        const buf = this.reader.read(offset, signature.length);
+        if (buf.length < signature.length) {
+            return false;
+        }
+        for (let i = 0; i < signature.length; i++) {
+            if (buf[i] !== signature.charCodeAt(i)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    resolve(address) {
+        if (address === UNDEFINED_ADDRESS) {
+            return -1;
+        }
+        const base = this.superblock ? this.superblock.baseAddress : 0;
+        return address + (base > 0 ? base : 0);
+    }
+    sizeOfOffsets() {
+        return this.superblock ? this.superblock.sizeOfOffsets : 8;
+    }
+    sizeOfLengths() {
+        return this.superblock ? this.superblock.sizeOfLengths : 8;
+    }
+}
+function readOffsetBuf(buffer, offset, size) {
+    if (offset < 0 || offset + size > buffer.length) {
+        return UNDEFINED_ADDRESS;
+    }
+    let allOnes = true;
+    for (let i = 0; i < size; i++) {
+        if (buffer[offset + i] !== 0xff) {
+            allOnes = false;
+            break;
+        }
+    }
+    if (allOnes) {
+        return UNDEFINED_ADDRESS;
+    }
+    return readLittleBuf(buffer, offset, size);
+}
+function readLittleBuf(buffer, offset, size) {
+    if (offset < 0 || offset + size > buffer.length) {
+        return 0;
+    }
+    if (size <= 6) {
+        let value = 0;
+        for (let i = size - 1; i >= 0; i--)
+            value = value * 256 + byteAt(buffer, offset + i);
+        return value;
+    }
+    let value = 0n;
+    for (let i = size - 1; i >= 0; i--) {
+        value = (value << 8n) | BigInt(byteAt(buffer, offset + i));
+    }
+    return value > BigInt(Number.MAX_SAFE_INTEGER) ? Number.MAX_SAFE_INTEGER : Number(value);
+}
+function byteAt(buffer, offset) {
+    return buffer[offset] ?? 0;
+}
+function readU16(buffer, offset) {
+    if (offset < 0 || offset + 2 > buffer.length)
+        return 0;
+    return (buffer[offset] ?? 0) | ((buffer[offset + 1] ?? 0) << 8);
+}
+function readU32(buffer, offset) {
+    if (offset < 0 || offset + 4 > buffer.length)
+        return 0;
+    return ((buffer[offset] ?? 0) | ((buffer[offset + 1] ?? 0) << 8) |
+        ((buffer[offset + 2] ?? 0) << 16) | ((buffer[offset + 3] ?? 0) << 24)) >>> 0;
+}
+function decodeUtf8(buffer) {
+    return new TextDecoder('utf-8', { fatal: false }).decode(buffer);
+}
+export function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return String(bytes) + ' bytes';
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let value = bytes / 1024;
+    let unit = units[0];
+    for (let i = 1; i < units.length && value >= 1024; i++) {
+        value /= 1024;
+        unit = units[i];
+    }
+    return value.toFixed(value >= 10 ? 1 : 2) + ' ' + unit;
+}
+function formatAddress(address) {
+    if (address === UNDEFINED_ADDRESS) {
+        return 'undefined';
+    }
+    return `0x${address.toString(16)}`;
+}
+function hexRows(buffer, start, end) {
+    const rows = [];
+    for (let offset = start; offset < end; offset += 16) {
+        const slice = buffer.subarray(offset, Math.min(offset + 16, end));
+        const hex = Array.from(slice).map(byte => byte.toString(16).padStart(2, '0')).join(' ');
+        const ascii = Array.from(slice).map(byte => (byte >= 32 && byte <= 126 ? String.fromCharCode(byte) : '.')).join('');
+        rows.push([`0x${offset.toString(16).padStart(4, '0')}`, hex, ascii]);
+    }
+    return rows;
+}
+/** Convenience function for adapters and the built-in viewer. */
+export function parseHdf5(input, fileSize = formatFileSize(input.byteLength)) {
+    return Hdf5Parser.parse(input, fileSize);
+}

package/dist/parsers/hdf5/node.d.ts

@@ -0,0 +1,21 @@
+import { type Hdf5Document, type Hdf5Reader } from './index.js';
+/**
+ * File-descriptor-backed random-access reader for Node hosts such as VS Code.
+ * A 4 MiB LRU page cache keeps metadata traversal cheap without loading HDF5
+ * dataset payloads or the complete file into memory.
+ */
+export declare class Hdf5FileReader implements Hdf5Reader {
+    private readonly fd;
+    readonly size: number;
+    private static readonly PAGE_BYTES;
+    private static readonly MAX_PAGES;
+    private readonly cache;
+    private closed;
+    private constructor();
+    static open(filePath: string): Hdf5FileReader;
+    read(offset: number, length: number): Uint8Array;
+    close(): void;
+    private getPage;
+}
+/** Parse an HDF5 file without loading dataset payloads into memory. */
+export declare function parseHdf5File(filePath: string, fileSize?: string): Hdf5Document;