@solidtv/renderer 1.1.4 → 1.2.0

package/src/core/shaders/webgl/RoundedWithBorder.ts

@@ -65,10 +65,12 @@ export const RoundedWithBorder: WebGlShaderType<RoundedWithBorderProps> = {
       v_outerSize = vec2(0.0);
 
       if(borderZero == 0.0) {
-        float borderTop = u_borderWidth.x;
-        float borderRight = u_borderWidth.y;
-        float borderBottom = u_borderWidth.z;
-        float borderLeft = u_borderWidth.w;
+        vec4 adjustedBorderWidth = u_borderWidth - 1.0 + clamp(u_borderWidth, -1.0, 1.0);
+
+        float borderTop = adjustedBorderWidth.x;
+        float borderRight = adjustedBorderWidth.y;
+        float borderBottom = adjustedBorderWidth.z;
+        float borderLeft = adjustedBorderWidth.w;
 
         v_outerBorderUv = vec2(0.0);
         v_innerBorderUv = vec2(0.0);

package/src/core/shaders/webgl/RoundedWithBorderAndShadow.ts

@@ -72,10 +72,12 @@ export const RoundedWithBorderAndShadow: WebGlShaderType<RoundedWithBorderAndSha
       v_outerSize = vec2(0.0);
 
       if(borderZero == 0.0) {
-        float borderTop = u_borderWidth.x;
-        float borderRight = u_borderWidth.y;
-        float borderBottom = u_borderWidth.z;
-        float borderLeft = u_borderWidth.w;
+        vec4 adjustedBorderWidth = u_borderWidth - 1.0 + clamp(u_borderWidth, -1.0, 1.0);
+
+        float borderTop = adjustedBorderWidth.x;
+        float borderRight = adjustedBorderWidth.y;
+        float borderBottom = adjustedBorderWidth.z;
+        float borderLeft = adjustedBorderWidth.w;
 
         v_outerBorderUv = vec2(0.0);
         v_innerBorderUv = vec2(0.0);

package/src/core/text-rendering/CanvasTextRenderer.ts

@@ -109,7 +109,10 @@ const renderText = (props: CoreTextNodeProps): TextRenderInfo => {
   const font = `${fontStyle} ${fontSize}px Unknown, ${fontFamily}`;
   // Get font metrics and calculate line height
   measureContext.font = font;
-  measureContext.textBaseline = 'hanging';
+  // The layout engine emits line[4] as the alphabetic baseline Y, matching
+  // CSS line box layout. Both contexts must use 'alphabetic' so fillText draws
+  // the baseline exactly at line[4].
+  measureContext.textBaseline = 'alphabetic';
 
   const metrics = CanvasFontHandler.getFontMetrics(fontFamily, fontSize);
 
@@ -150,7 +153,7 @@ const renderText = (props: CoreTextNodeProps): TextRenderInfo => {
   const a = color & 0xff;
   context.fillStyle = `rgba(${r},${g},${b},${a / 255})`;
   context.font = font;
-  context.textBaseline = 'hanging';
+  context.textBaseline = 'alphabetic';
 
   // Performance optimization for large fonts
   if (fontSize >= 128) {

package/src/core/text-rendering/SdfFontHandler.ts

@@ -229,6 +229,43 @@ const processFontData = (
       unitsPerEm: 1000,
     };
 
+  // Derive cap-height from the atlas when the metrics block doesn't already
+  // supply it. The layout engine uses this value to vertically center
+  // capital letters on each line. BMFont stores per-glyph `yoffset` as the
+  // distance from the line-box top to the glyph's top, and `common.base` as
+  // the distance from the line-box top to the alphabetic baseline — so the
+  // distance from the baseline up to the top of 'H' (atlas design px) is
+  // `common.base - H.yoffset`. Converted into font units it slots into
+  // `FontMetrics.capHeight` alongside the existing ascender / descender
+  // values and flows through `normalizeFontMetrics`.
+  if (metrics.capHeight === undefined) {
+    const capGlyph = glyphMap.get(72); // 'H'
+    if (capGlyph !== undefined) {
+      const capHeightAtlasPx = fontData.common.base - capGlyph.yoffset;
+      metrics = {
+        ...metrics,
+        capHeight: (capHeightAtlasPx / fontData.info.size) * metrics.unitsPerEm,
+      };
+    }
+    // If 'H' isn't in the atlas (icon-only fonts, etc.) we leave capHeight
+    // undefined and rely on the 0.7 × ascender fallback inside
+    // normalizeFontMetrics.
+  }
+
+  // Same derivation for x-height using glyph 'x' (id 120). Only consumed
+  // when `RendererMainSettings.textBaselineMode === 'x'`; otherwise the
+  // 0.5 × ascender fallback inside `normalizeFontMetrics` is sufficient.
+  if (metrics.xHeight === undefined) {
+    const xGlyph = glyphMap.get(120); // 'x'
+    if (xGlyph !== undefined) {
+      const xHeightAtlasPx = fontData.common.base - xGlyph.yoffset;
+      metrics = {
+        ...metrics,
+        xHeight: (xHeightAtlasPx / fontData.info.size) * metrics.unitsPerEm,
+      };
+    }
+  }
+
   // Cache processed data
   fontCache.set(fontFamily, {
     data: fontData,

package/src/core/text-rendering/SdfTextRenderer.ts

@@ -16,6 +16,8 @@ import type { WebGlShaderNode } from '../renderers/webgl/WebGlShaderNode.js';
 import { isProductionEnvironment } from '../../utils.js';
 import type { TextLayout, GlyphLayout } from './TextRenderer.js';
 import { mapTextLayout } from './TextLayoutEngine.js';
+import type { RectWithValid } from '../lib/utils.js';
+import type { Dimensions } from '../../common/CommonTypes.js';
 
 // Type definition to match interface
 const type = 'sdf' as const;
@@ -35,7 +37,7 @@ const font: FontHandler = SdfFontHandler;
 const layoutCache = new Map<string, TextLayout>();
 
 const getLayoutCacheKey = (props: CoreTextNodeProps): string =>
-  `${props.fontFamily}-${props.fontSize}-${props.letterSpacing}-${props.lineHeight}-${props.maxHeight}-${props.maxWidth}-${props.maxLines}-${props.textAlign}-${props.wordBreak}-${props.overflowSuffix}-${props.text}`;
+  `${props.fontFamily}-${props.fontStyle}-${props.fontSize}-${props.letterSpacing}-${props.lineHeight}-${props.maxHeight}-${props.maxWidth}-${props.maxLines}-${props.textAlign}-${props.wordBreak}-${props.overflowSuffix}-${props.text}`;
 
 /**
  * SDF text renderer using MSDF/SDF fonts with WebGL
@@ -144,14 +146,12 @@ const renderQuads = (
         cache.vertices,
         cache.glyphCount,
         ctxTexture,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        renderProps.clippingRect as any,
+        renderProps.clippingRect,
         renderProps.worldAlpha,
         layout.width,
         layout.height,
         renderProps.parentHasRenderTexture,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        renderProps.framebufferDimensions as any,
+        renderProps.framebufferDimensions,
         sdfShader!,
       );
       return null;
@@ -160,7 +160,6 @@ const renderQuads = (
 
   // --- Cache-miss slow path -----------------------------------------------
   const startIdx = webGlRenderer.sdfBufferIdx;
-
   webGlRenderer.addSdfQuads(
     layout.glyphs,
     layout.fontScale,
@@ -169,13 +168,12 @@ const renderQuads = (
     renderProps.worldAlpha,
     layout.distanceRange,
     ctxTexture,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    renderProps.clippingRect as any,
+
+    renderProps.clippingRect,
     layout.width,
     layout.height,
     renderProps.parentHasRenderTexture,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    renderProps.framebufferDimensions as any,
+    renderProps.framebufferDimensions,
     sdfShader!,
   );
 
@@ -221,9 +219,14 @@ const generateTextLayout = (
   const fontData = fontCache.data;
   const commonFontData = fontData.common;
   const designFontSize = fontData.info.size;
-  const designLineHeight = commonFontData.lineHeight;
-  const lineHeight =
-    props.lineHeight || (designLineHeight * fontSize) / designFontSize;
+  // common.base = distance from BMFont line-box top to the alphabetic baseline,
+  // in atlas design units. Used to convert per-glyph yoffset (BMFont top -> glyph top)
+  // into baseline-relative placement.
+  const atlasBase = commonFontData.base;
+  // When the user does not specify lineHeight, fall back to the engine's
+  // 'normal' line height (ascender + lineGap - descender) computed inside
+  // mapTextLayout via the supplied metrics. Passing 0 below triggers that path.
+  const lineHeight = props.lineHeight;
 
   const atlasWidth = commonFontData.scaleW;
   const atlasHeight = commonFontData.scaleH;
@@ -242,9 +245,9 @@ const generateTextLayout = (
   const maxHeight = props.maxHeight;
   const [
     lines,
-    remainingLines,
-    hasRemainingText,
-    bareLineHeight,
+    _remainingLines,
+    _hasRemainingText,
+    _bareLineHeight,
     lineHeightPx,
     effectiveWidth,
     effectiveHeight,
@@ -267,15 +270,16 @@ const generateTextLayout = (
 
   const glyphs: GlyphLayout[] = [];
   let currentX = 0;
-  let currentY = 0;
+  let baselineY = 0;
   for (let i = 0; i < lineAmount; i++) {
     const line = lines[i] as TextLineStruct;
     const textLine = line[0];
     const textLineLength = textLine.length;
     let prevGlyphId = 0;
     currentX = line[3];
-    //convert Y coord to vertex value
-    currentY = line[4] / fontScale;
+    // line[4] is the alphabetic baseline Y in screen px. Convert to atlas
+    // design units (where glyph.yoffset and atlasBase live).
+    baselineY = line[4] / fontScale;
 
     for (let j = 0; j < textLineLength; j++) {
       const codepoint = textLine.codePointAt(j) as number;
@@ -318,10 +322,13 @@ const generateTextLayout = (
       // Apply pair kerning before placing this glyph.
       currentX += kerning;
 
-      // Calculate glyph position and atlas coordinates (in design units)
+      // Glyph position in atlas design units. yoffset is measured from the
+      // BMFont line-box top; subtracting atlasBase re-anchors it relative to
+      // the alphabetic baseline so fonts with different BMFont 'base' values
+      // share the same on-screen baseline.
       const glyphLayout: GlyphLayout = {
         x: currentX + glyph.xoffset,
-        y: currentY + glyph.yoffset,
+        y: baselineY + glyph.yoffset - atlasBase,
         width: glyph.width,
         height: glyph.height,
         atlasX: glyph.x * invAtlasWidth,
@@ -336,7 +343,6 @@ const generateTextLayout = (
       currentX += glyph.xadvance + letterSpacing;
       prevGlyphId = glyph.id;
     }
-    currentY += lineHeightPx;
   }
 
   // Convert final dimensions to pixel space for the layout

package/src/core/text-rendering/TextLayoutEngine.ts

@@ -2,6 +2,7 @@ import type {
   FontMetrics,
   MeasureTextFn,
   NormalizedFontMetrics,
+  TextBaselineMode,
   TextLayoutStruct,
   TextLineStruct,
   WrappedLinesStruct,
@@ -35,18 +36,53 @@ type WrapStrategyFn = (
   overflowWidth: number,
 ) => [string, number, string];
 
+/**
+ * Generic Latin-font ratios used when exact metric values aren't available.
+ * Within a few percent of OS/2 sCapHeight / sxHeight across the common Latin
+ * families (Ubuntu, Noto, Roboto, Arial, etc.).
+ */
+const CAP_HEIGHT_FALLBACK_RATIO = 0.7;
+const X_HEIGHT_FALLBACK_RATIO = 0.5;
+
 export const normalizeFontMetrics = (
   metrics: FontMetrics,
   fontSize: number,
 ): NormalizedFontMetrics => {
   const scale = fontSize / metrics.unitsPerEm;
+  const capHeightUnits =
+    metrics.capHeight !== undefined
+      ? metrics.capHeight
+      : metrics.ascender * CAP_HEIGHT_FALLBACK_RATIO;
+  const xHeightUnits =
+    metrics.xHeight !== undefined
+      ? metrics.xHeight
+      : metrics.ascender * X_HEIGHT_FALLBACK_RATIO;
   return {
     ascender: metrics.ascender * scale,
     descender: metrics.descender * scale,
     lineGap: metrics.lineGap * scale,
+    capHeight: capHeightUnits * scale,
+    xHeight: xHeightUnits * scale,
   };
 };
 
+/**
+ * Engine-wide per-line baseline anchor. Configured once at renderer creation
+ * via {@link RendererMainSettings.textBaselineMode}, not exposed per node so
+ * a single app can't mix anchor models across its text. Defaults to `'cap'`
+ * — see {@link TextBaselineMode} for the rationale.
+ */
+let baselineMode: TextBaselineMode = 'cap';
+
+/**
+ * Sets the engine-wide baseline anchor. Called by `Stage` during construction;
+ * not intended to be called from user code (changing this mid-session would
+ * silently reflow every cached text layout).
+ */
+export const setBaselineMode = (mode: TextBaselineMode): void => {
+  baselineMode = mode;
+};
+
 export const mapTextLayout = (
   measureText: MeasureTextFn,
   metrics: NormalizedFontMetrics,
@@ -61,14 +97,12 @@ export const mapTextLayout = (
   maxWidth: number,
   maxHeight: number,
 ): TextLayoutStruct => {
-  const ascPx = metrics.ascender;
-  const descPx = metrics.descender;
-
-  const bareLineHeight = ascPx - descPx;
+  // Default line height matches CSS 'normal': ascender + lineGap - descender.
+  // metrics.descender is negative for descents below the baseline, so
+  // subtracting it adds the descent depth.
+  const bareLineHeight = metrics.ascender - metrics.descender + metrics.lineGap;
   const lineHeightPx =
     lineHeight <= 3 ? lineHeight * bareLineHeight : lineHeight;
-  const lineHeightDelta = lineHeightPx - bareLineHeight;
-  const halfDelta = lineHeightDelta * 0.5;
 
   let effectiveMaxLines = maxLines;
 
@@ -107,12 +141,27 @@ export const mapTextLayout = (
           effectiveMaxLines,
         );
 
-  let effectiveLineAmount = lines.length;
+  const effectiveLineAmount = lines.length;
   let effectiveMaxWidth = 0;
 
+  // CSS letter-spacing applies between characters, not after the trailing one.
+  // measureText accumulates one advance + letterSpacing per glyph, so each
+  // line carries one extra trailing letterSpacing. Trim it once per line for
+  // alignment / reported width purposes. Wrap decisions inside the loops above
+  // intentionally still use the un-trimmed width (CSS engines also consider
+  // trailing letter-spacing during break decisions; only the rendered line
+  // width is trimmed).
+  if (letterSpacing !== 0) {
+    for (let i = 0; i < effectiveLineAmount; i++) {
+      const line = lines[i]!;
+      if (line[0].length > 0) {
+        line[1] -= letterSpacing;
+      }
+    }
+  }
+
   if (effectiveLineAmount > 0) {
     effectiveMaxWidth = lines[0]![1];
-    //check for longest line
     if (effectiveLineAmount > 1) {
       for (let i = 1; i < effectiveLineAmount; i++) {
         effectiveMaxWidth = Math.max(effectiveMaxWidth, lines[i]![1]);
@@ -134,12 +183,50 @@ export const mapTextLayout = (
 
   const effectiveMaxHeight = effectiveLineAmount * lineHeightPx;
 
-  let firstBaseLine = halfDelta;
-
-  const startY = firstBaseLine;
+  // line[4] stores the alphabetic baseline Y of each line in screen px.
+  //
+  // ── Per-line anchor: cap-height centering ─────────────────────────────
+  //
+  //   baselineY(i) = lineHeight/2 + capHeight/2 + i × lineHeight
+  //
+  // The baseline sits below the line's geometric mid-line by exactly
+  // `capHeight / 2`, so the top of an uppercase letter lands the same
+  // distance *above* the mid-line — i.e. capital letters bracket the
+  // center symmetrically. Cap-height centering matches what designers
+  // expect for UI text (button labels, headings, badges): TXYZ and 1234
+  // sit centered; descenders like 'gjpq' hang slightly below, mirroring
+  // CSS button behavior in browsers.
+  //
+  // Alternative anchors considered (kept here for the record):
+  //
+  //   ── x-height centering ──────────────────────────────────────────────
+  //   baselineY(i) = lineHeight/2 + xHeight/2 + i × lineHeight
+  //   Centers lowercase letters on the mid-line. Matches CSS inline
+  //   `vertical-align: middle`. Reads well for running body text but
+  //   capitals appear high in headings/labels — wrong default for TV UI.
+  //
+  //   ── line-box centering (pre-cap-height behavior) ───────────────────
+  //   const halfLeading = (lineHeightPx − bareLineHeight) / 2
+  //   baselineY(i) = halfLeading + ascender + i × lineHeight
+  //   Centers the abstract asc-to-desc-plus-leading rectangle. The visible
+  //   ink lands noticeably high because asc/(asc−desc) is asymmetric for
+  //   most Latin fonts (~4.2:1 for Ubuntu). Mathematically tidy, visually
+  //   wrong.
+  //
+  // The active anchor is configured at renderer creation via
+  // `RendererMainSettings.textBaselineMode`. Defaults to `'cap'`.
+  let firstBaselineY: number;
+  if (baselineMode === 'x') {
+    firstBaselineY = (lineHeightPx + metrics.xHeight) * 0.5;
+  } else if (baselineMode === 'linebox') {
+    const halfLeading = (lineHeightPx - bareLineHeight) * 0.5;
+    firstBaselineY = halfLeading + metrics.ascender;
+  } else {
+    firstBaselineY = (lineHeightPx + metrics.capHeight) * 0.5;
+  }
   for (let i = 0; i < effectiveLineAmount; i++) {
     const line = lines[i] as TextLineStruct;
-    line[4] = startY + lineHeightPx * i;
+    line[4] = firstBaselineY + lineHeightPx * i;
   }
 
   return [

package/src/core/text-rendering/TextRenderer.ts

@@ -1,4 +1,6 @@
+import type { Dimensions } from '../../common/CommonTypes.js';
 import type { CoreTextNodeProps } from '../CoreTextNode.js';
+import type { RectWithValid } from '../lib/utils.js';
 import type { CoreRenderer } from '../renderers/CoreRenderer.js';
 import type { SdfRenderOp } from '../renderers/webgl/SdfRenderOp.js';
 import type { Stage } from '../Stage.js';
@@ -12,6 +14,24 @@ export type TextBaseline =
   | 'bottom';
 export type TextVerticalAlign = 'top' | 'middle' | 'bottom';
 export type TextRenderers = 'canvas' | 'sdf';
+
+/**
+ * Selects which font-derived height the text layout engine centers on each
+ * line's geometric mid-line. Configured via {@link RendererMainSettings} and
+ * cannot be overridden per node — see the engine-wide reasoning in
+ * `TextLayoutEngine.mapTextLayout`.
+ *
+ * - `'cap'` (default): capital letters centered. Best for UI text — button
+ *   labels, headings, badges. Capitals and digits bracket the center
+ *   symmetrically; descenders hang slightly below, matching CSS button
+ *   behavior in browsers.
+ * - `'x'`: lowercase x-height centered. Better for running body text;
+ *   capitals appear slightly high in headings.
+ * - `'linebox'`: legacy. Centers the abstract asc-to-desc-plus-leading
+ *   rectangle. Mathematically tidy but visually unbalanced because most
+ *   Latin fonts have asymmetric asc/desc ratios.
+ */
+export type TextBaselineMode = 'cap' | 'x' | 'linebox';
 /**
  * Structure mapping font family names to a set of font faces.
  */
@@ -39,24 +59,54 @@ export interface FontMetrics {
    * The number of font units per 1 EM.
    */
   unitsPerEm: number;
+  /**
+   * The distance, in font units, from the baseline to the top of an uppercase
+   * letter (OS/2 sCapHeight).
+   *
+   * Used by the layout engine to vertically center capital letters on each
+   * line's geometric mid-line. When absent, the SDF backend derives this
+   * value from glyph `H` (id 72) in the BMFont atlas; the Canvas backend
+   * falls back to `0.7 × ascender` (a generic Latin-font approximation).
+   */
+  capHeight?: number;
+  /**
+   * The distance, in font units, from the baseline to the top of a lowercase
+   * letter (OS/2 sxHeight). Optional; used only when the baseline-anchor
+   * mode is set to x-height centering (experimental).
+   */
+  xHeight?: number;
 }
 
 /**
- * Normalized font metrics where values are expressed as a fraction of 1 EM.
+ * Normalized font metrics where values are expressed in pixels at the
+ * configured font size (em-px).
  */
 export interface NormalizedFontMetrics {
   /**
-   * The distance, as a fraction of 1 EM, from the baseline to the highest point of the font.
+   * The distance, in em-px, from the baseline to the highest point of the font.
    */
   ascender: number;
   /**
-   * The distance, as a fraction of 1 EM, from the baseline to the lowest point of the font.
+   * The distance, in em-px, from the baseline to the lowest point of the font.
    */
   descender: number;
   /**
-   * The additional space used in the calculation of the default line height as a fraction of 1 EM
+   * The additional space used in the calculation of the default line height, in em-px.
    */
   lineGap: number;
+  /**
+   * The distance, in em-px, from the baseline to the top of an uppercase letter.
+   * Always populated; derived or approximated when {@link FontMetrics.capHeight}
+   * is not provided by the caller.
+   */
+  capHeight: number;
+  /**
+   * The distance, in em-px, from the baseline to the top of a lowercase letter.
+   * Always populated; derived from glyph `x` for SDF, falls back to
+   * `0.5 × ascender` otherwise. Only used by the experimental x-height
+   * baseline-anchor mode.
+   */
+  xHeight: number;
 }
 
 /**
@@ -181,13 +231,15 @@ export interface TrProps extends TrFontProps {
    */
   maxLines: number;
   /**
-   * Vertical Align for text when lineHeight > fontSize
+   * Vertical alignment of the text block within `maxHeight`.
    *
    * @remarks
-   * This property sets the vertical align of the text.
-   * Not yet implemented in the SDF renderer.
+   * Activates when `maxHeight > 0`. Composes with `textBaselineMode`
+   * (per-line anchor). CSS line-box semantics — `'top'` leaves
+   * half-leading above the first line's cap-top; `'bottom'` leaves
+   * half-leading below the last line's descender.
    *
-   * @default middle
+   * @default top
    */
   verticalAlign: TextVerticalAlign;
   /**
@@ -345,11 +397,11 @@ export interface TextRenderProps {
   offsetY: number;
   worldAlpha: number;
   globalTransform: Float32Array;
-  clippingRect: unknown;
+  clippingRect: RectWithValid;
   width: number;
   height: number;
   parentHasRenderTexture: boolean;
-  framebufferDimensions: unknown;
+  framebufferDimensions: Dimensions | null;
   stage: Stage;
   /** Optional SDF vertex cache — passed by CoreTextNode for cache-hit fast path. */
   sdfCache?: SdfVertexCache;

package/src/main-api/Renderer.ts

@@ -6,7 +6,10 @@ import { CoreNode, type CoreNodeProps } from '../core/CoreNode.js';
 import { type CoreTextNodeProps } from '../core/CoreTextNode.js';
 import type { INode, INodeProps, ITextNode, ITextNodeProps } from './INode.js';
 import type { TextureMemoryManagerSettings } from '../core/TextureMemoryManager.js';
-import type { TextRenderer } from '../core/text-rendering/TextRenderer.js';
+import type {
+  TextBaselineMode,
+  TextRenderer,
+} from '../core/text-rendering/TextRenderer.js';
 import type { CanvasRenderer } from '../core/renderers/canvas/CanvasRenderer.js';
 import type { WebGlRenderer } from '../core/renderers/webgl/WebGlRenderer.js';
 import type { Inspector, InspectorOptions } from './Inspector.js';
@@ -363,6 +366,28 @@ export type RendererMainSettings = RendererRuntimeSettings & {
    */
   fontEngines: TextRenderer[];
 
+  /**
+   * Per-line vertical baseline anchor used by the text layout engine.
+   *
+   * @remarks
+   * Picks which font-derived height is centered on each line's geometric
+   * mid-line. This is engine-wide and intentionally not exposed per node —
+   * mixing anchor models within one app produces visually inconsistent text.
+   *
+   * - `'cap'` (default): capital letters and digits sit centered on the line.
+   *   Best fit for UI text (button labels, headings, badges); descenders on
+   *   words like 'gjpq' hang slightly below center, matching CSS button
+   *   behavior in browsers.
+   * - `'x'`: lowercase x-height is centered. Better for running body text;
+   *   capitals appear slightly high in headings.
+   * - `'linebox'`: legacy mode. Centers the asc/lineGap/desc rectangle.
+   *   Mathematically tidy but visually unbalanced because most Latin fonts
+   *   have asymmetric asc/desc ratios.
+   *
+   * @defaultValue `'cap'`
+   */
+  textBaselineMode: TextBaselineMode;
+
   /**
    * Force WebGL2
    *
@@ -516,7 +541,7 @@ export class RendererMain extends EventEmitter {
       boundsMargin: settings.boundsMargin || 0,
       deviceLogicalPixelRatio: settings.deviceLogicalPixelRatio || 1,
       devicePhysicalPixelRatio:
-        settings.devicePhysicalPixelRatio || window.devicePixelRatio || 1,
+        settings.devicePhysicalPixelRatio || this.windowDevicePixelRatio() || 1,
       clearColor: settings.clearColor ?? 0x00000000,
       fpsUpdateInterval: settings.fpsUpdateInterval || 0,
       enableClear: settings.enableClear ?? true,
@@ -530,6 +555,7 @@ export class RendererMain extends EventEmitter {
       renderEngine: settings.renderEngine,
       quadBufferSize: settings.quadBufferSize ?? 4 * 1024 * 1024,
       fontEngines: settings.fontEngines ?? [],
+      textBaselineMode: settings.textBaselineMode ?? 'cap',
       textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 10,
       canvas: settings.canvas,
       createImageBitmapSupport: settings.createImageBitmapSupport || 'full',
@@ -588,6 +614,7 @@ export class RendererMain extends EventEmitter {
       eventBus: this,
       quadBufferSize: settings.quadBufferSize!,
       fontEngines: settings.fontEngines!,
+      textBaselineMode: settings.textBaselineMode!,
       inspector: settings.inspector !== null,
       targetFPS: settings.targetFPS!,
       textureProcessingTimeLimit: settings.textureProcessingTimeLimit!,
@@ -1039,4 +1066,8 @@ export class RendererMain extends EventEmitter {
     this.stage.options.targetFPS = fps > 0 ? fps : 0;
     this.stage.updateTargetFrameTime();
   }
+
+  private windowDevicePixelRatio() {
+    return typeof window !== 'undefined' ? window.devicePixelRatio : undefined;
+  }
 }