ducjs 2.3.0 → 2.4.0

package/dist/flatbuffers/duc/document-grid-config.d.ts

@@ -11,12 +11,14 @@ export declare class DocumentGridConfig {
     gapY(): number;
     alignItems(): DOCUMENT_GRID_ALIGN_ITEMS | null;
     firstPageAlone(): boolean;
+    scale(): number;
     static startDocumentGridConfig(builder: flatbuffers.Builder): void;
     static addColumns(builder: flatbuffers.Builder, columns: number): void;
     static addGapX(builder: flatbuffers.Builder, gapX: number): void;
     static addGapY(builder: flatbuffers.Builder, gapY: number): void;
     static addAlignItems(builder: flatbuffers.Builder, alignItems: DOCUMENT_GRID_ALIGN_ITEMS): void;
     static addFirstPageAlone(builder: flatbuffers.Builder, firstPageAlone: boolean): void;
+    static addScale(builder: flatbuffers.Builder, scale: number): void;
     static endDocumentGridConfig(builder: flatbuffers.Builder): flatbuffers.Offset;
-    static createDocumentGridConfig(builder: flatbuffers.Builder, columns: number, gapX: number, gapY: number, alignItems: DOCUMENT_GRID_ALIGN_ITEMS | null, firstPageAlone: boolean): flatbuffers.Offset;
+    static createDocumentGridConfig(builder: flatbuffers.Builder, columns: number, gapX: number, gapY: number, alignItems: DOCUMENT_GRID_ALIGN_ITEMS | null, firstPageAlone: boolean, scale: number): flatbuffers.Offset;
 }

package/dist/flatbuffers/duc/document-grid-config.js

@@ -38,8 +38,12 @@ export class DocumentGridConfig {
         const offset = this.bb.__offset(this.bb_pos, 12);
         return offset ? !!this.bb.readInt8(this.bb_pos + offset) : false;
     }
+    scale() {
+        const offset = this.bb.__offset(this.bb_pos, 14);
+        return offset ? this.bb.readFloat64(this.bb_pos + offset) : 0.0;
+    }
     static startDocumentGridConfig(builder) {
-        builder.startObject(5);
+        builder.startObject(6);
     }
     static addColumns(builder, columns) {
         builder.addFieldInt32(0, columns, 0);
@@ -56,11 +60,14 @@ export class DocumentGridConfig {
     static addFirstPageAlone(builder, firstPageAlone) {
         builder.addFieldInt8(4, +firstPageAlone, +false);
     }
+    static addScale(builder, scale) {
+        builder.addFieldFloat64(5, scale, 0.0);
+    }
     static endDocumentGridConfig(builder) {
         const offset = builder.endObject();
         return offset;
     }
-    static createDocumentGridConfig(builder, columns, gapX, gapY, alignItems, firstPageAlone) {
+    static createDocumentGridConfig(builder, columns, gapX, gapY, alignItems, firstPageAlone, scale) {
         DocumentGridConfig.startDocumentGridConfig(builder);
         DocumentGridConfig.addColumns(builder, columns);
         DocumentGridConfig.addGapX(builder, gapX);
@@ -68,6 +75,7 @@ export class DocumentGridConfig {
         if (alignItems !== null)
             DocumentGridConfig.addAlignItems(builder, alignItems);
         DocumentGridConfig.addFirstPageAlone(builder, firstPageAlone);
+        DocumentGridConfig.addScale(builder, scale);
         return DocumentGridConfig.endDocumentGridConfig(builder);
     }
 }

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export * as DucBin from "./flatbuffers/duc";
-export * from "./types";
-export * from "./utils";
-export * from "./serialize";
+export * from "./lazy-files";
 export * from "./parse";
 export * from "./restore";
+export * from "./serialize";
 export * from "./technical";
+export * from "./types";
+export * from "./utils";

package/dist/index.js

@@ -1,7 +1,8 @@
 export * as DucBin from "./flatbuffers/duc";
-export * from "./types";
-export * from "./utils";
-export * from "./serialize";
+export * from "./lazy-files";
 export * from "./parse";
 export * from "./restore";
+export * from "./serialize";
 export * from "./technical";
+export * from "./types";
+export * from "./utils";

package/dist/lazy-files.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ */
+import type { DucExternalFileData, DucExternalFileMetadata, DucExternalFiles } from "./types";
+export type ExternalFileMetadataMap = Record<string, DucExternalFileMetadata>;
+export declare class LazyExternalFileStore {
+    private _buffer;
+    private _byteBuffer;
+    private _dataState;
+    /** Map from file id → lazy entry */
+    private _entries;
+    /** Map from element key → file id (the external_files vector uses element id as key) */
+    private _keyToFileId;
+    /**
+     * 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.
+     */
+    private _runtimeFiles;
+    constructor(buffer: Uint8Array);
+    private _indexMetadata;
+    /** Total number of external files */
+    get size(): number;
+    /** Whether a file with the given id exists */
+    has(fileId: string): boolean;
+    /** Get metadata only (no binary data copied) — ~200 bytes per file */
+    getMetadata(fileId: string): DucExternalFileMetadata | null;
+    /** Get all metadata entries (for UI listing, etc.) */
+    getAllMetadata(): ExternalFileMetadataMap;
+    /**
+     * 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: string): DucExternalFileData | null;
+    /**
+     * 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: string): DucExternalFileData | null;
+    /**
+     * Add a file at runtime (user upload, paste, etc.).
+     * These files are held in memory since they aren't in the FlatBuffer.
+     */
+    addRuntimeFile(fileData: DucExternalFileData): void;
+    /** Remove a runtime-added file */
+    removeRuntimeFile(fileId: string): void;
+    /**
+     * Export all files as a standard DucExternalFiles record.
+     * This COPIES all file data eagerly — use only for serialization.
+     */
+    toExternalFiles(): DucExternalFiles;
+    /**
+     * Merge runtime files from the given DucExternalFiles map.
+     * Only adds files not already present in the store.
+     */
+    mergeFiles(files: DucExternalFiles): void;
+    /** Estimated RAM usage for metadata only (not counting the backing buffer) */
+    get estimatedMetadataBytes(): number;
+    /**
+     * 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(): void;
+    /** Whether the store has been released */
+    get isReleased(): boolean;
+}

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,8 +1,8 @@
 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, DocumentGridConfig as DocumentGridConfigFb, 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, DocumentGridConfig, 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"];
@@ -43,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;
@@ -53,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

@@ -86,6 +86,7 @@ export function parseDocumentGridConfig(gridConfig) {
             return 'start';
         })(),
         firstPageAlone: gridConfig.firstPageAlone(),
+        scale: gridConfig.scale(),
     };
 }
 export function parseHead(head) {
@@ -282,6 +283,7 @@ function parsePdfElement(element) {
             gapY: 0,
             alignItems: 'start',
             firstPageAlone: false,
+            scale: 1,
         } });
 }
 function parseMermaidElement(element) {
@@ -587,6 +589,7 @@ function parseDocElement(element) {
             gapY: 0,
             alignItems: 'start',
             firstPageAlone: false,
+            scale: 1,
         } });
 }
 function parseModelElement(element) {
@@ -907,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(),
@@ -1459,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/restoreElements.js

@@ -90,6 +90,10 @@ const restoreElement = (element, currentScope, restoredBlocks, localState, globa
         case "text": {
             let fontSize = element.fontSize;
             let fontFamily = element.fontFamily;
+            // Restore condition: if font family is "10", change to DEFAULT_FONT_FAMILY
+            if (fontFamily === "10") {
+                fontFamily = DEFAULT_FONT_FAMILY;
+            }
             if ("font" in element) {
                 try {
                     const fontParts = String(element.font).split(" ");
@@ -975,6 +979,7 @@ const restoreDocumentGridConfig = (gridConfig) => {
             gapY: 0,
             alignItems: "start",
             firstPageAlone: false,
+            scale: 1,
         };
     }
     return {
@@ -985,6 +990,7 @@ const restoreDocumentGridConfig = (gridConfig) => {
             ? gridConfig.alignItems
             : "start",
         firstPageAlone: typeof gridConfig.firstPageAlone === "boolean" ? gridConfig.firstPageAlone : false,
+        scale: typeof gridConfig.scale === "number" ? gridConfig.scale : 1,
     };
 };
 const getFontFamilyByName = (fontFamilyName) => {
@@ -1272,10 +1278,15 @@ const restoreFcfDatumDefinition = (def, elementScope, currentScope, restoredBloc
 const restoreTextStyle = (style, currentScope) => {
     var _a, _b, _c;
     const defaultLineHeight = 1.15;
+    // Restore condition: if font family is "10", change to DEFAULT_FONT_FAMILY
+    let fontFamily = style === null || style === void 0 ? void 0 : style.fontFamily;
+    if (fontFamily === "10") {
+        fontFamily = DEFAULT_FONT_FAMILY;
+    }
     return {
         // Text-specific styles
         isLtr: isValidBoolean(style === null || style === void 0 ? void 0 : style.isLtr, true),
-        fontFamily: getFontFamilyByName(style === null || style === void 0 ? void 0 : style.fontFamily),
+        fontFamily: getFontFamilyByName(fontFamily),
         bigFontFamily: isValidString(style === null || style === void 0 ? void 0 : style.bigFontFamily, "sans-serif"),
         textAlign: isValidTextAlignValue(style === null || style === void 0 ? void 0 : style.textAlign),
         verticalAlign: isValidVerticalAlignValue(style === null || style === void 0 ? void 0 : style.verticalAlign),

package/dist/serialize.js

@@ -756,6 +756,7 @@ function writeDocumentGridConfig(b, config, usv) {
     })();
     Duc.DocumentGridConfig.addAlignItems(b, alignItems);
     Duc.DocumentGridConfig.addFirstPageAlone(b, config.firstPageAlone);
+    Duc.DocumentGridConfig.addScale(b, config.scale);
     return Duc.DocumentGridConfig.endDocumentGridConfig(b);
 }
 function writeText(b, e, usv) {

package/dist/types/elements/index.d.ts

@@ -325,6 +325,7 @@ export type DocumentGridConfig = {
     gapY: number;
     alignItems: 'start' | 'center' | 'end';
     firstPageAlone: boolean;
+    scale: number;
 };
 export type DucPdfElement = _DucElementBase & {
     type: "pdf";
@@ -470,9 +471,8 @@ export type DucImageElement = _DucElementBase & {
 export type InitializedDucImageElement = MarkNonNullable<DucImageElement, "fileId">;
 export type FontFamilyKeys = keyof typeof FONT_FAMILY;
 export type FontFamilyValues = typeof FONT_FAMILY[FontFamilyKeys];
-export type FontString = string & {
-    _brand: "fontString";
-};
+/** Font family identifier — any valid CSS font-family string (Google Font name, system font, etc.) */
+export type FontString = string;
 export type TextAlign = ValueOf<typeof TEXT_ALIGN>;
 export type VerticalAlign = ValueOf<typeof VERTICAL_ALIGN>;
 export type LineSpacingType = ValueOf<typeof LINE_SPACING_TYPE>;
@@ -486,7 +486,7 @@ export type DucTextStyle = {
     /**
     * The primary font family to use for the text
     */
-    fontFamily: FontFamilyValues;
+    fontFamily: FontString;
     /**
      * Fallback font family for broader compatibility across all systems and languages
      * Useful for emojis, non-latin characters, etc.

package/dist/types/elements/typeChecks.d.ts

@@ -1,9 +1,12 @@
 import type { ElementOrToolType } from "..";
 import type { MarkNonNullable } from "../utility-types";
 import { Bounds, LineSegment, TuplePoint } from "../geometryTypes";
-import type { DucArrowElement, DucBindableElement, DucElbowArrowElement, DucElement, DucElementType, DucEmbeddableElement, DucFlowchartNodeElement, DucFrameElement, DucFrameLikeElement, DucFreeDrawElement, DucImageElement, DucLinearElement, DucPlotElement, DucTableElement, DucPointBinding, DucTextContainer, DucTextElement, DucTextElementWithContainer, FixedPointBinding, InitializedDucImageElement, DucNonSelectionElement, DucEllipseElement, DucPolygonElement, NonDeleted, DucIframeLikeElement } from "./";
+import type { DucArrowElement, DucBindableElement, DucDocElement, DucElbowArrowElement, DucElement, DucElementType, DucEmbeddableElement, DucFlowchartNodeElement, DucFrameElement, DucFrameLikeElement, DucFreeDrawElement, DucImageElement, DucLinearElement, DucPdfElement, DucPlotElement, DucTableElement, DucPointBinding, DucTextContainer, DucTextElement, DucTextElementWithContainer, FixedPointBinding, InitializedDucImageElement, DucNonSelectionElement, DucEllipseElement, DucPolygonElement, NonDeleted, DucIframeLikeElement } from "./";
 export declare const isInitializedImageElement: (element: DucElement | null) => element is InitializedDucImageElement;
 export declare const isImageElement: (element: DucElement | null) => element is DucImageElement;
+export declare const isPdfElement: (element: DucElement | null) => element is DucPdfElement;
+export type DucPdfLikeElement = DucPdfElement | DucDocElement;
+export declare const isPdfLikeElement: (element: DucElement | null) => element is DucPdfLikeElement;
 export declare const isEmbeddableElement: (element: DucElement | null | undefined) => element is DucEmbeddableElement;
 export declare const isTableElement: (element: DucElement | null) => element is DucTableElement;
 export declare const isIframeLikeElement: (element: DucElement | null) => element is DucIframeLikeElement;

package/dist/types/elements/typeChecks.js

@@ -5,6 +5,12 @@ export const isInitializedImageElement = (element) => {
 export const isImageElement = (element) => {
     return !!element && element.type === "image";
 };
+export const isPdfElement = (element) => {
+    return !!element && element.type === "pdf";
+};
+export const isPdfLikeElement = (element) => {
+    return !!element && (element.type === "pdf" || element.type === "doc");
+};
 export const isEmbeddableElement = (element) => {
     return !!element && element.type === "embeddable";
 };

package/dist/utils/constants.d.ts

@@ -89,24 +89,28 @@ export declare const HIDE_FRAME_NAME_ZOOM_THRESHOLD = 0.18;
 export declare const DEFAULT_PROPORTIONAL_RADIUS = 0.25;
 export declare const DEFAULT_ADAPTIVE_RADIUS = 32;
 /**
- * // TODO: shouldn't be really `const`, likely neither have integers as values, due to value for the custom fonts, which should likely be some hash.
+ * Font family identifiers. Values are the actual CSS font-family names
+ * so they can be passed directly to Google Fonts / Canvas2D.
  *
- * Let's think this through and consider:
- * - https://developer.mozilla.org/en-US/docs/Web/CSS/generic-family
- * - https://drafts.csswg.org/css-fonts-4/#font-family-prop
- * - https://learn.microsoft.com/en-us/typography/opentype/spec/ibmfc
+ * For backward compatibility with old files that stored numeric IDs,
+ * use `LEGACY_FONT_ID_TO_NAME` to resolve them.
  */
 export declare const FONT_FAMILY: {
-    Virgil: number;
-    Helvetica: number;
-    Cascadia: number;
-    Excalifont: number;
-    Nunito: number;
-    "Lilita One": number;
-    "Comic Shanns": number;
-    "Liberation Sans": number;
-    "Roboto Mono": number;
+    readonly Virgil: "Virgil";
+    readonly Helvetica: "Helvetica";
+    readonly Cascadia: "Cascadia";
+    readonly Excalifont: "Excalifont";
+    readonly Nunito: "Nunito";
+    readonly "Lilita One": "Lilita One";
+    readonly "Comic Shanns": "Comic Shanns";
+    readonly "Liberation Sans": "Liberation Sans";
+    readonly "Roboto Mono": "Roboto Mono";
 };
+/**
+ * Reverse mapping from legacy numeric font IDs to font family names.
+ * Used when loading old .duc files that encoded fontFamily as a number.
+ */
+export declare const LEGACY_FONT_ID_TO_NAME: Record<number, string>;
 export declare const WINDOWS_EMOJI_FALLBACK_FONT = "Segoe UI Emoji";
 export declare const DEFAULT_VERSION = "{version}";
 export declare const MIN_FONT_SIZE = 1;

package/dist/utils/constants.js

@@ -87,24 +87,37 @@ export const DEFAULT_PROPORTIONAL_RADIUS = 0.25;
 // Fixed radius for the ADAPTIVE_RADIUS algorithm. In pixels.
 export const DEFAULT_ADAPTIVE_RADIUS = 32;
 /**
- * // TODO: shouldn't be really `const`, likely neither have integers as values, due to value for the custom fonts, which should likely be some hash.
+ * Font family identifiers. Values are the actual CSS font-family names
+ * so they can be passed directly to Google Fonts / Canvas2D.
  *
- * Let's think this through and consider:
- * - https://developer.mozilla.org/en-US/docs/Web/CSS/generic-family
- * - https://drafts.csswg.org/css-fonts-4/#font-family-prop
- * - https://learn.microsoft.com/en-us/typography/opentype/spec/ibmfc
+ * For backward compatibility with old files that stored numeric IDs,
+ * use `LEGACY_FONT_ID_TO_NAME` to resolve them.
  */
 export const FONT_FAMILY = {
-    Virgil: 1,
-    Helvetica: 2,
-    Cascadia: 3,
-    // leave 4 unused as it was historically used for Assistant (which we don't use anymore) or custom font (Obsidian)
-    Excalifont: 5,
-    Nunito: 6,
-    "Lilita One": 7,
-    "Comic Shanns": 8,
-    "Liberation Sans": 9,
-    "Roboto Mono": 10,
+    Virgil: "Virgil",
+    Helvetica: "Helvetica",
+    Cascadia: "Cascadia",
+    Excalifont: "Excalifont",
+    Nunito: "Nunito",
+    "Lilita One": "Lilita One",
+    "Comic Shanns": "Comic Shanns",
+    "Liberation Sans": "Liberation Sans",
+    "Roboto Mono": "Roboto Mono",
+};
+/**
+ * Reverse mapping from legacy numeric font IDs to font family names.
+ * Used when loading old .duc files that encoded fontFamily as a number.
+ */
+export const LEGACY_FONT_ID_TO_NAME = {
+    1: "Virgil",
+    2: "Helvetica",
+    3: "Cascadia",
+    5: "Excalifont",
+    6: "Nunito",
+    7: "Lilita One",
+    8: "Comic Shanns",
+    9: "Liberation Sans",
+    10: "Roboto Mono",
 };
 export const WINDOWS_EMOJI_FALLBACK_FONT = "Segoe UI Emoji";
 export const DEFAULT_VERSION = "{version}";

package/dist/utils/elements/freedrawElement.d.ts

@@ -1,2 +1,8 @@
 import { DucFreeDrawElement } from "../../types/elements";
 export declare function getFreeDrawSvgPath(element: DucFreeDrawElement): string;
+/**
+ * Returns the raw outline polygon points from perfect-freehand.
+ * Each point is [x, y]. The result forms a closed polygon that
+ * represents the visual shape of the freedraw stroke.
+ */
+export declare function getFreeDrawStrokePoints(element: DucFreeDrawElement): number[][];

package/dist/utils/elements/freedrawElement.js

@@ -22,16 +22,8 @@ function getSvgPathFromStroke(points) {
         .join(" ")
         .replace(TO_FIXED_PRECISION, "$1");
 }
-export function getFreeDrawSvgPath(element) {
-    // If input points are empty (should they ever be?) return a dot
-    if (element.points.length === 0) {
-        return "";
-    }
-    const inputPoints = element.simulatePressure
-        ? element.points.map(({ x, y }, i) => [x.scoped, y.scoped, element.pressures[i]])
-        : element.points.map(({ x, y }) => [x.scoped, y.scoped]);
-    // Consider changing the options for simulated pressure vs real pressure
-    const options = {
+function buildStrokeOptions(element) {
+    return {
         size: element.size.scoped,
         simulatePressure: element.simulatePressure,
         thinning: element.thinning,
@@ -40,7 +32,32 @@ export function getFreeDrawSvgPath(element) {
         easing: element.easing,
         start: element.start || undefined,
         end: element.end || undefined,
-        last: !!element.lastCommittedPoint, // LastCommittedPoint is added on pointerup
+        last: !!element.lastCommittedPoint,
     };
+}
+function buildInputPoints(element) {
+    return element.simulatePressure
+        ? element.points.map(({ x, y }, i) => [x.scoped, y.scoped, element.pressures[i]])
+        : element.points.map(({ x, y }) => [x.scoped, y.scoped]);
+}
+export function getFreeDrawSvgPath(element) {
+    if (element.points.length === 0) {
+        return "";
+    }
+    const inputPoints = buildInputPoints(element);
+    const options = buildStrokeOptions(element);
     return getSvgPathFromStroke(getStroke(inputPoints, options));
 }
+/**
+ * Returns the raw outline polygon points from perfect-freehand.
+ * Each point is [x, y]. The result forms a closed polygon that
+ * represents the visual shape of the freedraw stroke.
+ */
+export function getFreeDrawStrokePoints(element) {
+    if (element.points.length === 0) {
+        return [];
+    }
+    const inputPoints = buildInputPoints(element);
+    const options = buildStrokeOptions(element);
+    return getStroke(inputPoints, options);
+}

package/dist/utils/elements/newElement.js

@@ -123,13 +123,22 @@ export const newTextElement = (currentScope, opts) => {
     const textAlign = opts.textAlign || DEFAULT_TEXT_ALIGN;
     const verticalAlign = opts.verticalAlign || DEFAULT_VERTICAL_ALIGN;
     const offsets = getTextElementPositionOffsets({ textAlign, verticalAlign }, metrics);
+    // Minimum dimensions: at least 1px wide, at least one line high (NaN-safe)
+    const rawMinLineHeight = fontSize.value * lineHeight;
+    const minLineHeight = (Number.isFinite(rawMinLineHeight) && rawMinLineHeight > 0)
+        ? rawMinLineHeight
+        : DEFAULT_FONT_SIZE * lineHeight;
+    const finalWidth = (Number.isFinite(metrics.width) && metrics.width > 0) ? metrics.width : 1;
+    const finalHeight = (Number.isFinite(metrics.height) && metrics.height > 0)
+        ? Math.max(metrics.height, minLineHeight)
+        : minLineHeight;
     const x = getPrecisionValueFromRaw(opts.x.value - offsets.x, scope, currentScope);
     const y = getPrecisionValueFromRaw(opts.y.value - offsets.y, scope, currentScope);
     return Object.assign(Object.assign({}, _newElementBase("text", currentScope, Object.assign(Object.assign({}, opts), { x, y }))), { type: "text", text,
         fontSize,
         fontFamily,
         textAlign,
-        verticalAlign, width: getPrecisionValueFromRaw(metrics.width, scope, currentScope), height: getPrecisionValueFromRaw(metrics.height, scope, currentScope), containerId: opts.containerId || null, originalText: (_b = opts.originalText) !== null && _b !== void 0 ? _b : text, autoResize: (_c = opts.autoResize) !== null && _c !== void 0 ? _c : true, lineHeight, 
+        verticalAlign, width: getPrecisionValueFromRaw(finalWidth, scope, currentScope), height: getPrecisionValueFromRaw(finalHeight, scope, currentScope), containerId: opts.containerId || null, originalText: (_b = opts.originalText) !== null && _b !== void 0 ? _b : text, autoResize: (_c = opts.autoResize) !== null && _c !== void 0 ? _c : true, lineHeight, 
         // DucTextStyle properties
         isLtr: (_d = opts.isLtr) !== null && _d !== void 0 ? _d : true, bigFontFamily: opts.bigFontFamily || "sans-serif", lineSpacing: opts.lineSpacing || { type: LINE_SPACING_TYPE.MULTIPLE, value: lineHeight }, obliqueAngle: opts.obliqueAngle || 0, paperTextHeight: opts.paperTextHeight, widthFactor: opts.widthFactor || 1, isUpsideDown: (_e = opts.isUpsideDown) !== null && _e !== void 0 ? _e : false, isBackwards: (_f = opts.isBackwards) !== null && _f !== void 0 ? _f : false, dynamic: opts.dynamic || [] });
 };
@@ -153,11 +162,11 @@ export const newImageElement = (currentScope, opts) => {
 export const newTableElement = (currentScope, opts) => (Object.assign(Object.assign(Object.assign({}, _newElementBase("table", currentScope, opts)), getDefaultTableData(currentScope)), { type: "table" }));
 export const newDocElement = (currentScope, opts) => {
     var _a, _b, _c, _d;
-    return (Object.assign(Object.assign({}, _newElementBase("doc", currentScope, opts)), { type: "doc", text: opts.text || "", dynamic: opts.dynamic || [], flowDirection: opts.flowDirection || TEXT_FLOW_DIRECTION.TOP_TO_BOTTOM, columns: opts.columns || { type: COLUMN_TYPE.NO_COLUMNS, definitions: [], autoHeight: true }, autoResize: (_a = opts.autoResize) !== null && _a !== void 0 ? _a : true, fileId: null, gridConfig: { columns: 1, gapX: 0, gapY: 0, alignItems: 'start', firstPageAlone: false }, 
+    return (Object.assign(Object.assign({}, _newElementBase("doc", currentScope, opts)), { type: "doc", text: opts.text || "", dynamic: opts.dynamic || [], flowDirection: opts.flowDirection || TEXT_FLOW_DIRECTION.TOP_TO_BOTTOM, columns: opts.columns || { type: COLUMN_TYPE.NO_COLUMNS, definitions: [], autoHeight: true }, autoResize: (_a = opts.autoResize) !== null && _a !== void 0 ? _a : true, fileId: null, gridConfig: { columns: 1, gapX: 0, gapY: 0, alignItems: 'start', firstPageAlone: false, scale: 1 }, 
         // DucDocStyle properties
         isLtr: (_b = opts.isLtr) !== null && _b !== void 0 ? _b : true, fontFamily: opts.fontFamily || DEFAULT_FONT_FAMILY, bigFontFamily: opts.bigFontFamily || "sans-serif", textAlign: opts.textAlign || DEFAULT_TEXT_ALIGN, verticalAlign: opts.verticalAlign || DEFAULT_VERTICAL_ALIGN, lineHeight: opts.lineHeight || 1.2, lineSpacing: opts.lineSpacing || { type: LINE_SPACING_TYPE.MULTIPLE, value: 1.2 }, obliqueAngle: opts.obliqueAngle || 0, fontSize: opts.fontSize || getPrecisionValueFromRaw(DEFAULT_FONT_SIZE, currentScope, currentScope), paperTextHeight: opts.paperTextHeight, widthFactor: opts.widthFactor || 1, isUpsideDown: (_c = opts.isUpsideDown) !== null && _c !== void 0 ? _c : false, isBackwards: (_d = opts.isBackwards) !== null && _d !== void 0 ? _d : false, paragraph: opts.paragraph || { firstLineIndent: getPrecisionValueFromRaw(0, currentScope, currentScope), hangingIndent: getPrecisionValueFromRaw(0, currentScope, currentScope), leftIndent: getPrecisionValueFromRaw(0, currentScope, currentScope), rightIndent: getPrecisionValueFromRaw(0, currentScope, currentScope), spaceBefore: getPrecisionValueFromRaw(0, currentScope, currentScope), spaceAfter: getPrecisionValueFromRaw(0, currentScope, currentScope), tabStops: [] }, stackFormat: opts.stackFormat || { autoStack: false, stackChars: [], properties: { upperScale: 0.7, lowerScale: 0.7, alignment: STACKED_TEXT_ALIGN.CENTER } } }));
 };
-export const newPdfElement = (currentScope, opts) => (Object.assign(Object.assign({ fileId: null, gridConfig: { columns: 1, gapX: 0, gapY: 0, alignItems: 'start', firstPageAlone: false } }, _newElementBase("pdf", currentScope, opts)), { type: "pdf" }));
+export const newPdfElement = (currentScope, opts) => (Object.assign(Object.assign({ fileId: null, gridConfig: { columns: 1, gapX: 0, gapY: 0, alignItems: 'start', firstPageAlone: false, scale: 1 } }, _newElementBase("pdf", currentScope, opts)), { type: "pdf" }));
 export const newMermaidElement = (currentScope, opts) => (Object.assign(Object.assign({ source: "", theme: undefined, svgPath: null }, _newElementBase("mermaid", currentScope, opts)), { type: "mermaid" }));
 export const newXRayElement = (currentScope, opts) => (Object.assign(Object.assign({ origin: { x: getPrecisionValueFromRaw(0, currentScope, currentScope), y: getPrecisionValueFromRaw(0, currentScope, currentScope) }, direction: { x: getPrecisionValueFromRaw(1, currentScope, currentScope), y: getPrecisionValueFromRaw(0, currentScope, currentScope) }, startFromOrigin: false, color: '#FF00FF' }, _newElementBase("xray", currentScope, opts)), { type: "xray" }));
 export const newLeaderElement = (currentScope, opts) => {

package/dist/utils/elements/textElement.d.ts

@@ -1,9 +1,9 @@
+import { SupportedMeasures } from "../../technical/scopes";
 import { DucLocalState, RawValue, Scope, ScopedValue } from "../../types";
 import { DucElement, DucElementType, DucTextContainer, DucTextElement, DucTextElementWithContainer, ElementsMap, FontFamilyValues, FontString, NonDeletedDucElement } from "../../types/elements";
 import { GeometricPoint } from "../../types/geometryTypes";
 import { ExtractSetType } from "../../types/utility-types";
 import { getBoundTextElementPosition } from "./linearElement";
-import { SupportedMeasures } from "../../technical/scopes";
 export declare const computeBoundTextPosition: (container: DucElement, boundTextElement: DucTextElementWithContainer, elementsMap: ElementsMap, currentScope: SupportedMeasures) => {
     x: ScopedValue;
     y: ScopedValue;
@@ -49,12 +49,12 @@ export declare const getMinTextElementWidth: (font: FontString, lineHeight: DucT
 /** retrieves text from text elements and concatenates to a single string */
 export declare const getTextFromElements: (elements: readonly DucElement[], separator?: string) => string;
 export declare const getFontFamilyString: ({ fontFamily, }: {
-    fontFamily: FontFamilyValues;
+    fontFamily: FontFamilyValues | string;
 }) => string;
 /** returns fontSize+fontFamily string for assignment to DOM elements */
 export declare const getFontString: ({ fontSize, fontFamily, }: {
     fontSize: DucTextElement["fontSize"];
-    fontFamily: FontFamilyValues;
+    fontFamily: FontFamilyValues | string;
 }) => FontString;
 /** computes element x/y offset based on textAlign/verticalAlign */
 export declare const getTextElementPositionOffsets: (opts: {

package/dist/utils/elements/textElement.js

@@ -1,11 +1,11 @@
 import { TEXT_ALIGN, VERTICAL_ALIGN } from "../../flatbuffers/duc";
+import { getPrecisionValueFromRaw, getScopedBezierPointFromDucPoint } from "../../technical/scopes";
 import { isArrowElement, isBoundToContainer, isTextElement } from "../../types/elements/typeChecks";
 import { getContainerElement, getElementAbsoluteCoords, getResizedElementAbsoluteCoords } from "../bounds";
-import { ARROW_LABEL_FONT_SIZE_TO_MIN_WIDTH_RATIO, ARROW_LABEL_WIDTH_FRACTION, BOUND_TEXT_PADDING, DEFAULT_FONT_FAMILY, DEFAULT_FONT_SIZE, FONT_FAMILY, WINDOWS_EMOJI_FALLBACK_FONT } from "../constants";
-import { getBoundTextElementPosition, getPointGlobalCoordinates, getPointsGlobalCoordinates, getSegmentMidPoint } from "./linearElement";
+import { ARROW_LABEL_FONT_SIZE_TO_MIN_WIDTH_RATIO, ARROW_LABEL_WIDTH_FRACTION, BOUND_TEXT_PADDING, DEFAULT_FONT_FAMILY, DEFAULT_FONT_SIZE, LEGACY_FONT_ID_TO_NAME, WINDOWS_EMOJI_FALLBACK_FONT } from "../constants";
 import { adjustXYWithRotation } from "../math";
 import { normalizeText } from "../normalize";
-import { getPrecisionValueFromRaw, getScopedBezierPointFromDucPoint } from "../../technical/scopes";
+import { getBoundTextElementPosition, getPointGlobalCoordinates, getPointsGlobalCoordinates, getSegmentMidPoint } from "./linearElement";
 export const computeBoundTextPosition = (container, boundTextElement, elementsMap, currentScope) => {
     if (isArrowElement(container)) {
         const coords = getBoundTextElementPosition(container, boundTextElement, elementsMap, currentScope);
@@ -54,10 +54,19 @@ export const measureText = (text, font, lineHeight, currentScope) => {
         // lines would be stripped from computation
         .map((x) => x || " ")
         .join("\n");
-    const fontSize = getPrecisionValueFromRaw(parseFloat(font), currentScope, currentScope);
+    const parsedFontSize = parseFloat(font);
+    // Guard: if font string produced an unparseable size (NaN) or zero,
+    // fall back to DEFAULT_FONT_SIZE so measurements are never degenerate.
+    const safeFontSize = (Number.isFinite(parsedFontSize) && parsedFontSize > 0)
+        ? parsedFontSize
+        : DEFAULT_FONT_SIZE;
+    const fontSize = getPrecisionValueFromRaw(safeFontSize, currentScope, currentScope);
     const height = getTextHeight(text, fontSize, lineHeight);
     const width = getTextWidth(text, font);
-    return { width, height };
+    // Defensive: ensure we never return 0 or NaN dimensions
+    const safeWidth = (Number.isFinite(width) && width > 0) ? width : 1;
+    const safeHeight = (Number.isFinite(height) && height > 0) ? height : (safeFontSize * lineHeight);
+    return { width: safeWidth, height: safeHeight };
 };
 /**
  * We calculate the line height from the font size and the unitless line height,
@@ -104,15 +113,15 @@ const getLineWidth = (text, font, forceAdvanceWidth, isTestEnv) => {
         // fallback to advance width if the actual width is zero, i.e. on text editing start
         // or when actual width does not respect whitespace chars, i.e. spaces
         // otherwise actual width should always be bigger
-        return Math.max(actualWidth, advanceWidth);
+        return Math.ceil(Math.max(actualWidth, advanceWidth));
     }
     // since in test env the canvas measureText algo
     // doesn't measure text and instead just returns number of
     // characters hence we assume that each letteris 10px
     if (isTestEnv) {
-        return advanceWidth * 10;
+        return Math.ceil(advanceWidth * 10);
     }
-    return advanceWidth;
+    return Math.ceil(advanceWidth);
 };
 export const getTextWidth = (text, font, forceAdvanceWidth) => {
     const lines = splitIntoLines(text);
@@ -470,14 +479,20 @@ export const getTextFromElements = (elements, separator = "\n\n") => {
     return text;
 };
 export const getFontFamilyString = ({ fontFamily, }) => {
-    // Handle both number and string fontFamily values
-    const fontFamilyNum = typeof fontFamily === 'string' ? parseInt(fontFamily, 10) : fontFamily;
-    for (const [fontFamilyString, id] of Object.entries(FONT_FAMILY)) {
-        if (id === fontFamilyNum) {
-            return `${fontFamilyString}, ${WINDOWS_EMOJI_FALLBACK_FONT}`;
-        }
-    }
-    return WINDOWS_EMOJI_FALLBACK_FONT;
+    // Handle legacy numeric font IDs from old files
+    if (typeof fontFamily === "number") {
+        const name = LEGACY_FONT_ID_TO_NAME[fontFamily];
+        if (name)
+            return `${name}, ${WINDOWS_EMOJI_FALLBACK_FONT}`;
+        return WINDOWS_EMOJI_FALLBACK_FONT;
+    }
+    // Handle stringified numeric IDs (e.g. "10")
+    const parsed = Number(fontFamily);
+    if (!Number.isNaN(parsed) && LEGACY_FONT_ID_TO_NAME[parsed]) {
+        return `${LEGACY_FONT_ID_TO_NAME[parsed]}, ${WINDOWS_EMOJI_FALLBACK_FONT}`;
+    }
+    // New path: fontFamily is already a string name
+    return `${fontFamily}, ${WINDOWS_EMOJI_FALLBACK_FONT}`;
 };
 /** returns fontSize+fontFamily string for assignment to DOM elements */
 export const getFontString = ({ fontSize, fontFamily, }) => {
@@ -504,6 +519,18 @@ export const refreshTextDimensions = (textElement, container, elementsMap, curre
             : textElement.width.scoped);
     }
     const dimensions = getAdjustedDimensions(textElement, elementsMap, text, currentScope);
+    // Defensive minimums — ensure height is always at least one line.
+    // Use negated >= to also catch NaN (NaN < x is always false).
+    const rawMinLineHeight = textElement.fontSize.value * textElement.lineHeight;
+    const minLineHeight = (Number.isFinite(rawMinLineHeight) && rawMinLineHeight > 0)
+        ? rawMinLineHeight
+        : DEFAULT_FONT_SIZE * textElement.lineHeight;
+    if (!(dimensions.height >= minLineHeight)) {
+        dimensions.height = minLineHeight;
+    }
+    if (!(dimensions.width > 0)) {
+        dimensions.width = (textElement.autoResize ? 1 : textElement.width.value);
+    }
     return Object.assign({ text }, dimensions);
 };
 export const splitIntoLines = (text) => {

package/dist/utils/state/index.js

@@ -78,7 +78,7 @@ export const getDefaultGlobalState = () => {
     return {
         name: null,
         viewBackgroundColor: typeof window !== "undefined" ? (window.matchMedia("(prefers-color-scheme: dark)").matches ? COLOR_PALETTE.night : COLOR_PALETTE.white) : COLOR_PALETTE.white,
-        scopeExponentThreshold: 2,
+        scopeExponentThreshold: 3,
         mainScope: NEUTRAL_SCOPE,
         dashSpacingScale: 1,
         isDashSpacingAffectedByViewportScale: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ducjs",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "The duc 2D CAD file format is a cornerstone of our advanced design system, conceived to cater to professionals seeking precision and efficiency in their design work.",
   "type": "module",
   "main": "dist/index.js",