@mlightcad/mtext-renderer 0.13.4 → 0.13.6

package/lib/font/fontManager.d.ts

@@ -89,10 +89,17 @@ export declare class FontManager {
     /**
      * Fonts whose latest {@link requestFont} failed to fetch or parse the face.
      * Prevents per-glyph retry storms until {@link release} clears state.
-     * Catalog misses (`NotFound`) are not sticky — a later `fonts.json` refresh
-     * must still be able to resolve the name.
      */
     private fontRequestFailed;
+    /**
+     * Session-sticky catalog misses (`NotFound` / empty load result).
+     * Open paths draw tens of thousands of MTEXT entities; re-entering the
+     * loader for the same absent face every draw dominates `requestFontsMs`.
+     * Cleared when the face is registered or on {@link release}. Soft misses
+     * stay recoverable via those paths — they are not retried automatically
+     * mid-open (unlike the previous per-draw NotFound retry behavior).
+     */
+    private fontRequestAbsent;
     /**
      * Names already confirmed absent from IndexedDB during this session.
      * Repeated open-time MTEXT loads must not re-enter IndexedDB for the same miss.
@@ -202,8 +209,18 @@ export declare class FontManager {
      * Requests each font name via {@link requestFont} (deduped per name).
      * Callers may ignore the returned promise for fire-and-forget loads, or
      * await it when they need fonts before drawing.
+     *
+     * When every name is already loaded, failed, or session-absent (or the
+     * list is empty), returns a resolved promise without scheduling
+     * `Promise.all` — open-time paths call this per entity.
      */
     requestFonts(fontNames: readonly string[]): Promise<FontLoadStatus[]>;
+    /**
+     * True when a face still needs an awaitable load attempt (not loaded and
+     * not session-settled as failed/absent). Used by open-time `asyncDraw` to
+     * skip `await requestFonts` once the manager has finished trying.
+     */
+    needsFontLoad(fontName: string): boolean;
     private normalizeFontName;
     /**
      * Returns raw mesh font program bytes from IndexedDB when available.

package/lib/font/meshFont.d.ts

@@ -128,7 +128,7 @@ export declare class MeshFont extends BaseFont {
      * @param size - The size of the text
      * @returns Indexed line-pair BufferGeometry suitable for LineSegments
      */
-    generateStrokeGeometry(text: string, size: number): import('three').BufferGeometry<import('three').NormalBufferAttributes>;
+    generateStrokeGeometry(text: string, size: number): import('three').BufferGeometry<import('three').NormalBufferAttributes, import('three').BufferGeometryEventMap>;
     /**
      * Gets the shape data for a specific character at a given size.
      * @param char - The character to get the shape for

package/lib/font/shxTextShape.d.ts

@@ -38,7 +38,7 @@ export declare class ShxTextShape extends BaseTextShape {
      * Converts the text shape to a THREE.js geometry.
      * @returns A BufferGeometry representing the text shape.
      */
-    toGeometry(): THREE.BufferGeometry<THREE.NormalBufferAttributes>;
+    toGeometry(): THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>;
     /** @inheritdoc */
     hasStrokeGeometry(): boolean;
     /**

package/lib/font/textGeometryBuilder.d.ts

@@ -20,6 +20,7 @@ export declare class TextGeometryBuilder {
      * @returns A single non-indexed line geometry containing all transformed segments.
      */
     static mergeLineGeometries(entries: TransformedLineGeometryEntry[]): THREE.BufferGeometry;
+    private static mergeLineGeometriesUnprofiled;
     /**
      * Counts how many line segments a geometry represents.
      * Indexed geometries use index pairs; non-indexed geometries use consecutive position pairs.
@@ -55,10 +56,11 @@ export declare class TextGeometryBuilder {
      * @returns A single indexed mesh geometry. Empty when `entries` is empty.
      */
     static mergeMeshGeometries(entries: TransformedLineGeometryEntry[]): THREE.BufferGeometry;
+    private static mergeMeshGeometriesUnprofiled;
     /**
      * Writes `position` transformed by `matrix` into `output` at `vertexBase`.
-     * Affine placement matrices keep `w` at 1; the perspective term matches
-     * {@link THREE.Vector3.applyMatrix4} for any other matrix.
+     * Glyph placement matrices are affine (no perspective); that path skips the
+     * per-vertex `w` divide. Non-affine matrices keep full `applyMatrix4` math.
      */
     private static writeTransformedMeshPositions;
 }

package/lib/font/threeFont.d.ts

@@ -1,51 +1,17 @@
-import { BufferGeometry, Shape } from 'three';
+import { BufferGeometry } from 'three';
 import { Font } from 'three/examples/jsm/loaders/FontLoader.js';
 type Direction = 'ltr' | 'rtl' | 'tb';
 /**
- * Extended Font that fixes inner holes for problematic fonts like SimSun.
- * Certain characters have incorrect inner contours (holes), e.g., 面, 限, 用, 色, 8.
+ * Font used for mesh glyphs.
+ *
+ * Filled outlines come from {@link Font.generateShapes}, which delegates to
+ * `ShapePath.toShapes()`. That path correctly classifies holes for fonts such
+ * as SimSun (面, 限, 用, 色, 8) starting with three.js r185 (0.185.1).
+ *
+ * Stroke geometry is still built here: it only needs sampled contours, not
+ * hole classification.
  */
 export declare class ThreeFont extends Font {
-    /**
-     * Generates geometry shapes from the given text and size.
-     *
-     * Algorithm overview:
-     * 1. Split the input text into individual characters.
-     * 2. For each character:
-     *    a. Retrieve the glyph data from the font.
-     *    b. Convert the glyph outline commands into a ShapePath.
-     *       - 'm' → moveTo
-     *       - 'l' → lineTo
-     *       - 'q' → quadraticCurveTo
-     *       - 'b' → cubic bezierCurveTo
-     *    c. Apply scaling to match the requested font size.
-     *    d. Apply offsets for proper placement (supports multiple lines and directions).
-     * 3. Handle text direction:
-     *    - 'ltr': left-to-right
-     *    - 'rtl': right-to-left (characters reversed)
-     *    - 'tb': top-to-bottom (vertical layout)
-     * 4. Collect all ShapePaths for the text.
-     * 5. Convert each ShapePath into one or more Shape objects:
-     *    a. Sample points along each subPath to approximate geometry.
-     *    b. Determine which subPaths are outer contours and which are holes:
-     *       - For each subPath, check if it is fully contained inside another polygon.
-     *       - Assign the smallest containing polygon as its parent.
-     *    c. Compute the relative depth of each subPath to handle nested holes.
-     *    d. Reverse curves if necessary to maintain correct clockwise/counterclockwise winding:
-     *       - Outer contours: CCW
-     *       - Holes: CW
-     *    e. Build Shape objects with holes properly assigned.
-     * 6. Return the final array of Shape objects ready for geometry creation.
-     *
-     * This algorithm ensures that complex characters with multiple independent contours
-     * (including intersecting subpaths or holes) are rendered correctly.
-     *
-     * @param text - input string to convert to shapes
-     * @param size - font size in units (default 100)
-     * @param direction - text direction ('ltr', 'rtl', 'tb')
-     * @returns array of Shape objects with proper holes and contours
-     */
-    generateShapes(text: string, size?: number, direction?: Direction): Shape[];
     /**
      * Samples glyph contours into line-segment geometry without hole detection
      * or triangulation.

package/lib/memory/index.d.ts

@@ -1,5 +1,7 @@
 export { collectIsolateMemoryStats, getMaterialStatsFromStyleManager, readJsHeapStats } from './collectIsolateMemoryStats';
 export { estimateGeometryBytes, estimateStringBytes, formatBytes, getSourceByteLength } from './estimateGeometryBytes';
 export { formatMemoryUsageReport } from './formatMemoryUsageReport';
+export { TextRenderProfiler } from './textRenderProfiler';
+export type { TextRenderProfileSnapshot } from './textRenderProfiler';
 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/textRenderProfiler.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Session-scoped CPU timing for MText / mesh glyph draws.
+ *
+ * Disabled by default so production paths pay only a boolean check.
+ * Enable via {@link TextRenderProfiler.setEnabled} (cad-viewer OPENPROF)
+ * or `globalThis.__MTEXTPROF__ = true`.
+ */
+export interface TextRenderProfileSnapshot {
+    enabled: boolean;
+    /** `asyncDraw` awaiting content/style fonts. */
+    requestFontsMs: number;
+    /**
+     * Tokenize + layout residual inside `processText` after nested glyph/merge
+     * leaf timers are subtracted.
+     */
+    parseLayoutMs: number;
+    /** opentype path → outline string (`_loadGlyphIfNeeded`). */
+    glyphLoadMs: number;
+    /** `generateShapes` / ShapePath construction. */
+    shapeBuildMs: number;
+    /** `new ShapeGeometry(...)` triangulation. */
+    triangulateMs: number;
+    /** Contour stroke sampling (`toStrokeGeometry`). */
+    strokeSampleMs: number;
+    /** Bake position+index + cache insert. */
+    bakeCacheMs: number;
+    cacheHit: number;
+    cacheMiss: number;
+    mergeMeshMs: number;
+    mergeLineMs: number;
+    /** Number of `mergeMeshGeometries` calls. */
+    mergeMeshCalls: number;
+    /** Sum of glyph entries across all mesh merges (≈ placed mesh glyphs). */
+    mergeMeshEntries: number;
+    /** Largest single mesh-merge batch size. */
+    mergeMeshEntriesMax: number;
+    /** Merges with exactly 1 glyph entry. */
+    mergeMeshBucket1: number;
+    /** Merges with 2–8 glyph entries. */
+    mergeMeshBucket2to8: number;
+    /** Merges with 9–32 glyph entries. */
+    mergeMeshBucket9to32: number;
+    /** Merges with 33+ glyph entries. */
+    mergeMeshBucket33plus: number;
+    /** Distinct code points that missed the geometry cache. */
+    uniqueChars: number;
+    /**
+     * Code points represented by {@link uniqueChars} (present on worker deltas so
+     * the main thread can merge sets accurately).
+     */
+    uniqueCharCodes?: number[];
+    /** Glyph placements (instances) during draws. */
+    placedChars: number;
+    vertexCount: number;
+    indexCount: number;
+    /** Worker-side `asyncDraw` wall (from worker delta). */
+    workerBuildMs: number;
+    /** Worker-side `serializeMText`. */
+    serializeMs: number;
+    /** Main-thread wait for worker render response (includes build+serialize+IPC). */
+    transferWaitMs: number;
+    /** Main-thread `reconstructMText`. */
+    reconstructMs: number;
+    /** Number of `syncDraw` / worker builds counted. */
+    drawCount: number;
+}
+/**
+ * Process-wide (per isolate) accumulator for text-render CPU buckets.
+ */
+export declare class TextRenderProfiler {
+    private static _explicitEnabled;
+    private static _stats;
+    /** True when profiling is active in this isolate. */
+    static get enabled(): boolean;
+    /**
+     * Forces profiling on/off. Pass `null` to fall back to `globalThis.__MTEXTPROF__`.
+     */
+    static setEnabled(enabled: boolean | null): void;
+    /** Clears all counters for a new open / benchmark run. */
+    static reset(): void;
+    /** Immutable snapshot of current counters. */
+    static snapshot(includeCodes?: boolean): TextRenderProfileSnapshot;
+    /**
+     * Snapshot suitable for `postMessage`. Used as a per-render delta from
+     * workers and merged on the main thread.
+     */
+    static takeDelta(): TextRenderProfileSnapshot;
+    /**
+     * Merges a worker (or prior) delta into this isolate's accumulator.
+     * Does not merge `enabled`.
+     */
+    static mergeDelta(delta: Partial<TextRenderProfileSnapshot> | null | undefined): void;
+    static addMs(key: 'requestFontsMs' | 'parseLayoutMs' | 'glyphLoadMs' | 'shapeBuildMs' | 'triangulateMs' | 'strokeSampleMs' | 'bakeCacheMs' | 'mergeMeshMs' | 'mergeLineMs' | 'workerBuildMs' | 'serializeMs' | 'transferWaitMs' | 'reconstructMs', ms: number): void;
+    static timeSync<T>(key: Parameters<typeof TextRenderProfiler.addMs>[0], fn: () => T): T;
+    static timeAsync<T>(key: Parameters<typeof TextRenderProfiler.addMs>[0], fn: () => Promise<T>): Promise<T>;
+    /** Sum of leaf geometry timers (for layout residual). */
+    static geometryLeafTotalMs(): number;
+    /**
+     * Records `processText` wall minus nested leaf geometry time as layout residual.
+     */
+    static addProcessTextResidual(wallMs: number, leafMsBefore: number): void;
+    static noteCacheHit(): void;
+    static noteCacheMiss(code?: number): void;
+    static notePlacedChar(): void;
+    static addGeometryCounts(vertexCount: number, indexCount: number): void;
+    /**
+     * Records one `mergeMeshGeometries` batch size for distribution analysis.
+     * Cheap counters only — used to decide merge-opt vs scene-level instancing.
+     */
+    static noteMergeMeshBatch(entryCount: number): void;
+    static noteDraw(): void;
+    /**
+     * Formats a snapshot for OPENPROF / console (Chinese-friendly labels kept short).
+     */
+    static formatReport(snap?: TextRenderProfileSnapshot): string[];
+}

package/lib/renderer/mtext.d.ts

@@ -38,6 +38,11 @@ export declare class MText extends THREE.Object3D {
     private _box;
     /** Lazily built layout data (line geometry + char boxes). */
     private _layoutData;
+    /**
+     * Cached result of {@link MText.getFonts} for {@link _mtextData.text}.
+     * Avoids re-parsing control codes on every {@link asyncDraw}.
+     */
+    private _contentFontNames;
     /** Raw mtext data to draw on demand */
     private _mtextData;
     /**

package/lib/renderer/mtextProcessor.d.ts

@@ -1,7 +1,7 @@
 import { ChangedProperties, MTextParagraphAlignment, MTextToken } from '@mlightcad/mtext-parser';
 import { FontManager } from '../font';
 import { StyleManager } from './styleManager';
-import { ColorSettings, LineLayout, MeshFontRenderMode, MTextFlowDirection, MTextLineSpacingStyle, TextStyle } from './types';
+import { ColorSettings, LineLayout, MeshFontRenderMode, MeshGlyphOutputMode, MTextFlowDirection, MTextLineSpacingStyle, TextStyle } from './types';
 import * as THREE from 'three';
 /**
  * Options for formatting MText.
@@ -57,6 +57,10 @@ export interface MTextFormatOptions {
      * How TrueType/OTF (mesh) glyphs are drawn. Default is `'mesh'`.
      */
     meshFontRenderMode?: MeshFontRenderMode;
+    /**
+     * How filled mesh glyphs are packaged. Default `'merge'`.
+     */
+    meshGlyphOutputMode?: MeshGlyphOutputMode;
 }
 /**
  * Converts parsed MText tokens into positioned THREE.js geometry.
@@ -670,11 +674,17 @@ export declare class MTextProcessor {
      */
     private resolveCharBoxTarget;
     /**
-     * Applies translation on the specified buffer geometries according to text alignment setting.
+     * Applies horizontal translation on the current visual line according to
+     * paragraph alignment.
      *
-     * Translates both geometry vertices and attached char boxes on the current visual line.
+     * Updates merged {@link THREE.BufferGeometry} vertices, {@link MeshGlyphPlacement}
+     * matrices (placement output mode), and attached char boxes.
      */
     private processAlignment;
+    /** Unions axis-aligned bounds of unit glyphs transformed by placement matrices. */
+    private unionBoxFromPlacements;
+    /** Left-multiplies each placement by a translation (same as `geometry.translate`). */
+    private translateMeshGlyphPlacements;
     /**
      * Resolves horizontal advance for an ASCII space in the active font.
      *

package/lib/renderer/types.d.ts

@@ -171,6 +171,24 @@ export declare const createDefaultColorSettings: () => ColorSettings;
  * - `line`: sample glyph contours as line segments (no triangulation)
  */
 export type MeshFontRenderMode = 'mesh' | 'line';
+/**
+ * How filled mesh glyphs are packaged after layout.
+ * - `merge`: bake placements into one BufferGeometry (default)
+ * - `placement`: leave unit glyph geometries + matrices on
+ *   `userData.meshGlyphPlacements` for a scene-level InstancedMesh batcher
+ *   (main-thread only; skips per-entity vertex copy)
+ */
+export type MeshGlyphOutputMode = 'merge' | 'placement';
+/**
+ * One unit-glyph instance emitted when {@link MeshGlyphOutputMode} is
+ * `'placement'`. `geometry` is the shared cache entry — do not dispose it
+ * with the entity.
+ */
+export interface MeshGlyphPlacement {
+    geometry: THREE.BufferGeometry;
+    /** Column-major 4×4 placement (same layout as {@link THREE.Matrix4.elements}). */
+    matrixElements: Float32Array;
+}
 /**
  * Represents the data structure for multiline text (MText) entities.
  * Contains all necessary properties to define the appearance and positioning of text.
@@ -213,7 +231,14 @@ export interface MTextData {
      * `line` draws sampled contours only, skipping triangulation.
      */
     meshFontRenderMode?: MeshFontRenderMode;
+    /**
+     * How filled mesh glyphs are packaged. Default `'merge'`.
+     * `'placement'` is for scene-level InstancedMesh batching (main thread).
+     */
+    meshGlyphOutputMode?: MeshGlyphOutputMode;
 }
+/** `userData` key for {@link MeshGlyphPlacement} arrays on an MText object. */
+export declare const MESH_GLYPH_PLACEMENTS_USERDATA = "meshGlyphPlacements";
 /**
  * Describes one AutoCAD SHAPE entity for rendering.
  */

package/lib/worker/unifiedRenderer.d.ts

@@ -1,5 +1,5 @@
 import { DefaultFontsPreset, FontLoadStatus } from '../font';
-import { MemoryUsageReport } from '../memory';
+import { MemoryUsageReport, TextRenderProfileSnapshot } from '../memory';
 import { StyleManager } from '../renderer';
 import { ColorSettings, MTextData, ShapeData, TextStyle } from '../renderer/types';
 import { MTextObject } from './baseRenderer';
@@ -92,6 +92,15 @@ export declare class UnifiedRenderer {
     replaceMissedFonts(fonts: Record<string, number>): Promise<void>;
     /** Clears session-scoped missed-font bookkeeping on the main thread and workers. */
     clearMissedFonts(): Promise<void>;
+    /**
+     * Enables or disables {@link TextRenderProfiler} on the main thread and worker pool.
+     * When enabling, counters are reset for a fresh open-file session.
+     */
+    setTextRenderProfilerEnabled(enabled: boolean): Promise<void>;
+    /** Resets main-thread text profiler counters (worker deltas merge into main). */
+    resetTextRenderProfiler(): void;
+    /** Snapshot of merged main + worker text-render timings. */
+    getTextRenderProfile(): TextRenderProfileSnapshot;
     /**
      * Returns font names for a predefined default-font preset.
      */

package/lib/worker/webWorkerRenderer.d.ts

@@ -202,6 +202,10 @@ export declare class WebWorkerRenderer implements MTextBaseRenderer {
      * Render MText in one worker and return serialized data asynchronously.
      */
     asyncRenderMText(mtextContent: MTextData, textStyle: TextStyle, colorSettings?: ColorSettings): Promise<MTextObject>;
+    /**
+     * Enables or disables {@link TextRenderProfiler} on every worker isolate.
+     */
+    setTextRenderProfilerEnabled(enabled: boolean): Promise<void>;
     /**
      * Render MText synchronously.
      * Notes: It isn't supported yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlightcad/mtext-renderer",
-  "version": "0.13.4",
+  "version": "0.13.6",
   "description": "AutoCAD MText renderer based on Three.js",
   "license": "MIT",
   "author": "MLight Lee <mlight.lee@outlook.com>",
@@ -51,12 +51,13 @@
   "devDependencies": {
     "@mlightcad/mtext-parser": "^1.5.5",
     "@types/opentype.js": "^1.3.10",
-    "@types/three": "^0.172.0",
+    "@types/three": "^0.186.0",
+    "three": "^0.186.1",
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
     "@mlightcad/mtext-parser": "^1.5.5",
-    "three": "^0.172.0"
+    "three": ">=0.185.1"
   },
   "scripts": {
     "build": "tsc && vite build -c vite.config.main.ts && vite build -c vite.config.worker.ts",