@mlightcad/mtext-renderer 0.11.9 → 0.12.0

package/lib/cache/fontCacheManager.d.ts

@@ -1,4 +1,5 @@
 import { FontData } from '../font';
+import { IndexedDbFontCacheStats } from '../memory/types';
 /**
  * A simple font cache interface that provides map-like operations for font data
  */
@@ -42,6 +43,14 @@ export declare class FontCacheManager {
      * @returns An array of all font data in the cache
      */
     getAll(): Promise<FontData[]>;
+    /**
+     * Estimates IndexedDB font-blob storage size.
+     *
+     * @remarks
+     * This loads all cached font payloads into the JS heap temporarily via
+     * {@link getAll}, then measures each `data` ArrayBuffer.
+     */
+    getStorageStats(): Promise<IndexedDbFontCacheStats>;
     /**
      * Clears all fonts from the cache
      */

package/lib/common/lruCache.d.ts

@@ -53,6 +53,18 @@ export declare class LRUCache<K, V> {
      * @returns True if the key is present; otherwise, false.
      */
     has(key: K): boolean;
+    /**
+     * Number of entries currently stored in the cache.
+     */
+    get size(): number;
+    /**
+     * Maximum number of entries this cache may retain.
+     */
+    get capacity(): number;
+    /**
+     * Iterates over cached values without updating recency order.
+     */
+    values(): IterableIterator<V>;
     /**
      * Removes all entries from the cache.
      *

package/lib/font/baseFont.d.ts

@@ -1,3 +1,4 @@
+import { FontMemoryStats } from '../memory/types';
 import { BaseTextShape } from './baseTextShape';
 import { CharGeometryCache } from './charGeometryCache';
 import { FontData, FontType } from './font';
@@ -23,11 +24,26 @@ export declare abstract class BaseFont {
      * https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings
      */
     encoding?: string;
+    /**
+     * Byte length of the original font file payload when known (ArrayBuffer / TypedArray).
+     * Used as the basis for parsed-font memory heuristics.
+     */
+    readonly sourceByteLength: number;
     /**
      * Caching of font character geometries to improve text rendering performance.
      */
     cache: CharGeometryCache;
     constructor(fontData: FontData);
+    /**
+     * Estimates memory used by this font instance (parsed data + caches).
+     * Only reports resources still retained by this font (not disposed/released caches).
+     */
+    abstract estimateMemoryUsage(): FontMemoryStats;
+    /**
+     * Releases cache resources held by this font so they are eligible for GC
+     * and no longer appear in {@link estimateMemoryUsage}.
+     */
+    dispose(): void;
     /**
      * Return true if this font contains glyph of the specified character. Otherwise, return false.
      * @param char - The character to check

package/lib/font/charGeometryCache.d.ts

@@ -1,3 +1,4 @@
+import { CacheBucketStats } from '../memory/types';
 import * as THREE from 'three';
 /**
  * Manages caching of font character geometries to improve text rendering performance.
@@ -5,6 +6,7 @@ import * as THREE from 'three';
  */
 export declare class CharGeometryCache {
     private readonly cache;
+    private readonly maxSize;
     constructor(maxSize?: number);
     /**
      * Returns true if the geometry of the specified character code exists in the cache.
@@ -31,6 +33,10 @@ export declare class CharGeometryCache {
      * @param geometry The geometry to set.
      */
     setGeometry(code: number, size: number, geometry: THREE.BufferGeometry): void;
+    /**
+     * Estimates memory used by cached BufferGeometry attribute/index buffers.
+     */
+    getStats(): CacheBucketStats;
     /**
      * Dispose all cached geometries.
      */

package/lib/font/fontManager.d.ts

@@ -1,5 +1,6 @@
 import { ShxFontType } from '@mlightcad/shx-parser';
 import { EventManager } from '../common';
+import { IsolateMemoryStats, MaterialMemoryStats } from '../memory/types';
 import { BaseFont } from './baseFont';
 import { BaseTextShape } from './baseTextShape';
 import { DefaultFontsPreset } from './defaultFontsPresets';
@@ -292,6 +293,9 @@ export declare class FontManager {
      * - If no argument is provided, all loaded fonts are released and the font map is cleared.
      * - If a font name is provided, only that specific font is released from the font map.
      *
+     * Disposes per-font caches before dropping references so released resources are
+     * not retained and are excluded from {@link estimateMemoryUsage}.
+     *
      * This is useful for freeing up memory, especially when working with large font files (e.g., Chinese mesh fonts).
      * Notes: Based on testing, one Chinese mesh font file may take 40M memory.
      *
@@ -299,4 +303,17 @@ export declare class FontManager {
      * @returns `true` if the operation succeeded (all fonts released or the specified font was found and deleted), `false` if the specified font was not found.
      */
     release(fontToRelease?: string): boolean;
+    /**
+     * Estimates memory used by loaded fonts in this isolate.
+     *
+     * Font aliases that point at the same instance are counted once.
+     * Does not include IndexedDB blobs or other isolates (workers).
+     *
+     * @param options - Optional isolate id, material stats, and in-flight request count.
+     */
+    estimateMemoryUsage(options?: {
+        id?: string;
+        materials?: MaterialMemoryStats;
+        inFlightRequests?: number;
+    }): IsolateMemoryStats;
 }

package/lib/font/meshFont.d.ts

@@ -1,4 +1,5 @@
 import { FontData as ThreeFontData } from 'three/examples/jsm/loaders/FontLoader.js';
+import { FontMemoryStats } from '../memory/types';
 import { BaseFont } from './baseFont';
 import { FontData } from './font';
 import { MeshTextShape } from './meshTextShape';
@@ -148,5 +149,13 @@ export declare class MeshFont extends BaseFont {
      * @returns The shape data for the not found indicator
      */
     getNotFoundTextShape(size: number): MeshTextShape;
+    /**
+     * Estimates memory used by this mesh font (parsed opentype + glyphs + geometry cache).
+     */
+    estimateMemoryUsage(): FontMemoryStats;
+    /**
+     * Clears glyph and geometry caches. Does not unload the opentype parse until GC.
+     */
+    dispose(): void;
 }
 export {};

package/lib/font/shxFont.d.ts

@@ -1,4 +1,5 @@
 import { ShxFontData, ShxFontMetrics } from '@mlightcad/shx-parser';
+import { FontMemoryStats } from '../memory/types';
 import { BaseFont } from './baseFont';
 import { FontData } from './font';
 import { ShxTextShape } from './shxTextShape';
@@ -93,6 +94,14 @@ export declare class ShxFont extends BaseFont {
      * @returns The fallback shape, or undefined if it cannot be built.
      */
     getNotFoundTextShape(size: number): ShxTextShape | undefined;
+    /**
+     * Estimates memory used by this SHX font (parsed tables + layout/geometry caches).
+     */
+    estimateMemoryUsage(): FontMemoryStats;
+    /**
+     * Clears layout/code caches and disposes retained shape geometries.
+     */
+    dispose(): void;
     /**
      * Resolves the internal SHX character code for a given Unicode character.
      * @param char - The input character.

package/lib/font/shxTextShape.d.ts

@@ -41,4 +41,12 @@ export declare class ShxTextShape extends BaseTextShape {
     toGeometry(): THREE.BufferGeometry<THREE.NormalBufferAttributes>;
     /** @inheritdoc */
     hasStrokeGeometry(): boolean;
+    /**
+     * Estimated bytes of the lazily built BufferGeometry, or 0 if not built / disposed.
+     */
+    estimateMemoryBytes(): number;
+    /**
+     * Disposes the lazily built BufferGeometry, if any.
+     */
+    dispose(): void;
 }

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 export { getColorByIndex } from './common';
 export * from './common/eventManager';
 export * from './font';
+export * from './memory';
 export * from './shxParser';
 export * from './renderer';
 export * from './worker';

package/lib/memory/collectIsolateMemoryStats.d.ts

@@ -0,0 +1,20 @@
+import { FontManager } from '../font/fontManager';
+import { StyleManager } from '../renderer/styleManager';
+import { IsolateMemoryStats, MaterialMemoryStats, MemoryUsageReport } from './types';
+/**
+ * Reads material stats from a style manager when it exposes `getMaterialStats`.
+ */
+export declare function getMaterialStatsFromStyleManager(styleManager?: StyleManager | null): MaterialMemoryStats;
+/**
+ * Builds isolate stats from a FontManager and optional style manager.
+ */
+export declare function collectIsolateMemoryStats(fontManager: FontManager, options: {
+    id: string;
+    styleManager?: StyleManager | null;
+    materials?: MaterialMemoryStats;
+    inFlightRequests?: number;
+}): IsolateMemoryStats;
+/**
+ * Reads Chrome `performance.memory` when available.
+ */
+export declare function readJsHeapStats(): MemoryUsageReport['jsHeap'] | undefined;

package/lib/memory/estimateGeometryBytes.d.ts

@@ -0,0 +1,18 @@
+import * as THREE from 'three';
+/**
+ * Sums TypedArray byte lengths of all attributes and the index on a BufferGeometry.
+ * Returns 0 for missing or already-disposed geometries.
+ */
+export declare function estimateGeometryBytes(geometry: THREE.BufferGeometry | undefined | null): number;
+/**
+ * UTF-16 string byte length (JavaScript strings are UTF-16 code units).
+ */
+export declare function estimateStringBytes(value: string | undefined | null): number;
+/**
+ * Best-effort source byte length from raw font payload.
+ */
+export declare function getSourceByteLength(data: unknown): number;
+/**
+ * Formats a byte count as a short human-readable string.
+ */
+export declare function formatBytes(bytes: number): string;

package/lib/memory/formatMemoryUsageReport.d.ts

@@ -0,0 +1,5 @@
+import { MemoryUsageReport } from './types';
+/**
+ * Formats a {@link MemoryUsageReport} for console logging.
+ */
+export declare function formatMemoryUsageReport(report: MemoryUsageReport): string;

package/lib/memory/index.d.ts

@@ -0,0 +1,5 @@
+export { collectIsolateMemoryStats, getMaterialStatsFromStyleManager, readJsHeapStats } from './collectIsolateMemoryStats';
+export { estimateGeometryBytes, estimateStringBytes, formatBytes, getSourceByteLength } from './estimateGeometryBytes';
+export { formatMemoryUsageReport } from './formatMemoryUsageReport';
+export { emptyMaterialStats, estimateMaterialBytes, MATERIAL_ESTIMATED_BYTES, MESH_PARSED_FONT_OVERHEAD, SHX_PARSED_FONT_OVERHEAD } from './types';
+export type { CacheBucketStats, FontMemoryStats, IndexedDbFontCacheStats, IsolateMemoryStats, MaterialMemoryStats, MemoryUsageReport } from './types';

package/lib/memory/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Approximate byte size of one cached Three.js material entry.
+ * Materials are small compared to fonts; this is a fixed heuristic.
+ */
+export declare const MATERIAL_ESTIMATED_BYTES = 512;
+/**
+ * Estimates material cache bytes from counts.
+ */
+export declare function estimateMaterialBytes(meshCount: number, lineCount: number): number;
+/**
+ * Multiplier applied to mesh font source bytes to estimate opentype.js parse overhead.
+ * Aligned with the documented ~40MB resident cost for large CJK mesh fonts.
+ */
+export declare const MESH_PARSED_FONT_OVERHEAD = 2.5;
+/**
+ * Multiplier applied to SHX font source bytes to estimate parsed SHX tables.
+ */
+export declare const SHX_PARSED_FONT_OVERHEAD = 1.5;
+/**
+ * Entry-count and estimated byte size for one cache bucket.
+ */
+export interface CacheBucketStats {
+    entries: number;
+    maxEntries: number;
+    estimatedBytes: number;
+}
+/**
+ * Material cache occupancy for a style manager.
+ */
+export interface MaterialMemoryStats {
+    meshCount: number;
+    lineCount: number;
+    estimatedBytes: number;
+}
+/**
+ * Empty material stats when no style manager is available.
+ */
+export declare function emptyMaterialStats(): MaterialMemoryStats;
+/**
+ * Per-font memory estimate (parsed font + caches).
+ *
+ * @remarks
+ * `parsedFontEstimatedBytes` is heuristic (source size × overhead). Geometry
+ * buffers and outline strings are measured from TypedArrays / string lengths.
+ */
+export interface FontMemoryStats {
+    names: string[];
+    type: 'mesh' | 'shx';
+    sourceByteLength: number;
+    parsedFontEstimatedBytes: number;
+    charGeometryCache: CacheBucketStats;
+    meshGlyphs?: {
+        glyphCount: number;
+        outlineStringBytes: number;
+    };
+    shxLayoutCache?: CacheBucketStats;
+    estimatedBytes: number;
+}
+/**
+ * Memory estimate for one JS isolate (main thread or a single worker).
+ */
+export interface IsolateMemoryStats {
+    id: string;
+    inFlightRequests?: number;
+    fonts: FontMemoryStats[];
+    materials: MaterialMemoryStats;
+    totalEstimatedBytes: number;
+}
+/**
+ * IndexedDB persistent font-blob storage stats.
+ *
+ * @remarks
+ * Collecting these stats loads font blobs into the JS heap temporarily.
+ */
+export interface IndexedDbFontCacheStats {
+    fontCount: number;
+    totalBytes: number;
+    fonts: Array<{
+        name: string;
+        type: string;
+        bytes: number;
+    }>;
+}
+/**
+ * Aggregated memory usage report for mtext-renderer.
+ *
+ * @remarks
+ * This is an estimate, not a heap snapshot.
+ * {@link MemoryUsageReport.totalEstimatedBytes} counts live isolate memory only
+ * (still-loaded fonts and caches). IndexedDB storage is listed separately and
+ * is not part of the total. Scene-held MText objects created by the application
+ * are not included. Released / disposed font caches are excluded.
+ */
+export interface MemoryUsageReport {
+    collectedAt: number;
+    /** Live isolate memory only; excludes IndexedDB and disposed resources. */
+    totalEstimatedBytes: number;
+    mainThread: IsolateMemoryStats;
+    workers: IsolateMemoryStats[];
+    /** Persistent disk/IDB cache; not included in {@link totalEstimatedBytes}. */
+    indexedDbFontCache: IndexedDbFontCacheStats;
+    jsHeap?: {
+        usedJSHeapSize: number;
+        totalJSHeapSize: number;
+        jsHeapSizeLimit: number;
+    };
+}

package/lib/renderer/constants.d.ts

@@ -1,8 +1,15 @@
 /**
- * Scale applied with `lineSpaceFactor` when computing the extra vertical gap
- * between MTEXT lines in {@link MTextProcessor}.
+ * AutoCAD single-line spacing as a multiple of text height ("3-on-5").
+ *
+ * DXF group 44 (`lineSpaceFactor`) is a ratio relative to this single spacing,
+ * so baseline-to-baseline distance =
+ * `lineSpaceFactor × LINE_SPACING_SCALE_FACTOR × textHeight`.
  */
-export declare const LINE_SPACING_SCALE_FACTOR = 1.666666;
+export declare const LINE_SPACING_SCALE_FACTOR: number;
+/**
+ * Default DXF group-44 line spacing factor (AutoCAD single spacing).
+ */
+export declare const DEFAULT_LINE_SPACE_FACTOR = 1;
 /**
  * Vertical compensation needed after switching normal glyph placement from
  * top-anchored to baseline-anchored coordinates.

package/lib/renderer/defaultStyleManager.d.ts

@@ -1,3 +1,4 @@
+import { MaterialMemoryStats } from '../memory/types';
 import { StyleManager } from './styleManager';
 import { ColorSettings } from './types';
 import * as THREE from 'three';
@@ -10,6 +11,10 @@ export declare class DefaultStyleManager implements StyleManager {
     unsupportedTextStyles: Record<string, number>;
     getMeshBasicMaterial(colorSettings: ColorSettings): THREE.Material;
     getLineBasicMaterial(colorSettings: ColorSettings): THREE.Material;
+    /**
+     * Returns occupancy of the material caches (counts + heuristic bytes).
+     */
+    getMaterialStats(): MaterialMemoryStats;
     /**
      * Builds a stable material key from traits.
      * Key differs for shader vs basic, ByLayer vs ByEntity.

package/lib/renderer/mtextProcessor.d.ts

@@ -16,7 +16,8 @@ export interface MTextFormatOptions {
      */
     widthFactor: number;
     /**
-     * The line space factor.
+     * AutoCAD DXF group-44 line spacing factor: ratio of actual line spacing to
+     * single spacing (`5/3` of text height). Default is `1.0`.
      */
     lineSpaceFactor: number;
     /**
@@ -165,7 +166,8 @@ export declare class MTextProcessor {
      */
     get defaultFontSize(): number;
     /**
-     * The default line space factor
+     * AutoCAD DXF group-44 line spacing factor (multiple of single spacing).
+     * Single spacing is {@link LINE_SPACING_SCALE_FACTOR} × text height.
      */
     get defaultLineSpaceFactor(): number;
     /**
@@ -191,7 +193,11 @@ export declare class MTextProcessor {
      */
     get currentLayoutFontSize(): number;
     /**
-     * The height of current line of texts
+     * Baseline-to-baseline advance for the current line (AutoCAD MTEXT semantics).
+     *
+     * Single spacing is `5/3` of the drawing-space text height; `lineSpaceFactor`
+     * (DXF group 44) scales that distance. Font glyph scale factors must not
+     * affect this layout metric — use {@link currentLayoutFontSize}.
      */
     get currentLineHeight(): number;
     /**

package/lib/renderer/types.d.ts

@@ -170,7 +170,11 @@ export interface MTextData {
     attachmentPoint?: MTextAttachmentPoint;
     /** Determines the primary direction in which text flows */
     drawingDirection?: MTextFlowDirection;
-    /** Factor that controls the spacing between text lines. Default is 1.0 */
+    /**
+     * AutoCAD DXF group-44 line spacing factor.
+     * Ratio of actual baseline spacing to single spacing (`5/3` of text height).
+     * Default is `1.0`.
+     */
     lineSpaceFactor?: number;
     /** The width scaling factor applied to each character. Default is 1.0 */
     widthFactor?: number;

package/lib/worker/mainThreadRenderer.d.ts

@@ -1,3 +1,4 @@
+import { IsolateMemoryStats } from '../memory';
 import { StyleManager } from '../renderer/styleManager';
 import { ColorSettings, MTextData, ShapeData, TextStyle } from '../renderer/types';
 import { MTextBaseRenderer, MTextObject } from './baseRenderer';
@@ -46,6 +47,10 @@ export declare class MainThreadRenderer implements MTextBaseRenderer {
             name: string[];
         }>;
     }>;
+    /**
+     * Estimates memory used by fonts and materials in the main-thread isolate.
+     */
+    estimateMemoryUsage(): IsolateMemoryStats;
     destroy(): void;
     private ensureInitialized;
 }

package/lib/worker/unifiedRenderer.d.ts

@@ -1,4 +1,5 @@
 import { DefaultFontsPreset, FontLoadStatus } from '../font';
+import { MemoryUsageReport } from '../memory';
 import { StyleManager } from '../renderer';
 import { ColorSettings, MTextData, ShapeData, TextStyle } from '../renderer/types';
 import { MTextObject } from './baseRenderer';
@@ -89,6 +90,19 @@ export declare class UnifiedRenderer {
             name: string[];
         }>;
     }>;
+    /**
+     * Estimates memory used by mtext-renderer across the main thread and workers.
+     *
+     * @remarks
+     * `totalEstimatedBytes` covers **live** isolate memory only (fonts still loaded
+     * in memory, caches, materials). IndexedDB font blobs are reported separately
+     * under {@link MemoryUsageReport.indexedDbFontCache} and are **not** included
+     * in the total — they remain after {@link FontManager.release}. Disposed /
+     * released font caches are excluded. Application-held scene graphs are not
+     * included. Collecting IndexedDB stats temporarily loads cached blobs into
+     * the JS heap.
+     */
+    estimateMemoryUsage(): Promise<MemoryUsageReport>;
     /**
      * Parse and cache a user-uploaded font file in IndexedDB.
      * Always runs on the main-thread {@link FontManager} so the cache is shared

package/lib/worker/webWorkerRenderer.d.ts

@@ -1,3 +1,4 @@
+import { IsolateMemoryStats } from '../memory/types';
 import { StyleManager } from '../renderer/styleManager';
 import { CharBox, ColorSettings, MTextData, ShapeData, TextStyle } from '../renderer/types';
 import { MTextBaseRenderer, MTextObject } from './baseRenderer';
@@ -181,6 +182,13 @@ export declare class WebWorkerRenderer implements MTextBaseRenderer {
             name: string[];
         }>;
     }>;
+    /**
+     * Collects memory estimates from each worker in the pool.
+     *
+     * Worker ids are rewritten to `worker-0`, `worker-1`, … and
+     * {@link inFlightPerWorker} counts are attached.
+     */
+    estimateMemoryUsage(): Promise<IsolateMemoryStats[]>;
     /**
      * Reconstruct MText object from JSON serialized data
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlightcad/mtext-renderer",
-  "version": "0.11.9",
+  "version": "0.12.0",
   "description": "AutoCAD MText renderer based on Three.js",
   "license": "MIT",
   "author": "MLight Lee <mlight.lee@outlook.com>",