omni-viewer-core 0.6.0 → 0.7.0

package/README.md

@@ -63,6 +63,26 @@ Viewers follow the same pattern — a `mount*Viewer(input, container, ctx,
 deps)` entry per format, plus `self-loading` variants that dynamically import
 their own dependencies for hosts that don't want to wire them manually.
 
+### Safetensors large-file input
+
+Pass browser `File`/`Blob` objects through the lazy source helper so only the
+8-byte length prefix and JSON header are read:
+
+```ts
+import {
+    createSafetensorsBlobSource,
+    mountSafetensorsViewer
+} from 'omni-viewer-core/viewers/safetensors';
+
+const source = createSafetensorsBlobSource(file, file.name);
+await mountSafetensorsViewer(source, container, ctx);
+```
+
+Node hosts can use `parseSafetensorsFile` from
+`omni-viewer-core/parsers/safetensors/node` and mount the returned document
+with `mountSafetensorsDocument`. The legacy `Uint8Array` input remains
+available, but it requires the host to load the complete file first.
+
 ### PDF host integration
 
 The PDF viewer asks `ctx.assets.resolveAssetUrl` for the exact key

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

@@ -16,6 +16,17 @@ export interface SafetensorsDocument {
     rawPreview?: string | undefined;
     warnings: string[];
 }
+/** Random-access source used to inspect a safetensors file without loading its payload. */
+export interface SafetensorsSource {
+    /** Complete file size in bytes. */
+    readonly size: number;
+    /** Reads up to `length` bytes at the absolute `offset`. */
+    read(offset: number, length: number, signal?: AbortSignal): Uint8Array | Promise<Uint8Array>;
+}
+export interface SafetensorsSourceParseOptions {
+    fileSize?: string;
+    signal?: AbortSignal;
+}
 /** One tensor as declared in the safetensors header. */
 export interface SafetensorsTensor {
     name: string;
@@ -29,6 +40,17 @@ export interface SafetensorsTensor {
     byteLength: number;
 }
 export declare function parseSafetensors(input: Uint8Array, fileSize?: string): SafetensorsDocument;
+/**
+ * Reads and parses only the safetensors header from a random-access source.
+ * The tensor payload range is validated against `source.size` but never read.
+ */
+export declare function parseSafetensorsSource(source: SafetensorsSource, options?: SafetensorsSourceParseOptions): Promise<SafetensorsDocument>;
+/**
+ * Parses bytes containing the 8-byte length prefix and complete JSON header.
+ * `totalFileBytes` is the size of the original file and is used to validate
+ * tensor offsets without requiring tensor payload bytes in `input`.
+ */
+export declare function parseSafetensorsHeader(input: Uint8Array, totalFileBytes: number, fileSize?: string): SafetensorsDocument;
 /** Compact parameter counts, e.g. 1.20B, 350.0M, 12.3K. */
 export declare function formatCount(count: number): string;
 export declare function formatFileSize(bytes: number): string;

package/dist/parsers/safetensors/index.js

@@ -3,9 +3,10 @@
  *
  * The format is a fixed 8-byte little-endian header length, followed by a UTF-8
  * JSON header (tensor name → {dtype, shape, data_offsets}, plus an optional
- * "__metadata__" string map), followed by the raw tensor buffer. Only the header
- * is decoded here — the tensor payloads are never read, so inspecting a
- * multi-gigabyte checkpoint stays cheap.
+ * "__metadata__" string map), followed by the raw tensor buffer. Use
+ * {@link parseSafetensorsSource} for large files: it reads only the 8-byte length
+ * prefix and JSON header. {@link parseSafetensors} remains the compatibility API
+ * for callers that already have the complete file in memory.
  *
  * Reference: https://github.com/huggingface/safetensors
  */
@@ -25,19 +26,65 @@ const DTYPE_BITS = {
     F6_E2M3: 6, F6_E3M2: 6, F4: 4
 };
 export function parseSafetensors(input, fileSize = formatFileSize(input.byteLength)) {
+    return parseSafetensorsHeader(input, input.byteLength, fileSize);
+}
+/**
+ * Reads and parses only the safetensors header from a random-access source.
+ * The tensor payload range is validated against `source.size` but never read.
+ */
+export async function parseSafetensorsSource(source, options = {}) {
+    const fileSize = options.fileSize ?? formatFileSize(source.size);
+    if (!Number.isSafeInteger(source.size) || source.size < 0) {
+        return invalid(fileSize, 'File size is out of range.');
+    }
+    throwIfAborted(options.signal);
+    const prefix = await source.read(0, HEADER_LENGTH_BYTES, options.signal);
+    throwIfAborted(options.signal);
+    if (prefix.byteLength < HEADER_LENGTH_BYTES) {
+        return invalid(fileSize, 'File is too small to contain a safetensors header.');
+    }
+    const headerLength = readHeaderLength(prefix);
+    const lengthIssue = validateHeaderLength(headerLength);
+    if (lengthIssue)
+        return invalid(fileSize, lengthIssue);
+    const headerEnd = HEADER_LENGTH_BYTES + headerLength;
+    if (headerEnd > source.size) {
+        return invalid(fileSize, 'Declared header length extends past the end of the file.');
+    }
+    const jsonHeader = await source.read(HEADER_LENGTH_BYTES, headerLength, options.signal);
+    throwIfAborted(options.signal);
+    if (jsonHeader.byteLength < headerLength) {
+        return invalid(fileSize, 'The complete safetensors header could not be read.');
+    }
+    const headerBytes = new Uint8Array(headerEnd);
+    headerBytes.set(prefix.subarray(0, HEADER_LENGTH_BYTES));
+    headerBytes.set(jsonHeader.subarray(0, headerLength), HEADER_LENGTH_BYTES);
+    return parseSafetensorsHeader(headerBytes, source.size, fileSize);
+}
+/**
+ * Parses bytes containing the 8-byte length prefix and complete JSON header.
+ * `totalFileBytes` is the size of the original file and is used to validate
+ * tensor offsets without requiring tensor payload bytes in `input`.
+ */
+export function parseSafetensorsHeader(input, totalFileBytes, fileSize = formatFileSize(totalFileBytes)) {
     const warnings = [];
     if (input.byteLength < HEADER_LENGTH_BYTES) {
         return invalid(fileSize, 'File is too small to contain a safetensors header.');
     }
-    const view = new DataView(input.buffer, input.byteOffset, input.byteLength);
-    const headerLength = Number(view.getBigUint64(0, true));
-    if (!Number.isSafeInteger(headerLength) || headerLength <= 0 || headerLength > MAX_HEADER_BYTES) {
-        return invalid(fileSize, 'Header length is out of range; the file is not a valid safetensors file.');
+    if (!Number.isSafeInteger(totalFileBytes) || totalFileBytes < 0) {
+        return invalid(fileSize, 'File size is out of range.');
     }
+    const headerLength = readHeaderLength(input);
+    const lengthIssue = validateHeaderLength(headerLength);
+    if (lengthIssue)
+        return invalid(fileSize, lengthIssue);
     const headerEnd = HEADER_LENGTH_BYTES + headerLength;
-    if (headerEnd > input.byteLength) {
+    if (headerEnd > totalFileBytes) {
         return invalid(fileSize, 'Declared header length extends past the end of the file.');
     }
+    if (headerEnd > input.byteLength) {
+        return invalid(fileSize, 'The complete safetensors header could not be read.');
+    }
     const headerBytes = input.subarray(HEADER_LENGTH_BYTES, headerEnd);
     if (headerBytes[0] !== 0x7b) {
         return invalid(fileSize, 'The safetensors header must begin with a JSON object.');
@@ -72,7 +119,7 @@ export function parseSafetensors(input, fileSize = formatFileSize(input.byteLeng
     }
     if (metadataIssue)
         warnings.push('Some "__metadata__" values are not strings and were ignored.');
-    const dataBufferSize = input.byteLength - headerEnd;
+    const dataBufferSize = totalFileBytes - headerEnd;
     const tensors = [];
     const dtypeCounts = new Map();
     let totalElements = 0;
@@ -184,6 +231,20 @@ export function parseSafetensors(input, fileSize = formatFileSize(input.byteLeng
         warnings
     };
 }
+function readHeaderLength(input) {
+    const view = new DataView(input.buffer, input.byteOffset, input.byteLength);
+    return Number(view.getBigUint64(0, true));
+}
+function validateHeaderLength(headerLength) {
+    return !Number.isSafeInteger(headerLength) || headerLength <= 0 || headerLength > MAX_HEADER_BYTES
+        ? 'Header length is out of range; the file is not a valid safetensors file.'
+        : undefined;
+}
+function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    throw signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+}
 function safeElementCount(shape) {
     let count = 1;
     for (const dimension of shape) {

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

@@ -0,0 +1,13 @@
+import { type SafetensorsDocument, type SafetensorsSource } from './index.js';
+/** File-descriptor-backed source that reads only requested safetensors ranges. */
+export declare class SafetensorsFileSource implements SafetensorsSource {
+    private readonly fd;
+    readonly size: number;
+    private closed;
+    private constructor();
+    static open(filePath: string): SafetensorsFileSource;
+    read(offset: number, length: number, signal?: AbortSignal): Uint8Array;
+    close(): void;
+}
+/** Parses a safetensors file after reading only its length prefix and JSON header. */
+export declare function parseSafetensorsFile(filePath: string, fileSize?: string): Promise<SafetensorsDocument>;

package/dist/parsers/safetensors/node.js

@@ -0,0 +1,52 @@
+import * as fs from 'node:fs';
+import { formatFileSize, parseSafetensorsSource } from './index.js';
+const EMPTY = new Uint8Array(0);
+/** File-descriptor-backed source that reads only requested safetensors ranges. */
+export class SafetensorsFileSource {
+    fd;
+    size;
+    closed = false;
+    constructor(fd, size) {
+        this.fd = fd;
+        this.size = size;
+    }
+    static open(filePath) {
+        const fd = fs.openSync(filePath, 'r');
+        try {
+            return new SafetensorsFileSource(fd, fs.fstatSync(fd).size);
+        }
+        catch (error) {
+            fs.closeSync(fd);
+            throw error;
+        }
+    }
+    read(offset, length, signal) {
+        if (this.closed)
+            throw new Error('Safetensors source is closed');
+        if (signal?.aborted)
+            throw signal.reason ?? new Error('The operation was aborted.');
+        const start = Math.max(0, offset);
+        const end = Math.min(start + Math.max(0, length), this.size);
+        if (end <= start)
+            return EMPTY;
+        const bytes = new Uint8Array(end - start);
+        const bytesRead = fs.readSync(this.fd, bytes, 0, bytes.byteLength, start);
+        return bytesRead === bytes.byteLength ? bytes : bytes.subarray(0, bytesRead);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        fs.closeSync(this.fd);
+    }
+}
+/** Parses a safetensors file after reading only its length prefix and JSON header. */
+export async function parseSafetensorsFile(filePath, fileSize) {
+    const source = SafetensorsFileSource.open(filePath);
+    try {
+        return await parseSafetensorsSource(source, { fileSize: fileSize ?? formatFileSize(source.size) });
+    }
+    finally {
+        source.close();
+    }
+}

package/dist/viewers/safetensors/index.d.ts

@@ -1,5 +1,5 @@
 import type { ClipboardService, HostContext } from '../../host/index.js';
-import { type SafetensorsDocument } from '../../parsers/safetensors/index.js';
+import { type SafetensorsDocument, type SafetensorsSource } from '../../parsers/safetensors/index.js';
 import { type MountOptions, type ViewerHandle, type ViewerInput } from '../types.js';
 export { safetensorsViewerCss } from './styles.js';
 export declare const SAFETENSORS_VIEWER_META: {
@@ -14,6 +14,14 @@ export declare const SAFETENSORS_VIEWER_META: {
 export type SafetensorsViewerContext = HostContext & {
     clipboard?: ClipboardService;
 };
+/** Lazy input used by large-file hosts to avoid materializing tensor payloads. */
+export interface SafetensorsViewerSource extends SafetensorsSource {
+    fileName: string;
+    lastModified?: number;
+}
+/** Creates a lazy safetensors input backed by browser `Blob.slice()` range reads. */
+export declare function createSafetensorsBlobSource(blob: Blob, fileName?: string): SafetensorsViewerSource;
 export declare function mountSafetensorsViewer(input: ViewerInput, container: HTMLElement, ctx: SafetensorsViewerContext, options?: MountOptions): Promise<ViewerHandle>;
+export declare function mountSafetensorsViewer(input: SafetensorsViewerSource, container: HTMLElement, ctx: SafetensorsViewerContext, options?: MountOptions): Promise<ViewerHandle>;
 /** Mount a pre-parsed model, allowing Node adapters to retain random-access parsing. */
 export declare function mountSafetensorsDocument(document: SafetensorsDocument, fileName: string, container: HTMLElement, ctx: SafetensorsViewerContext, options?: MountOptions): ViewerHandle;

package/dist/viewers/safetensors/index.js

@@ -1,4 +1,4 @@
-import { parseSafetensors } from '../../parsers/safetensors/index.js';
+import { parseSafetensors, parseSafetensorsSource } from '../../parsers/safetensors/index.js';
 import { MountAbortedError, VIEWER_ROOT_CLASS } from '../types.js';
 import { safetensorsViewerCss } from './styles.js';
 export { safetensorsViewerCss } from './styles.js';
@@ -11,10 +11,33 @@ export const SAFETENSORS_VIEWER_META = {
     optionalServices: ['clipboard'],
     inputOwnership: 'borrows'
 };
+/** Creates a lazy safetensors input backed by browser `Blob.slice()` range reads. */
+export function createSafetensorsBlobSource(blob, fileName = 'model.safetensors') {
+    return {
+        fileName,
+        size: blob.size,
+        async read(offset, length, signal) {
+            throwIfAborted(signal);
+            const bytes = new Uint8Array(await blob.slice(offset, offset + length).arrayBuffer());
+            throwIfAborted(signal);
+            return bytes;
+        }
+    };
+}
 export async function mountSafetensorsViewer(input, container, ctx, options = {}) {
     if (options.signal?.aborted)
         throw new MountAbortedError();
-    const document = parseSafetensors(input.data);
+    let document;
+    try {
+        document = 'data' in input
+            ? parseSafetensors(input.data)
+            : await parseSafetensorsSource(input, { ...(options.signal ? { signal: options.signal } : {}) });
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw new MountAbortedError();
+        throw error;
+    }
     if (options.signal?.aborted)
         throw new MountAbortedError();
     return mountSafetensorsDocument(document, input.fileName, container, ctx, options);
@@ -168,3 +191,8 @@ function element(tag, className, text) {
         node.textContent = text;
     return node;
 }
+function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    throw signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omni-viewer-core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Shared parsing + rendering core for Omni Viewer (vscode / chrome / obsidian / web)",
   "type": "module",
   "license": "MIT",
@@ -145,6 +145,10 @@
       "types": "./dist/parsers/safetensors/index.d.ts",
       "default": "./dist/parsers/safetensors/index.js"
     },
+    "./parsers/safetensors/node": {
+      "types": "./dist/parsers/safetensors/node.d.ts",
+      "default": "./dist/parsers/safetensors/node.js"
+    },
     "./viewers/types": {
       "types": "./dist/viewers/types.d.ts",
       "default": "./dist/viewers/types.js"