@mlightcad/mtext-renderer 0.12.12 → 0.13.0

package/lib/font/baseTextShape.d.ts

@@ -14,6 +14,14 @@ export declare abstract class BaseTextShape extends THREE.Shape {
      * @returns A THREE.js BufferGeometry representing the text shape
      */
     abstract toGeometry(): THREE.BufferGeometry;
+    /**
+     * Uniform XY scale applied to {@link toGeometry} when placing the glyph.
+     *
+     * Mesh fonts cache unit-size outlines and report the requested font size here
+     * so one geometry serves every height. SHX stroke geometries are already
+     * sized and leave this at `1`.
+     */
+    get geometryScale(): number;
     /**
      * Whether the shape has drawable stroke or mesh geometry (not advance-only).
      */

package/lib/font/fontManager.d.ts

@@ -87,10 +87,18 @@ export declare class FontManager {
     /** In-flight {@link requestFont} promises keyed by normalized font name. */
     private fontRequestInFlight;
     /**
-     * Fonts whose latest {@link requestFont} finished without registering the
-     * face. Prevents per-glyph retry storms until {@link release} clears state.
+     * 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;
+    /**
+     * Names already confirmed absent from IndexedDB during this session.
+     * Repeated open-time MTEXT loads must not re-enter IndexedDB for the same miss.
+     * Cleared when the face is registered or {@link release} drops all fonts.
+     */
+    private fontCacheLookupMisses;
     /**
      * Bumped by full {@link release} so in-flight loads that complete after a
      * release do not re-register fonts into a cleared manager.

package/lib/font/index.d.ts

@@ -6,3 +6,4 @@ export * from './font';
 export * from './fontFactory';
 export * from './fontLoader';
 export * from './fontManager';
+export * from './meshGlyphGeometry';

package/lib/font/meshFont.d.ts

@@ -67,7 +67,7 @@ export declare class MeshFont extends BaseFont {
     readonly data: MeshFontData;
     /** Internal opentype.js font instance used for on-demand glyph parsing */
     private readonly opentypeFont;
-    /** Glyph cache to limit memory usage */
+    /** Glyph cache to limit memory usage; eviction removes entries from {@link data.glyphs}. */
     private readonly glyphCache;
     /**
      * Creates a new instance of MeshFont.

package/lib/font/meshFontScaleFactor.d.ts

@@ -18,27 +18,13 @@ export interface MeshFontScaleSource {
     charToGlyph: (char: string) => MeshFontScaleGlyph | undefined;
     charToGlyphIndex: (char: string) => number | null | undefined;
 }
-/**
- * Threshold above which a Latin-'A'-based scale is treated as unsafe for fonts
- * that also contain full-em CJK ideographs (SimSun / SimFang / etc.).
- */
-export declare const CJK_LATIN_SCALE_INFLATION_THRESHOLD = 1.15;
-/**
- * Fraction of the em square at which an ideograph advance is treated as a
- * full-cell CJK design glyph.
- */
-export declare const CJK_FULL_EM_ADVANCE_RATIO = 0.9;
 /**
  * Computes the mesh-font scale that maps CAD text height onto glyph outlines.
  *
- * AutoCAD maps TrueType text height to the font design size. For Western faces,
- * capital {@code A} height is a good proxy (`unitsPerEm / A.yMax`). For CJK
- * faces, ideographs occupy the full em while Latin capitals are much shorter —
- * using {@code A.yMax} then inflates both glyph size and advance (~1.4× for
- * SimFang/SimSun), which falsely wraps MTEXT that AutoCAD keeps on one line.
- *
- * When the font has full-em ideographs and the Latin-based scale would inflate
- * advances past {@link CJK_LATIN_SCALE_INFLATION_THRESHOLD}, return {@code 1}
- * so text height maps to the em square (AutoCAD CJK TrueType behavior).
+ * AutoCAD maps TrueType text height to the capital-letter height of the face
+ * (`unitsPerEm / A.yMax`). That scale applies to CJK faces as well: ideographs
+ * occupy most of the em, so their advances become larger than the nominal text
+ * height. Using the em square alone (`1`) under-sizes both glyphs and advances,
+ * which delays soft wraps and shortens the MTEXT block relative to AutoCAD.
  */
 export declare function computeMeshFontScaleFactor(font: MeshFontScaleSource): number;

package/lib/font/meshGlyphGeometry.d.ts

@@ -0,0 +1,23 @@
+import type * as THREE from 'three';
+/**
+ * `userData` flag marking BufferGeometry produced for mesh (TTF/OTF) glyphs.
+ *
+ * Cached glyphs are baked to position and index buffers, so callers must not
+ * rely on `instanceof ShapeGeometry` to distinguish mesh glyphs from SHX
+ * stroke geometry.
+ */
+export declare const MESH_GLYPH_USER_DATA_KEY = "isMeshGlyph";
+/**
+ * Canonical size stored in {@link CharGeometryCache} for mesh glyphs.
+ * Placement scales by {@link MeshTextShape.geometryScale} (= requested size).
+ */
+export declare const MESH_GLYPH_CACHE_SIZE = 1;
+/**
+ * Returns true when `geometry` is a mesh-font glyph (filled outline),
+ * including geometries baked down to a plain {@link THREE.BufferGeometry}.
+ */
+export declare function isMeshGlyphGeometry(geometry: THREE.BufferGeometry): boolean;
+/**
+ * Marks a geometry as a mesh glyph so downstream batching keeps the filled-mesh path.
+ */
+export declare function markMeshGlyphGeometry(geometry: THREE.BufferGeometry): void;

package/lib/font/meshTextShape.d.ts

@@ -16,9 +16,14 @@ export declare class MeshTextShape extends BaseTextShape {
     private readonly font;
     private readonly fontSize;
     constructor(char: string, fontSize: number, font: MeshFont);
+    /**
+     * Scale from the unit-size cached outline to the requested drawing height.
+     */
+    get geometryScale(): number;
     /**
      * Converts the text shape to a THREE.js geometry.
-     * This is used for 3D rendering of the text.
+     * Outlines are cached once at {@link MESH_GLYPH_CACHE_SIZE}; callers must
+     * apply {@link geometryScale} when placing the glyph.
      * @returns A THREE.js BufferGeometry representing the text shape
      */
     toGeometry(): THREE.BufferGeometry;

package/lib/font/shxFont.d.ts

@@ -75,6 +75,10 @@ export declare class ShxFont extends BaseFont {
      * @returns The shape data for the code, or undefined if not found.
      */
     getCodeShape(code: number, size: number): ShxTextShape | undefined;
+    /**
+     * Snaps near-equal heights so layout/geometry cache keys hit across float noise.
+     */
+    private static quantizeSize;
     /**
      * Gets the shape data for a named SHX shape at the requested size.
      * @param name - The SHX shape name to look up.

package/lib/font/textGeometryBuilder.d.ts

@@ -44,4 +44,21 @@ export declare class TextGeometryBuilder {
      * @returns The next write offset after all segments have been written.
      */
     private static writeTransformedLineSegments;
+    /**
+     * Merges indexed mesh glyphs into one indexed triangle geometry, applying each
+     * glyph matrix while copying vertices.
+     *
+     * One write pass replaces per-glyph `clone` + `applyMatrix4` followed by a
+     * second copy inside `mergeGeometries`.
+     *
+     * @param entries Cached glyph geometries paired with their placement matrices.
+     * @returns A single indexed mesh geometry. Empty when `entries` is empty.
+     */
+    static mergeMeshGeometries(entries: TransformedLineGeometryEntry[]): THREE.BufferGeometry;
+    /**
+     * 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.
+     */
+    private static writeTransformedMeshPositions;
 }

package/lib/index.d.ts

@@ -5,4 +5,3 @@ export * from './memory';
 export * from './shxParser';
 export * from './renderer';
 export * from './worker';
-export * from '@mlightcad/mtext-parser';

package/lib/renderer/constants.d.ts

@@ -10,6 +10,12 @@ 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;
+/**
+ * Default DXF group-73 line spacing style (AutoCAD "At Least").
+ *
+ * DXF may omit group 73 or write `0`; both mean At Least.
+ */
+export declare const DEFAULT_LINE_SPACE_STYLE = 1;
 /**
  * Vertical compensation needed after switching normal glyph placement from
  * top-anchored to baseline-anchored coordinates.

package/lib/renderer/mtext.d.ts

@@ -47,7 +47,8 @@ export declare class MText extends THREE.Object3D {
      *
      * @param mtext - The MText string to analyze for font names
      * @param removeExtension - Whether to remove font file extensions (e.g., .ttf, .shx) from font names. Defaults to false.
-     * @returns A Set containing all unique font names found in the MText string, converted to lowercase
+     * @returns A Set containing all unique font names found in the MText string, converted to lowercase.
+     * SHX pairs such as `\Ftssdeng,hztxt|c134;` contribute both the primary face and the big font.
      * @example
      * ```ts
      * const mtext = "\\fArial.ttf|Hello\\fTimes New Roman.otf|World";

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, MTextFlowDirection, TextStyle } from './types';
+import { ColorSettings, LineLayout, MTextFlowDirection, MTextLineSpacingStyle, TextStyle } from './types';
 import * as THREE from 'three';
 /**
  * Options for formatting MText.
@@ -20,6 +20,11 @@ export interface MTextFormatOptions {
      * single spacing (`5/3` of text height). Default is `1.0`.
      */
     lineSpaceFactor: number;
+    /**
+     * AutoCAD DXF group-73 line spacing style.
+     * `1` / omitted / `0` = At Least, `2` = Exact.
+     */
+    lineSpaceStyle?: number;
     /**
      * The horizontal alignment.
      */
@@ -84,6 +89,11 @@ export declare class MTextProcessor {
     private _currentContext;
     /** Largest font size encountered on the current visual line. */
     private _maxFontSize;
+    /**
+     * Maximum drawing-space (layout) font size on the current line.
+     * Used by At Least line spacing so font glyph scale factors do not inflate the floor.
+     */
+    private _maxLayoutFontSize;
     /**
      * The current horizontal alignment for the paragraph.
      *
@@ -111,12 +121,20 @@ export declare class MTextProcessor {
     private _processedCharCount;
     /** Line glyph entries collected for batch geometry merge within a style segment. */
     private _lineBatchEntries;
+    /** Mesh glyph entries collected for a single-pass triangle merge within a style segment. */
+    private _meshBatchEntries;
     /** Current paragraph first-line indent in drawing units. */
     private _currentIndent;
     /** Current paragraph left margin in drawing units. */
     private _currentLeftMargin;
     /** Current paragraph right margin in drawing units. */
     private _currentRightMargin;
+    /**
+     * When true, {@link processChar} will not soft-wrap even if the pen is past the
+     * defined width. Used while finishing a short word that AutoCAD keeps on the
+     * current line with a slight overhang.
+     */
+    private _suppressSoftWrap;
     /**
      * Construct one instance of this class and initialize some properties with default values.
      * @param style Input text style
@@ -170,6 +188,11 @@ export declare class MTextProcessor {
      * Single spacing is {@link LINE_SPACING_SCALE_FACTOR} × text height.
      */
     get defaultLineSpaceFactor(): number;
+    /**
+     * AutoCAD DXF group-73 line spacing style.
+     * Omitted/`0` values resolve to At Least (AutoCAD default).
+     */
+    get defaultLineSpaceStyle(): MTextLineSpacingStyle;
     /**
      * Font name of current character
      */
@@ -195,9 +218,15 @@ export declare class MTextProcessor {
     /**
      * Baseline-to-baseline advance for the current line (AutoCAD MTEXT semantics).
      *
-     * Single spacing is `5/3` of the drawing-space text height; `lineSpaceFactor`
+     * Single spacing is `5/3` of the MTEXT text height; `lineSpaceFactor`
      * (DXF group 44) scales that distance. Font glyph scale factors must not
-     * affect this layout metric — use {@link currentLayoutFontSize}.
+     * affect this layout metric.
+     *
+     * Nominal spacing is `lineSpaceFactor × MTEXT height × 5/3`. Exact style
+     * always uses that distance. At Least (DXF group 73 = 1, or omitted/`0`)
+     * never goes below single spacing of the line's layout height, so a compact
+     * factor such as `0.25` does not stack glyphs. Taller characters on the line
+     * raise the floor further.
      */
     get currentLineHeight(): number;
     /**
@@ -209,8 +238,8 @@ export declare class MTextProcessor {
     /**
      * The current space setting between two characters. The meaning of this value is as follows.
      * - 1: no extra spacing (default tracking)
-     * - 1.2: increases spacing by 20% of the text height
-     * - 0.8: decreases spacing by 20% of the text height
+     * - 1.2: increases spacing by 20% of (text height × width factor / font scale)
+     * - 0.8: decreases spacing by 20% of that same base
      */
     get currentWordSpace(): number;
     /**
@@ -219,6 +248,22 @@ export declare class MTextProcessor {
     get currentWidthFactor(): number;
     /** Horizontal advance for one space, including tracking and width factor. */
     get currentBlankAdvance(): number;
+    /**
+     * Horizontal pen advance for a glyph (or space) width.
+     *
+     * AutoCAD MTEXT tracking (`\T`) adjusts the space *between* characters: 1.0 is
+     * normal. Multiplying the full advance by the tracking factor over-spaces CJK
+     * ideographs (full-em cells) and forces early soft wraps. Instead, apply width
+     * factor to the glyph advance, then add
+     * `(tracking - 1) × textHeight × widthFactor / fontScaleFactor`.
+     *
+     * Dividing by the TrueType capital-A scale keeps tracking tied to the MTEXT
+     * text height rather than the inflated outline size used for glyph advances.
+     *
+     * @param shapeWidth - Unscaled glyph/space advance from the font.
+     * @param obliqueExtraAdvance - Extra advance from oblique shear, if any.
+     */
+    private penAdvance;
     /**
      * All of THREE.js objects in current line. It contains objects in all of sections of this line.
      */
@@ -272,6 +317,8 @@ export declare class MTextProcessor {
      * Apply a font face change to the current render context, including
      * derived bold/italic/oblique settings based on font type.
      * @param fontFace The font face change data from the parser.
+     * @param updateInlineBigFont When false, a comma-less family keeps the big
+     * font already restored by the context stack. Used for `{}` snapshots.
      */
     private applyFontFaceChange;
     /**
@@ -370,14 +417,16 @@ export declare class MTextProcessor {
     /**
      * Appends one glyph's geometry to the active batch buffers and optional char boxes.
      *
-     * Mesh fonts (`ShapeGeometry`) are transformed immediately; line fonts are queued in
+     * Mesh fonts (tagged via {@link isMeshGlyphGeometry}) are queued in
+     * {@link _meshBatchEntries} and merged once via {@link TextGeometryBuilder.mergeMeshGeometries}.
+     * Line fonts are queued in
      * {@link _lineBatchEntries} for later merge via {@link TextGeometryBuilder.mergeLineGeometries}.
      *
      * @param shape Source text shape for the glyph.
      * @param label Character label stored on geometry and char boxes.
      * @param canonical Untransformed glyph geometry from the font.
      * @param matrix World transform to apply to the glyph.
-     * @param geometries Accumulator for mesh (`ShapeGeometry`) primitives.
+     * @param geometries Unused. Mesh glyphs are queued on {@link _meshBatchEntries}.
      * @param meshCharBoxes Accumulator for mesh-glyph picking boxes.
      * @param lineCharBoxes Accumulator for line-glyph picking boxes.
      */
@@ -395,6 +444,10 @@ export declare class MTextProcessor {
      * @returns A {@link THREE.Group} containing merged line/mesh objects and layout metadata.
      */
     processText(tokens: Generator<MTextToken>): THREE.Group<THREE.Object3DEventMap>;
+    /**
+     * True when the current style segment still has mesh glyphs, line glyphs, or decorations to flush.
+     */
+    private hasPendingDrawables;
     /**
      * Flushes pending geometry and char boxes into a styled THREE.js object on `group`.
      *
@@ -409,9 +462,20 @@ export declare class MTextProcessor {
      * @param charBoxType Char-box classification stored on the flushed object.
      */
     private processGeometries;
+    /**
+     * True when every code point is in Basic Latin / Latin-1 (drawing numbers,
+     * hyphens, etc.). CJK and other scripts soft-wrap between characters.
+     */
+    private isLatinAsciiRun;
     /**
      * Lays out and renders one parser word token, breaking to a new visual line when needed.
      *
+     * - CJK / non-Latin: no whole-word wrap — {@link processChar} breaks between
+     *   characters when the next glyph would not fit in the defined width.
+     * - Latin/ASCII: keep Western word wrapping, except a short run that only
+     *   slightly overshoots after CJK (e.g. `秘密-FJP-898E-G`) may stay on the
+     *   current line with a small overhang (AutoCAD).
+     *
      * @param word Character sequence for a single word token.
      * @param geometries Mesh geometry accumulator for the active style segment.
      * @param lineGeometries Line geometry accumulator for the active style segment.
@@ -479,8 +543,10 @@ export declare class MTextProcessor {
     /**
      * Renders one character glyph, including decorations and line-break handling.
      *
-     * Missing glyphs are treated as spaces. When the pen exceeds {@link maxLineWidth},
-     * a visual line break is recorded before placement.
+     * Missing glyphs are treated as spaces. Soft wrap is decided before placement:
+     * if the glyph's advance would not fit in the remaining defined width, break
+     * first (CJK may break between any two characters). The first glyph on an
+     * empty line is always placed even when wider than the box.
      *
      * @param char Character to render.
      * @param geometries Mesh geometry accumulator.
@@ -604,7 +670,7 @@ export declare class MTextProcessor {
     /**
      * Converts pending mesh and line geometries into a styled THREE.js object.
      *
-     * @param geometries Mesh (`ShapeGeometry`) primitives for the current style segment.
+     * @param geometries Mesh glyph primitives for the current style segment.
      * @param lineGeometries Line primitives and decorations for the current style segment.
      * @param meshCharBoxes Mesh char boxes to attach to the created object.
      * @param lineCharBoxes Line char boxes to attach to the created object.

package/lib/renderer/types.d.ts

@@ -71,6 +71,22 @@ export declare enum MTextAttachmentPoint {
     /** Baseline-right point. */
     BaselineRight = 12
 }
+/**
+ * AutoCAD MTEXT line spacing style (DXF group 73).
+ *
+ * - At Least: never below single spacing of the line's layout height; factors
+ *   above 1.0 raise that floor, and taller characters raise it further
+ * - Exact: factor spacing is fixed even if characters overlap
+ *
+ * Omitted or `0` values are treated as {@link MTextLineSpacingStyle.AtLeast}
+ * (AutoCAD's default).
+ */
+export declare enum MTextLineSpacingStyle {
+    /** At least — floor at single spacing of content; taller glyphs raise further. */
+    AtLeast = 1,
+    /** Exact — fixed baseline spacing; tall characters may overlap. */
+    Exact = 2
+}
 /**
  * Logical text token with optional pick box information.
  *
@@ -176,6 +192,11 @@ export interface MTextData {
      * Default is `1.0`.
      */
     lineSpaceFactor?: number;
+    /**
+     * AutoCAD DXF group-73 line spacing style.
+     * `1` = At Least (default when omitted/`0`), `2` = Exact.
+     */
+    lineSpaceStyle?: MTextLineSpacingStyle | number;
     /** The width scaling factor applied to each character. Default is 1.0 */
     widthFactor?: number;
     /** Whether to collect per-character bounding boxes for picking. Default is true */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlightcad/mtext-renderer",
-  "version": "0.12.12",
+  "version": "0.13.0",
   "description": "AutoCAD MText renderer based on Three.js",
   "license": "MIT",
   "author": "MLight Lee <mlight.lee@outlook.com>",
@@ -43,18 +43,19 @@
     "3d-text"
   ],
   "dependencies": {
-    "@mlightcad/mtext-parser": "^1.5.1",
     "@mlightcad/shx-parser": "^1.4.5",
     "iconv-lite": "^0.7.0",
     "idb": "^8.0.3",
     "opentype.js": "^2.0.0"
   },
   "devDependencies": {
+    "@mlightcad/mtext-parser": "^1.5.2",
     "@types/opentype.js": "^1.3.10",
     "@types/three": "^0.172.0",
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
+    "@mlightcad/mtext-parser": "^1.5.2",
     "three": "^0.172.0"
   },
   "scripts": {
@@ -64,6 +65,7 @@
     "clean": "rimraf dist lib tsconfig.tsbuildinfo",
     "lint": "eslint src/",
     "lint:fix": "eslint --fix --quiet src/",
-    "test": "vitest run"
+    "test": "vitest run",
+    "bench": "vitest run --config vitest.bench.config.ts"
   }
 }