ducjs 2.2.3 → 2.4.0

package/dist/lazy-files.js

@@ -0,0 +1,207 @@
+/**
+ * LazyExternalFileStore — Zero-copy, on-demand access to external file data from a FlatBuffer.
+ *
+ * Instead of eagerly parsing and copying every external file's binary data into JS memory,
+ * this store keeps a reference to the original FlatBuffer Uint8Array and reads file bytes
+ * only when explicitly requested. FlatBuffer `dataArray()` returns a zero-copy view
+ * (a Uint8Array pointing into the original buffer), so no allocation occurs until the
+ * consumer actually needs the data.
+ *
+ * Memory lifecycle:
+ *   1. On parse: only metadata (~200 bytes per file) enters JS heap.
+ *   2. On demand: `getFileData(fileId)` reads the zero-copy slice from the buffer.
+ *   3. The caller (renderer/worker) uses the data, then lets it GC naturally.
+ *   4. If the store is released, the buffer reference is dropped, freeing everything.
+ *
+ * This is the key to supporting 1000s of external files without RAM bloat.
+ */
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import * as flatbuffers from "flatbuffers";
+import { ExportedDataState as ExportedDataStateFb } from "./flatbuffers/duc";
+export class LazyExternalFileStore {
+    constructor(buffer) {
+        /** Map from file id → lazy entry */
+        this._entries = new Map();
+        /** Map from element key → file id (the external_files vector uses element id as key) */
+        this._keyToFileId = new Map();
+        /**
+         * Files that were added at runtime (e.g. user uploading a new image).
+         * These aren't in the original FlatBuffer so we hold their data directly.
+         */
+        this._runtimeFiles = new Map();
+        this._buffer = buffer;
+        this._byteBuffer = new flatbuffers.ByteBuffer(buffer);
+        this._dataState = ExportedDataStateFb.getRootAsExportedDataState(this._byteBuffer);
+        this._indexMetadata();
+        console.info(`[LazyExternalFileStore] indexed ${this._entries.size} files from ${buffer.byteLength} byte buffer, ids: [${[...this._entries.keys()].map(k => k.slice(0, 12)).join(', ')}]`);
+    }
+    _indexMetadata() {
+        if (!this._dataState)
+            return;
+        const count = this._dataState.externalFilesLength();
+        for (let i = 0; i < count; i++) {
+            const entry = this._dataState.externalFiles(i);
+            if (!entry)
+                continue;
+            const key = entry.key();
+            const fileData = entry.value();
+            if (!key || !fileData)
+                continue;
+            const id = fileData.id();
+            if (!id)
+                continue;
+            const metadata = {
+                id,
+                mimeType: fileData.mimeType() || "application/octet-stream",
+                created: Number(fileData.created()),
+                lastRetrieved: Number(fileData.lastRetrieved()) || undefined,
+            };
+            const lazyEntry = { metadata, vectorIndex: i };
+            this._entries.set(id, lazyEntry);
+            this._keyToFileId.set(key, id);
+        }
+    }
+    /** Total number of external files */
+    get size() {
+        return this._entries.size + this._runtimeFiles.size;
+    }
+    /** Whether a file with the given id exists */
+    has(fileId) {
+        return this._entries.has(fileId) || this._runtimeFiles.has(fileId);
+    }
+    /** Get metadata only (no binary data copied) — ~200 bytes per file */
+    getMetadata(fileId) {
+        var _a, _b;
+        const runtime = this._runtimeFiles.get(fileId);
+        if (runtime) {
+            const { data: _ } = runtime, meta = __rest(runtime, ["data"]);
+            return meta;
+        }
+        return (_b = (_a = this._entries.get(fileId)) === null || _a === void 0 ? void 0 : _a.metadata) !== null && _b !== void 0 ? _b : null;
+    }
+    /** Get all metadata entries (for UI listing, etc.) */
+    getAllMetadata() {
+        const result = {};
+        for (const [id, entry] of this._entries) {
+            result[id] = entry.metadata;
+        }
+        for (const [id, file] of this._runtimeFiles) {
+            const { data: _ } = file, meta = __rest(file, ["data"]);
+            result[id] = meta;
+        }
+        return result;
+    }
+    /**
+     * Get full file data (metadata + binary bytes) ON DEMAND.
+     *
+     * For files from the original FlatBuffer, this returns a zero-copy Uint8Array
+     * view into the original buffer — no allocation for the file bytes themselves.
+     * The view is valid as long as this store hasn't been released.
+     *
+     * For runtime-added files, returns the data directly.
+     */
+    getFileData(fileId) {
+        const runtime = this._runtimeFiles.get(fileId);
+        if (runtime)
+            return runtime;
+        const entry = this._entries.get(fileId);
+        if (!entry || !this._dataState)
+            return null;
+        const fbEntry = this._dataState.externalFiles(entry.vectorIndex);
+        if (!fbEntry)
+            return null;
+        const fileData = fbEntry.value();
+        if (!fileData)
+            return null;
+        const data = fileData.dataArray();
+        if (!data)
+            return null;
+        return Object.assign(Object.assign({}, entry.metadata), { data });
+    }
+    /**
+     * Get a detached copy of the file data (allocates new ArrayBuffer).
+     * Use this when you need to transfer data to a worker or keep it beyond store lifetime.
+     */
+    getFileDataCopy(fileId) {
+        const fileDataRef = this.getFileData(fileId);
+        if (!fileDataRef)
+            return null;
+        return Object.assign(Object.assign({}, fileDataRef), { data: new Uint8Array(fileDataRef.data) });
+    }
+    /**
+     * Add a file at runtime (user upload, paste, etc.).
+     * These files are held in memory since they aren't in the FlatBuffer.
+     */
+    addRuntimeFile(fileData) {
+        this._runtimeFiles.set(fileData.id, fileData);
+    }
+    /** Remove a runtime-added file */
+    removeRuntimeFile(fileId) {
+        this._runtimeFiles.delete(fileId);
+    }
+    /**
+     * Export all files as a standard DucExternalFiles record.
+     * This COPIES all file data eagerly — use only for serialization.
+     */
+    toExternalFiles() {
+        const result = {};
+        for (const [key, fileId] of this._keyToFileId) {
+            const fileData = this.getFileData(fileId);
+            if (fileData) {
+                result[key] = fileData;
+            }
+        }
+        for (const [id, file] of this._runtimeFiles) {
+            result[id] = file;
+        }
+        return result;
+    }
+    /**
+     * Merge runtime files from the given DucExternalFiles map.
+     * Only adds files not already present in the store.
+     */
+    mergeFiles(files) {
+        for (const [_key, fileData] of Object.entries(files)) {
+            if (!this.has(fileData.id)) {
+                this.addRuntimeFile(fileData);
+            }
+        }
+    }
+    /** Estimated RAM usage for metadata only (not counting the backing buffer) */
+    get estimatedMetadataBytes() {
+        var _a, _b;
+        let bytes = 0;
+        for (const [, entry] of this._entries) {
+            bytes += 200 + entry.metadata.id.length * 2 + entry.metadata.mimeType.length * 2;
+        }
+        for (const [, file] of this._runtimeFiles) {
+            bytes += 200 + ((_b = (_a = file.data) === null || _a === void 0 ? void 0 : _a.byteLength) !== null && _b !== void 0 ? _b : 0);
+        }
+        return bytes;
+    }
+    /**
+     * Release the FlatBuffer reference. After this, only runtime-added files remain accessible.
+     * Call this when switching documents or when the store is no longer needed.
+     */
+    release() {
+        this._buffer = null;
+        this._byteBuffer = null;
+        this._dataState = null;
+        this._entries.clear();
+        this._keyToFileId.clear();
+    }
+    /** Whether the store has been released */
+    get isReleased() {
+        return this._buffer === null;
+    }
+}

package/dist/parse.d.ts

@@ -1,11 +1,12 @@
 import { FileSystemHandle } from 'browser-fs-access';
-import { CustomHatchPattern as CustomHatchPatternFb, DimensionToleranceStyle as DimensionToleranceStyleFb, DucBlock as DucBlockFb, DucDimensionStyle as DucDimensionStyleFb, DucDocStyle as DucDocStyleFb, DucExternalFileEntry, DucFeatureControlFrameStyle as DucFeatureControlFrameStyleFb, DucGlobalState as DucGlobalStateFb, DucGroup as DucGroupFb, DucHatchStyle as DucHatchStyleFb, DucHead as DucHeadFb, DucImageFilter as DucImageFilterFb, DucLayer as DucLayerFb, DucLeaderStyle as DucLeaderStyleFb, DucLine as DucLineFb, DucLineReference as DucLineReferenceFb, DucLocalState as DucLocalStateFb, DucPath as DucPathFb, DucPlotStyle as DucPlotStyleFb, DucPointBinding as DucPointBindingFb, DucPoint as DucPointFb, DucRegion as DucRegionFb, DucStackLikeStyles as DucStackLikeStylesFb, DucTableCellStyle as DucTableCellStyleFb, DucTableStyle as DucTableStyleFb, DucTextStyle as DucTextStyleFb, DucViewportStyle as DucViewportStyleFb, DucXRayStyle as DucXRayStyleFb, ElementBackground as ElementBackgroundFb, ElementContentBase as ElementContentBaseFb, ElementStroke as ElementStrokeFb, ElementWrapper, ExportedDataState as ExportedDataStateFb, GeometricPoint as GeometricPointFb, HatchPatternLine as HatchPatternLineFb, Margins as MarginsFb, PrimaryUnits as PrimaryUnitsFb, Standard as StandardFb, StrokeSides as StrokeSidesFb, StrokeStyle as StrokeStyleFb, TilingProperties as TilingPropertiesFb, VersionGraph as VersionGraphFb, _DucElementBase as _DucElementBaseFb, _DucElementStylesBase as _DucElementStylesBaseFb, _DucLinearElementBase as _DucLinearElementBaseFb, _DucStackBase as _DucStackBaseFb, _DucStackElementBase as _DucStackElementBaseFb } from "./flatbuffers/duc";
+import { CustomHatchPattern as CustomHatchPatternFb, DimensionToleranceStyle as DimensionToleranceStyleFb, DocumentGridConfig as DocumentGridConfigFb, DucBlock as DucBlockFb, DucDimensionStyle as DucDimensionStyleFb, DucDocStyle as DucDocStyleFb, DucExternalFileEntry, DucFeatureControlFrameStyle as DucFeatureControlFrameStyleFb, DucGlobalState as DucGlobalStateFb, DucGroup as DucGroupFb, DucHatchStyle as DucHatchStyleFb, DucHead as DucHeadFb, DucImageFilter as DucImageFilterFb, DucLayer as DucLayerFb, DucLeaderStyle as DucLeaderStyleFb, DucLine as DucLineFb, DucLineReference as DucLineReferenceFb, DucLocalState as DucLocalStateFb, DucPath as DucPathFb, DucPlotStyle as DucPlotStyleFb, DucPointBinding as DucPointBindingFb, DucPoint as DucPointFb, DucRegion as DucRegionFb, DucStackLikeStyles as DucStackLikeStylesFb, DucTableCellStyle as DucTableCellStyleFb, DucTableStyle as DucTableStyleFb, DucTextStyle as DucTextStyleFb, DucViewportStyle as DucViewportStyleFb, DucXRayStyle as DucXRayStyleFb, ElementBackground as ElementBackgroundFb, ElementContentBase as ElementContentBaseFb, ElementStroke as ElementStrokeFb, ElementWrapper, ExportedDataState as ExportedDataStateFb, GeometricPoint as GeometricPointFb, HatchPatternLine as HatchPatternLineFb, Margins as MarginsFb, PrimaryUnits as PrimaryUnitsFb, Standard as StandardFb, StrokeSides as StrokeSidesFb, StrokeStyle as StrokeStyleFb, TilingProperties as TilingPropertiesFb, VersionGraph as VersionGraphFb, _DucElementBase as _DucElementBaseFb, _DucElementStylesBase as _DucElementStylesBaseFb, _DucLinearElementBase as _DucLinearElementBaseFb, _DucStackBase as _DucStackBaseFb, _DucStackElementBase as _DucStackElementBaseFb } from "./flatbuffers/duc";
 import { RestoreConfig, RestoredDataState } from "./restore";
 import { Standard, StandardUnits } from "./technical";
-import { CustomHatchPattern, Dictionary, DucBlock, DucDimensionStyle, DucDocStyle, DucElement, DucExternalFiles, DucFeatureControlFrameStyle, DucGlobalState, DucGroup, DucHatchStyle, DucHead, DucImageFilter, DucLayer, DucLeaderStyle, DucLine, DucLineReference, DucLocalState, DucPath, DucPlotStyle, DucPoint, DucPointBinding, DucRegion, DucStackLikeStyles, DucTableCellStyle, DucTableStyle, DucTextStyle, DucViewportStyle, DucXRayStyle, ElementBackground, ElementContentBase, ElementStroke, GeometricPoint, HatchPatternLine, PlotLayout, StrokeSides, StrokeStyle, TilingProperties, VersionGraph, _DucElementBase, _DucElementStylesBase, _DucLinearElementBase, _DucStackBase, _DucStackElementBase } from "./types";
+import { CustomHatchPattern, Dictionary, DocumentGridConfig, DucBlock, DucDimensionStyle, DucDocStyle, DucElement, DucExternalFileMetadata, DucExternalFiles, DucFeatureControlFrameStyle, DucGlobalState, DucGroup, DucHatchStyle, DucHead, DucImageFilter, DucLayer, DucLeaderStyle, DucLine, DucLineReference, DucLocalState, DucPath, DucPlotStyle, DucPoint, DucPointBinding, DucRegion, DucStackLikeStyles, DucTableCellStyle, DucTableStyle, DucTextStyle, DucViewportStyle, DucXRayStyle, ElementBackground, ElementContentBase, ElementStroke, GeometricPoint, HatchPatternLine, PlotLayout, StrokeSides, StrokeStyle, TilingProperties, VersionGraph, _DucElementBase, _DucElementStylesBase, _DucLinearElementBase, _DucStackBase, _DucStackElementBase } from "./types";
 export declare function parseGeometricPoint(point: GeometricPointFb): GeometricPoint;
 export declare function parsePoint(point: DucPointFb): DucPoint;
 export declare function parseMargins(margins: MarginsFb): PlotLayout["margins"];
+export declare function parseDocumentGridConfig(gridConfig: DocumentGridConfigFb): DocumentGridConfig;
 export declare function parseHead(head: DucHeadFb): DucHead;
 export declare function parseHatchPatternLine(line: HatchPatternLineFb): HatchPatternLine;
 export declare function parseCustomHatchPattern(pattern: CustomHatchPatternFb): CustomHatchPattern;
@@ -42,6 +43,14 @@ export declare function parseElementFromBinary(wrapper: ElementWrapper): DucElem
 export declare function parseBlockFromBinary(block: DucBlockFb): DucBlock;
 export declare function parseDictionaryFromBinary(data: ExportedDataStateFb): Dictionary;
 export declare function parseExternalFilesFromBinary(entry: DucExternalFileEntry): DucExternalFiles;
+/**
+ * Parse only metadata (no binary data) from an external file entry.
+ * Used by the lazy file store to avoid copying file bytes into JS memory.
+ */
+export declare function parseExternalFileMetadataFromBinary(entry: DucExternalFileEntry): {
+    key: string;
+    metadata: DucExternalFileMetadata;
+} | null;
 export declare function parseGlobalStateFromBinary(state: DucGlobalStateFb): DucGlobalState;
 export declare function parseGroupFromBinary(group: DucGroupFb): DucGroup;
 export declare function parseLayerFromBinary(layer: DucLayerFb): DucLayer;
@@ -52,3 +61,27 @@ export declare function parseStandardFromBinary(standard: StandardFb): Standard;
 export declare function parseThumbnailFromBinary(data: ExportedDataStateFb): Uint8Array | undefined;
 export declare function parseVersionGraphFromBinary(graph: VersionGraphFb | null): VersionGraph | null;
 export declare const parseDuc: (blob: Blob | File, fileHandle?: FileSystemHandle | null, restoreConfig?: RestoreConfig) => Promise<RestoredDataState>;
+import { LazyExternalFileStore } from "./lazy-files";
+export type LazyRestoredDataState = Omit<RestoredDataState, 'files'> & {
+    /** Lazy file store: only metadata is in memory, file bytes are read on-demand from the buffer */
+    lazyFileStore: LazyExternalFileStore;
+    /** Legacy `files` field — always empty. Use lazyFileStore instead. */
+    files: DucExternalFiles;
+};
+/**
+ * Parse a .duc binary with lazy external file loading.
+ *
+ * This is identical to `parseDuc` except:
+ *  - External file BYTES are NOT copied into JS memory.
+ *  - Only file metadata (~200 bytes per file) is parsed.
+ *  - A `LazyExternalFileStore` is returned for on-demand data access.
+ *  - The store holds a reference to the original Uint8Array buffer.
+ *
+ * Memory comparison for 500 PDFs averaging 5MB each:
+ *  - parseDuc: files field holds 2.5GB of ArrayBuffer data in JS heap
+ *  - parseDucLazy: ~100KB of metadata + the original buffer (referenced, not copied)
+ *
+ * @param buffer - The raw .duc file bytes (from storage/IndexedDB/filesystem)
+ * @param restoreConfig - Optional restore configuration
+ */
+export declare const parseDucLazy: (buffer: Uint8Array, restoreConfig?: RestoreConfig) => Promise<LazyRestoredDataState>;

package/dist/parse.js

@@ -10,7 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { decompressSync, strFromU8 } from 'fflate';
 import * as flatbuffers from "flatbuffers";
 import { nanoid } from 'nanoid';
-import { DucArrowElement as DucArrowElementFb, DucDimensionElement as DucDimensionElementFb, DucDocElement as DucDocElementFb, DucEllipseElement as DucEllipseElementFb, DucEmbeddableElement as DucEmbeddableElementFb, DucFeatureControlFrameElement as DucFeatureControlFrameElementFb, DucFrameElement as DucFrameElementFb, DucFreeDrawElement as DucFreeDrawElementFb, DucImageElement as DucImageElementFb, DucLeaderElement as DucLeaderElementFb, DucLinearElement as DucLinearElementFb, DucMermaidElement as DucMermaidElementFb, DucParametricElement as DucParametricElementFb, DucPdfElement as DucPdfElementFb, DucPlotElement as DucPlotElementFb, DucPolygonElement as DucPolygonElementFb, DucRectangleElement as DucRectangleElementFb, DucTableElement as DucTableElementFb, DucTextDynamicDictionarySource as DucTextDynamicDictionarySourceFb, DucTextDynamicElementSource as DucTextDynamicElementSourceFb, DucTextElement as DucTextElementFb, DucViewportElement as DucViewportElementFb, DucXRayElement as DucXRayElementFb, Element as ElementUnion, ExportedDataState, LEADER_CONTENT_TYPE as LEADER_CONTENT_TYPE_ENUM, LeaderBlockContent as LeaderBlockContentFb, LeaderTextBlockContent as LeaderTextBlockContentFb, TEXT_FIELD_SOURCE_TYPE } from "./flatbuffers/duc";
+import { DOCUMENT_GRID_ALIGN_ITEMS, DucArrowElement as DucArrowElementFb, DucDimensionElement as DucDimensionElementFb, DucDocElement as DucDocElementFb, DucEllipseElement as DucEllipseElementFb, DucEmbeddableElement as DucEmbeddableElementFb, DucFeatureControlFrameElement as DucFeatureControlFrameElementFb, DucFrameElement as DucFrameElementFb, DucFreeDrawElement as DucFreeDrawElementFb, DucImageElement as DucImageElementFb, DucLeaderElement as DucLeaderElementFb, DucLinearElement as DucLinearElementFb, DucMermaidElement as DucMermaidElementFb, DucModelElement as DucModelElementFb, DucPdfElement as DucPdfElementFb, DucPlotElement as DucPlotElementFb, DucPolygonElement as DucPolygonElementFb, DucRectangleElement as DucRectangleElementFb, DucTableElement as DucTableElementFb, DucTextDynamicDictionarySource as DucTextDynamicDictionarySourceFb, DucTextDynamicElementSource as DucTextDynamicElementSourceFb, DucTextElement as DucTextElementFb, DucViewportElement as DucViewportElementFb, DucXRayElement as DucXRayElementFb, Element as ElementUnion, ExportedDataState, LEADER_CONTENT_TYPE as LEADER_CONTENT_TYPE_ENUM, LeaderBlockContent as LeaderBlockContentFb, LeaderTextBlockContent as LeaderTextBlockContentFb, TEXT_FIELD_SOURCE_TYPE } from "./flatbuffers/duc";
 import { restore } from "./restore";
 // #region HELPERS & LOW-LEVEL CASTS
 // Helper functions for type casting
@@ -70,6 +70,25 @@ export function parseMargins(margins) {
         left: toPrecisionValue(margins.left()),
     };
 }
+export function parseDocumentGridConfig(gridConfig) {
+    return {
+        columns: gridConfig.columns(),
+        gapX: gridConfig.gapX(),
+        gapY: gridConfig.gapY(),
+        alignItems: (() => {
+            const align = gridConfig.alignItems();
+            if (align === DOCUMENT_GRID_ALIGN_ITEMS.START)
+                return 'start';
+            if (align === DOCUMENT_GRID_ALIGN_ITEMS.CENTER)
+                return 'center';
+            if (align === DOCUMENT_GRID_ALIGN_ITEMS.END)
+                return 'end';
+            return 'start';
+        })(),
+        firstPageAlone: gridConfig.firstPageAlone(),
+        scale: gridConfig.scale(),
+    };
+}
 export function parseHead(head) {
     return {
         type: head.type(),
@@ -257,7 +276,15 @@ function parseEmbeddableElement(element) {
     return Object.assign({ type: "embeddable" }, parseElementBase(element.base()));
 }
 function parsePdfElement(element) {
-    return Object.assign(Object.assign({ type: "pdf" }, parseElementBase(element.base())), { fileId: element.fileId() });
+    const gridConfig = element.gridConfig();
+    return Object.assign(Object.assign({ type: "pdf" }, parseElementBase(element.base())), { fileId: element.fileId(), gridConfig: gridConfig ? parseDocumentGridConfig(gridConfig) : {
+            columns: 1,
+            gapX: 0,
+            gapY: 0,
+            alignItems: 'start',
+            firstPageAlone: false,
+            scale: 1,
+        } });
 }
 function parseMermaidElement(element) {
     return Object.assign(Object.assign({ type: "mermaid" }, parseElementBase(element.base())), { source: element.source(), theme: element.theme() || undefined, svgPath: element.svgPath() });
@@ -545,6 +572,7 @@ function parseDocElement(element) {
         });
     }
     const columns = element.columns();
+    const gridConfig = element.gridConfig();
     return Object.assign(Object.assign(Object.assign({ type: "doc" }, parseElementBase(element.base())), parseDocStyle(element.style())), { text: element.text(), dynamic: dynamicParts, flowDirection: element.flowDirection(), columns: {
             type: columns.type(),
             definitions: Array.from({ length: columns.definitionsLength() }, (_, i) => {
@@ -555,16 +583,18 @@ function parseDocElement(element) {
                 };
             }),
             autoHeight: columns.autoHeight(),
-        }, autoResize: element.autoResize() });
-}
-function parseParametricElement(element) {
-    const source = element.source();
-    return Object.assign(Object.assign({ type: "parametric" }, parseElementBase(element.base())), { source: {
-            type: source.type(),
-            code: source.code(),
-            fileId: source.fileId(),
+        }, autoResize: element.autoResize(), fileId: element.fileId(), gridConfig: gridConfig ? parseDocumentGridConfig(gridConfig) : {
+            columns: 1,
+            gapX: 0,
+            gapY: 0,
+            alignItems: 'start',
+            firstPageAlone: false,
+            scale: 1,
         } });
 }
+function parseModelElement(element) {
+    return Object.assign(Object.assign({ type: "model" }, parseElementBase(element.base())), { source: element.source(), svgPath: element.svgPath(), fileIds: Array.from({ length: element.fileIdsLength() }, (_, i) => element.fileIds(i)) });
+}
 // #endregion
 // #region STYLE PARSERS (ELEMENT-LEVEL)
 export function parseTextStyle(style) {
@@ -772,8 +802,8 @@ export function parseElementFromBinary(wrapper) {
         case ElementUnion.DucDocElement:
             element = wrapper.element(new DucDocElementFb());
             break;
-        case ElementUnion.DucParametricElement:
-            element = wrapper.element(new DucParametricElementFb());
+        case ElementUnion.DucModelElement:
+            element = wrapper.element(new DucModelElementFb());
             break;
         default:
             return null;
@@ -823,8 +853,8 @@ export function parseElementFromBinary(wrapper) {
             return parseFeatureControlFrameElement(element);
         case ElementUnion.DucDocElement:
             return parseDocElement(element);
-        case ElementUnion.DucParametricElement:
-            return parseParametricElement(element);
+        case ElementUnion.DucModelElement:
+            return parseModelElement(element);
         default:
             return null;
     }
@@ -880,6 +910,28 @@ export function parseExternalFilesFromBinary(entry) {
         }
     };
 }
+/**
+ * Parse only metadata (no binary data) from an external file entry.
+ * Used by the lazy file store to avoid copying file bytes into JS memory.
+ */
+export function parseExternalFileMetadataFromBinary(entry) {
+    const fileData = entry.value();
+    const key = entry.key();
+    if (!fileData || !key)
+        return null;
+    const id = fileData.id();
+    if (!id)
+        return null;
+    return {
+        key,
+        metadata: {
+            id,
+            mimeType: fileData.mimeType() || "application/octet-stream",
+            created: Number(fileData.created()),
+            lastRetrieved: Number(fileData.lastRetrieved()) || undefined,
+        },
+    };
+}
 export function parseGlobalStateFromBinary(state) {
     return {
         name: state.name(),
@@ -1432,3 +1484,181 @@ export const parseDuc = (blob_1, ...args_1) => __awaiter(void 0, [blob_1, ...arg
     };
 });
 // #endregion
+// #region LAZY ROOT PARSER
+import { LazyExternalFileStore } from "./lazy-files";
+/**
+ * Parse a .duc binary with lazy external file loading.
+ *
+ * This is identical to `parseDuc` except:
+ *  - External file BYTES are NOT copied into JS memory.
+ *  - Only file metadata (~200 bytes per file) is parsed.
+ *  - A `LazyExternalFileStore` is returned for on-demand data access.
+ *  - The store holds a reference to the original Uint8Array buffer.
+ *
+ * Memory comparison for 500 PDFs averaging 5MB each:
+ *  - parseDuc: files field holds 2.5GB of ArrayBuffer data in JS heap
+ *  - parseDucLazy: ~100KB of metadata + the original buffer (referenced, not copied)
+ *
+ * @param buffer - The raw .duc file bytes (from storage/IndexedDB/filesystem)
+ * @param restoreConfig - Optional restore configuration
+ */
+export const parseDucLazy = (buffer_1, ...args_1) => __awaiter(void 0, [buffer_1, ...args_1], void 0, function* (buffer, restoreConfig = {}) {
+    var _a;
+    if (!buffer || buffer.byteLength === 0) {
+        throw new Error('Invalid DUC buffer: empty file');
+    }
+    const byteBuffer = new flatbuffers.ByteBuffer(buffer);
+    let data;
+    try {
+        data = ExportedDataState.getRootAsExportedDataState(byteBuffer);
+    }
+    catch (e) {
+        throw new Error('Invalid DUC buffer: cannot read root table');
+    }
+    const legacyVersion = data.versionLegacy();
+    if (legacyVersion) {
+        throw new Error(`Unsupported DUC version: ${legacyVersion}. Please use version ducjs@2.0.1 or lower to support this file.`);
+    }
+    const localState = data.ducLocalState();
+    const parsedLocalState = localState && parseLocalStateFromBinary(localState);
+    const globalState = data.ducGlobalState();
+    const parsedGlobalState = globalState && parseGlobalStateFromBinary(globalState);
+    // Parse elements
+    const elements = [];
+    for (let i = 0; i < data.elementsLength(); i++) {
+        const e = data.elements(i);
+        if (e) {
+            const element = parseElementFromBinary(e);
+            if (element) {
+                elements.push(element);
+            }
+        }
+    }
+    // Create lazy file store — only metadata is parsed, no file bytes copied
+    const lazyFileStore = new LazyExternalFileStore(buffer);
+    // Parse blocks
+    const blocks = [];
+    for (let i = 0; i < data.blocksLength(); i++) {
+        const block = data.blocks(i);
+        if (block) {
+            const parsedBlock = parseBlockFromBinary(block);
+            if (parsedBlock) {
+                blocks.push(parsedBlock);
+            }
+        }
+    }
+    // Parse block instances
+    const blockInstances = [];
+    for (let i = 0; i < data.blockInstancesLength(); i++) {
+        const blockInstance = data.blockInstances(i);
+        if (blockInstance) {
+            const parsedBlockInstance = parseBlockInstance(blockInstance);
+            if (parsedBlockInstance) {
+                blockInstances.push(parsedBlockInstance);
+            }
+        }
+    }
+    // Parse block collections
+    const blockCollections = [];
+    for (let i = 0; i < data.blockCollectionsLength(); i++) {
+        const blockCollection = data.blockCollections(i);
+        if (blockCollection) {
+            const parsedBlockCollection = parseBlockCollection(blockCollection);
+            if (parsedBlockCollection) {
+                blockCollections.push(parsedBlockCollection);
+            }
+        }
+    }
+    // Parse groups
+    const groups = [];
+    for (let i = 0; i < data.groupsLength(); i++) {
+        const group = data.groups(i);
+        if (group) {
+            const parsedGroup = parseGroupFromBinary(group);
+            if (parsedGroup) {
+                groups.push(parsedGroup);
+            }
+        }
+    }
+    // Parse dictionary
+    const dictionary = parseDictionaryFromBinary(data);
+    // Parse thumbnail
+    const thumbnail = parseThumbnailFromBinary(data);
+    // Parse version graph
+    const versionGraphData = data.versionGraph();
+    const versionGraph = parseVersionGraphFromBinary(versionGraphData);
+    // Parse regions
+    const regions = [];
+    for (let i = 0; i < data.regionsLength(); i++) {
+        const region = data.regions(i);
+        if (region) {
+            const parsedRegion = parseRegionFromBinary(region);
+            if (parsedRegion) {
+                regions.push(parsedRegion);
+            }
+        }
+    }
+    // Parse layers
+    const layers = [];
+    for (let i = 0; i < data.layersLength(); i++) {
+        const layer = data.layers(i);
+        if (layer) {
+            const parsedLayer = parseLayerFromBinary(layer);
+            if (parsedLayer) {
+                layers.push(parsedLayer);
+            }
+        }
+    }
+    // Parse standards
+    const standards = [];
+    for (let i = 0; i < data.standardsLength(); i++) {
+        const standard = data.standards(i);
+        if (standard) {
+            const parsedStandard = parseStandardFromBinary(standard);
+            if (parsedStandard) {
+                standards.push(parsedStandard);
+            }
+        }
+    }
+    const exportData = {
+        thumbnail,
+        dictionary,
+        elements: elements,
+        localState: parsedLocalState,
+        globalState: parsedGlobalState,
+        blocks,
+        blockInstances,
+        blockCollections,
+        groups,
+        regions,
+        layers,
+        standards,
+        files: {}, // empty — use lazyFileStore
+        versionGraph: versionGraph !== null && versionGraph !== void 0 ? versionGraph : undefined,
+        id: (_a = data.id()) !== null && _a !== void 0 ? _a : nanoid(),
+    };
+    const sanitized = restore(exportData, {
+        syncInvalidIndices: (elements) => elements,
+        repairBindings: true,
+        refreshDimensions: false,
+    }, restoreConfig);
+    return {
+        thumbnail: sanitized.thumbnail,
+        dictionary: sanitized.dictionary,
+        elements: sanitized.elements,
+        localState: sanitized.localState,
+        globalState: sanitized.globalState,
+        files: {},
+        lazyFileStore,
+        blocks: sanitized.blocks,
+        blockInstances: sanitized.blockInstances,
+        groups: sanitized.groups,
+        regions: sanitized.regions,
+        layers: sanitized.layers,
+        blockCollections: sanitized.blockCollections,
+        standards: sanitized.standards,
+        versionGraph: sanitized.versionGraph,
+        id: sanitized.id,
+    };
+});
+// #endregion

package/dist/restore/restoreDataState.d.ts

@@ -97,12 +97,7 @@ export declare const restoreBlockCollections: (collections: unknown) => Restored
  * Restores the blockInstances array from imported data, ensuring each item
  * conforms to the DucBlockInstance type.
  */
-export declare const restoreBlockInstances: (blockInstances: unknown) => RestoredDataState["blockInstances"];
-/**
- * Restores instances from block instances data (alias for restoreBlockInstances)
- * This method provides a consistent naming convention for instance restoration.
- */
-export declare const restoreInstances: (instances: unknown) => RestoredDataState["blockInstances"];
+export declare const restoreBlockInstances: (blockInstances: unknown, currentScope: Scope) => RestoredDataState["blockInstances"];
 /**
  * Restores the global state of the document from imported data.
  * It validates and provides defaults for missing or invalid properties.

package/dist/restore/restoreDataState.js

@@ -20,7 +20,7 @@ export const restore = (data, elementsConfig, restoreConfig = {}) => {
     const restoredRegions = restoreRegions(data === null || data === void 0 ? void 0 : data.regions);
     const restoredGroups = restoreGroups(data === null || data === void 0 ? void 0 : data.groups);
     const restoredLayers = restoreLayers(data === null || data === void 0 ? void 0 : data.layers, restoredLocalState.scope);
-    const restoredBlockInstances = restoreBlockInstances(data === null || data === void 0 ? void 0 : data.blockInstances);
+    const restoredBlockInstances = restoreBlockInstances(data === null || data === void 0 ? void 0 : data.blockInstances, restoredLocalState.scope);
     const restoredElements = restoreElements(data === null || data === void 0 ? void 0 : data.elements, restoredLocalState.scope, restoredBlocks, restoredElementsConfig);
     const restoredVersionGraph = restoreVersionGraph(data === null || data === void 0 ? void 0 : data.versionGraph);
     // Generate a new ID if none exists or if it's empty
@@ -247,7 +247,7 @@ export const restoreBlockCollections = (collections) => {
  * Restores the blockInstances array from imported data, ensuring each item
  * conforms to the DucBlockInstance type.
  */
-export const restoreBlockInstances = (blockInstances) => {
+export const restoreBlockInstances = (blockInstances, currentScope) => {
     if (!Array.isArray(blockInstances)) {
         return [];
     }
@@ -301,8 +301,8 @@ export const restoreBlockInstances = (blockInstances) => {
                 ? {
                     rows: typeof dupArray.rows === "number" ? dupArray.rows : 1,
                     cols: typeof dupArray.cols === "number" ? dupArray.cols : 1,
-                    rowSpacing: typeof dupArray.rowSpacing === "number" ? dupArray.rowSpacing : 0,
-                    colSpacing: typeof dupArray.colSpacing === "number" ? dupArray.colSpacing : 0,
+                    rowSpacing: restorePrecisionValue(dupArray.rowSpacing, NEUTRAL_SCOPE, currentScope),
+                    colSpacing: restorePrecisionValue(dupArray.colSpacing, NEUTRAL_SCOPE, currentScope),
                 }
                 : null,
         };
@@ -337,13 +337,6 @@ const restoreBlockMetadata = (metadata) => {
         : undefined;
     return Object.assign(Object.assign({}, (source ? { source } : {})), { usageCount: typeof metadataObj.usageCount === "number" ? metadataObj.usageCount : 0, createdAt: typeof metadataObj.createdAt === "number" ? metadataObj.createdAt : Date.now(), updatedAt: typeof metadataObj.updatedAt === "number" ? metadataObj.updatedAt : Date.now(), localization });
 };
-/**
- * Restores instances from block instances data (alias for restoreBlockInstances)
- * This method provides a consistent naming convention for instance restoration.
- */
-export const restoreInstances = (instances) => {
-    return restoreBlockInstances(instances);
-};
 /**
  * Restores the global state of the document from imported data.
  * It validates and provides defaults for missing or invalid properties.