@mlightcad/mtext-renderer 0.10.13 → 0.10.15

package/lib/font/shxFont.d.ts

@@ -24,10 +24,39 @@ export declare class ShxFont extends BaseFont {
      * @returns True if this font contains glyph of the specified character code. Otherwise, return false.
      */
     hasCode(code: number): boolean;
+    /**
+     * Horizontal advance for the space character (ASCII 32) at the given size.
+     * Uses the SHX glyph pen advance when defined; otherwise falls back to half the
+     * text height (common for AutoCAD SHX fonts).
+     */
+    getSpaceAdvance(size: number): number;
     generateShapes(text: string, size: number): ShxTextShape[];
     /**
-     * SHX font always has fixed scale factor 1.
-     * @returns Always return value 1
+     * Scale factor that converts AutoCAD's `TEXT.height` (cap-height in the SHX
+     * convention) into the em-box-scaled size expected by `generateShapes`.
+     *
+     * SHX glyphs are defined with `baseUp` units of cap-height (height of an
+     * uppercase letter above the baseline) and `height` units of total em-box
+     * (cap-height + descender + headroom for accents). AutoCAD's DXF group 40
+     * for TEXT/ATTRIB/MTEXT is the cap-height — the historical SHX convention
+     * since the format's introduction in AutoCAD R2 (1985), kept by AutoCAD
+     * when TrueType support was added in the early 1990s so that DWGs portable
+     * across font formats render at consistent visual sizes.
+     *
+     * Returning `1` (the previous behavior) meant SHX glyphs were rendered at
+     * `baseUp / height` of the expected size — typically ~0.75 for western
+     * fonts like `romans.shx`/`complex.shx` where `baseUp=21, height=28`.
+     * Multiplying by `height / baseUp` restores the cap-height interpretation.
+     *
+     * Mirrors the behavior already in place for mesh fonts (see
+     * `meshFontParser.ts` where `scaleFactor = unitsPerEm / glyph('A').yMax`),
+     * isolated to the glyph render path only — `mtextProcessor.currentLayoutFontSize`
+     * divides by this factor to keep layout metrics (line height, attachment
+     * offsets, blank width) on the original cap-height scale.
+     *
+     * @returns `height / baseUp` when both are populated and positive; `1`
+     *   otherwise (e.g. exotic BIGFONT/symbol fonts without standard metrics),
+     *   matching the prior behavior as a safe fallback.
      */
     getScaleFactor(): number;
     /**

package/lib/font/shxTextShape.d.ts

@@ -19,6 +19,16 @@ export declare class ShxTextShape extends BaseTextShape {
      * @param shape - The shape data for this character
      */
     constructor(code: number, fontSize: number, shape: ShxShape, font: ShxFont);
+    /**
+     * Resolves horizontal advance for SHX glyphs.
+     *
+     * - Unicode / shapes fonts: prefer the pen-down end X (lastPoint), which matches
+     *   AutoCAD's advance for single-byte SHX.
+     * - Big fonts (CJK): advance is the scaled font cell width (content.width /
+     *   content.height * fontSize). Glyph bbox or lastPoint can be narrower than the
+     *   cell; using only bbox caused successive Han characters to overlap visually.
+     */
+    private resolveAdvanceWidth;
     protected calcWidth(): number;
     offset(offset: Point): ShxTextShape;
     /**

package/lib/renderer/mtext.d.ts

@@ -109,20 +109,86 @@ export declare class MText extends THREE.Object3D {
      */
     private createMTextGroup;
     /**
-     * Calculates the anchor point for text positioning based on alignment and flow direction.
-     * @param width - The width of the text
-     * @param height - The height of the text
-     * @param attachmentPoint - The attachment point for text alignment
-     * @param flowDirection - The text flow direction
-     * @returns The calculated anchor point coordinates
+     * Measures the logical text frame used by attachment-point anchoring.
+     *
+     * @remarks
+     * Line-layout boxes include inter-line leading that is useful for hit testing, but
+     * that leading must not become extra padding above the first rendered line when
+     * aligning to top/middle/bottom attachment points. This method therefore prefers the
+     * visible geometry height from `geometryBox` when it is non-empty, and only falls
+     * back to `layoutHeight` when there are no measurable glyphs (e.g. empty or
+     * whitespace-only runs).
+     *
+     * @param object - Root group produced by layout; traversed for {@link LineLayout}
+     *   metadata to locate the first line baseline.
+     * @param width - Column width used for horizontal anchoring when finite and
+     *   positive; if not, horizontal extents are taken from `geometryBox`.
+     * @param layoutHeight - Total laid-out height from {@link MTextProcessor} when
+     *   geometry height is unavailable or zero.
+     * @param geometryBox - Axis-aligned bounds of rendered primitives under `object`,
+     *   typically from {@link THREE.Box3.setFromObject}.
+     * @param flowDirection - Optional flow; when {@link MTextFlowDirection.BOTTOM_TO_TOP},
+     *   the vertical frame is anchored from the geometry minimum upward.
+     * @returns Metrics consumed by {@link MText.calculateAnchorPoint}.
+     */
+    private measureAnchorMetrics;
+    /**
+     * Computes the 2D translation that maps the logical frame described by `metrics`
+     * so that the chosen AutoCAD-style attachment point coincides with the insertion
+     * origin (before rotation/insertion-point transforms applied later in
+     * {@link MText.loadMText}).
+     *
+     * @remarks
+     * The returned vector is **added** to vertex positions and char-box metadata via
+     * `geometry.translate` / `CharBox.box.translate` / line `y` offsets. For `undefined`
+     * attachment, behavior matches {@link MTextAttachmentPoint.TopLeft}.
+     *
+     * @param metrics - Pre-anchoring frame from {@link MText.measureAnchorMetrics}.
+     * @param attachmentPoint - DWG attachment constant; determines which corner, edge
+     *   center, or baseline of the frame is pinned to `(0,0)` in anchored space.
+     * @returns Translation `(x, y)` in drawing units applied uniformly to the laid-out
+     *   group and its layout sidecars.
      */
     private calculateAnchorPoint;
     /**
-     * Recursively calculates bounding boxes for an object and its children.
-     * @param object - The Three.js object to process
-     * @param boxes - Array to store the calculated bounding boxes
+     * Walks a laid-out MText subgraph and accumulates world-space character hit boxes and
+     * soft line rectangles for {@link MText.createLayoutData} (raycasting, cursors, debug).
+     *
+     * @remarks
+     * - When `userData.layout.chars` is present, entries are transformed with
+     *   {@link buildCharBoxesFromObject} and appended to `chars`, then recursion stops
+     *   for that branch (char metadata is authoritative).
+     * - When only mesh/line geometry exists, a single synthetic {@link CharBox} wrapping
+     *   the geometry AABB may be emitted.
+     * - `userData.lineLayouts` rows are converted to world-space center `y` and height.
+     *
+     * @param object - Node to traverse (typically the root group from {@link MText.loadMText}).
+     * @param chars - Output collection; receives merged {@link CharBox} entries in world space.
+     * @param lines - Output collection; receives {@link LineLayout} summaries per line break.
      */
     private getLayout;
+    /**
+     * Depth-first union of this MText’s {@link MText.box} from layout metadata and mesh
+     * geometry, while optionally tracking coarse line AABB in `lineBounds`.
+     *
+     * @remarks
+     * Priority order per node:
+     * 1. If `userData.logicalBounds` exists (set in {@link MText.loadMText}), union that
+     *    axis-aligned rectangle transformed by `matrixWorld` — this reflects anchored
+     *    logical extents even when individual glyphs are expensive to union.
+     * 2. Else if `userData.lineLayouts` exists, expand `lineBounds` from the world-space
+     *    top/bottom of each line strip (used as a fallback when no logical bounds were
+     *    written, e.g. legacy paths).
+     * 3. Else if `userData.layout.chars` exists, union each transformed char AABB.
+     * 4. Else for mesh/line primitives, union non-decoration geometry bounds.
+     * 5. Always recurse into children.
+     *
+     * @param object - Current scene graph node.
+     * @param lineBounds - Mutable accumulator: `hasLine`/`min*`/`max*` track the union of
+     *   line-layout strips in world space; `hasLogicalBounds` flips true when any child
+     *   contributed `logicalBounds` so {@link MText.syncDraw} can avoid double-counting
+     *   vertical extent from line strips alone.
+     */
     private updateBoxFromObject;
     /**
      * Remove the specified object from its parent and release geometry and material resource used
@@ -130,5 +196,12 @@ export declare class MText extends THREE.Object3D {
      * @param obj - Input object to dispose
      */
     private disposeThreeObject;
+    /**
+     * Normalizes a font file reference to the lowercase stem used by
+     * {@link FontManager.loadFontsByNames} (strip extension).
+     *
+     * @param fontFileName - Style font path such as `arial.ttf` or extension-less name.
+     * @returns Lowercase name without the last extension segment, or `undefined` if empty.
+     */
     private getFontName;
 }

package/lib/renderer/mtextProcessor.d.ts

@@ -166,6 +166,8 @@ export declare class MTextProcessor {
      * The current scale factor of character width
      */
     get currentWidthFactor(): number;
+    /** Horizontal advance for one space, including tracking and width factor. */
+    get currentBlankAdvance(): number;
     /**
      * All of THREE.js objects in current line. It contains objects in all of sections of this line.
      */
@@ -305,14 +307,11 @@ export declare class MTextProcessor {
      */
     private processAlignment;
     /**
-     * In AutoCAD, the width of a regular space character (ASCII 32, the space key on the keyboard) in MText
-     * depends on the current font and text height, and is not a fixed value.
-     * Specifically:
-     * - Space width ≈ Text height × space width ratio defined by the font
-     * - For common TrueType fonts (like Arial), the space width is typically about 1/4 to 1/3 of the text height.
-     * For example, if the text height is 10 (units), the space width would be approximately 2.5 to 3.3 units.
-     * - For SHX fonts (AutoCAD's built-in vector fonts, such as txt.shx), the space width is often half the text height.
-     * So if the text height is 10, the space width is typically 5 units.
+     * Resolves horizontal advance for an ASCII space in the active font.
+     *
+     * AutoCAD uses each font's own space glyph metrics (SHX pen advance or TrueType
+     * horizontal advance). A fixed fraction of text height (e.g. 50% for SHX) is only
+     * a rough fallback when the font has no space definition.
      */
     private calculateBlankWidthForFont;
     /**

package/package.json

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