@mentra/engine 0.1.0-beta.0

package/src/utils/display/measurer/TextMeasurer.ts

@@ -0,0 +1,346 @@
+import type { DisplayProfile, ScriptType } from "../profiles/types"
+import { detectScript, isUniformWidthScript } from "./script-detection"
+
+/**
+ * Character measurement result with detailed breakdown.
+ */
+export interface CharMeasurement {
+  /** The character measured */
+  char: string
+  /** Width in rendered pixels */
+  widthPx: number
+  /** The script type of the character */
+  script: ScriptType
+  /** Whether width came from glyph map (true) or fallback (false) */
+  fromGlyphMap: boolean
+}
+
+/**
+ * Text measurement result with detailed breakdown.
+ */
+export interface TextMeasurement {
+  /** The text measured */
+  text: string
+  /** Total width in rendered pixels */
+  totalWidthPx: number
+  /** Number of characters */
+  charCount: number
+  /** Per-character measurements (optional, for debugging) */
+  chars?: CharMeasurement[]
+}
+
+/**
+ * Measures text width in pixels based on a DisplayProfile.
+ * All measurements are in actual rendered pixels, not abstract units.
+ *
+ * Key features:
+ * - Pixel-perfect measurement for mapped characters
+ * - Uniform-width handling for CJK, Korean, Cyrillic
+ * - Safe fallback for unmapped Latin characters
+ * - Caching for performance
+ */
+export class TextMeasurer {
+  private readonly profile: DisplayProfile
+  private readonly charCache: Map<string, number> = new Map()
+
+  constructor(profile: DisplayProfile) {
+    this.profile = profile
+    // Pre-populate cache with known glyphs
+    this.buildCharCache()
+  }
+
+  /**
+   * Pre-compute rendered widths for all known glyphs.
+   */
+  private buildCharCache(): void {
+    const { glyphWidths, renderFormula } = this.profile.fontMetrics
+
+    for (const [char, glyphWidth] of glyphWidths.entries()) {
+      const renderedWidth = renderFormula(glyphWidth)
+      this.charCache.set(char, renderedWidth)
+    }
+  }
+
+  /**
+   * Measure the total pixel width of a text string.
+   *
+   * @param text - The text to measure
+   * @returns Width in rendered pixels
+   */
+  measureText(text: string): number {
+    if (!text || text.length === 0) {
+      return 0
+    }
+
+    let totalWidth = 0
+    for (const char of text) {
+      totalWidth += this.measureChar(char)
+    }
+    return totalWidth
+  }
+
+  /**
+   * Measure text with detailed breakdown of each character.
+   *
+   * @param text - The text to measure
+   * @returns Detailed measurement result
+   */
+  measureTextDetailed(text: string): TextMeasurement {
+    if (!text || text.length === 0) {
+      return {
+        text: "",
+        totalWidthPx: 0,
+        charCount: 0,
+        chars: [],
+      }
+    }
+
+    const chars: CharMeasurement[] = []
+    let totalWidth = 0
+
+    for (const char of text) {
+      const script = detectScript(char)
+      const widthPx = this.measureChar(char)
+      const fromGlyphMap = this.profile.fontMetrics.glyphWidths.has(char)
+
+      chars.push({
+        char,
+        widthPx,
+        script,
+        fromGlyphMap,
+      })
+
+      totalWidth += widthPx
+    }
+
+    return {
+      text,
+      totalWidthPx: totalWidth,
+      charCount: chars.length,
+      chars,
+    }
+  }
+
+  /**
+   * Measure a single character's pixel width.
+   *
+   * IMPORTANT: This is PIXEL-PERFECT measurement, not averaging!
+   * - Mapped characters: exact width from glyph map
+   * - Uniform scripts (CJK, Korean, Cyrillic): verified uniform width
+   * - Unmapped Latin: MAX width fallback (safe, never overflow)
+   *
+   * @param char - Single character to measure
+   * @returns Width in rendered pixels
+   */
+  measureChar(char: string): number {
+    if (!char || char.length === 0) {
+      return 0
+    }
+
+    // Check cache first (includes pre-computed glyph map entries)
+    const cached = this.charCache.get(char)
+    if (cached !== undefined) {
+      return cached
+    }
+
+    // Calculate width based on script type
+    const width = this.calculateCharWidth(char)
+
+    // Cache for future lookups
+    this.charCache.set(char, width)
+
+    return width
+  }
+
+  /**
+   * Calculate character width (called when not in cache).
+   */
+  private calculateCharWidth(char: string): number {
+    const { fontMetrics } = this.profile
+    const { uniformScripts, fallback, renderFormula, glyphWidths } = fontMetrics
+
+    // 1. Check explicit glyph map (pixel-perfect for Latin)
+    const glyphWidth = glyphWidths.get(char)
+    if (glyphWidth !== undefined) {
+      return renderFormula(glyphWidth)
+    }
+
+    // 2. Uniform-width scripts (verified monospace - NOT averages!)
+    const script = detectScript(char)
+
+    switch (script) {
+      case "cjk":
+        return uniformScripts.cjk // ALL CJK chars are exactly this width
+      case "hiragana":
+        return uniformScripts.hiragana // ALL Hiragana chars are exactly this width
+      case "katakana":
+        return uniformScripts.katakana // ALL Katakana chars are exactly this width
+      case "korean":
+        return uniformScripts.korean // ALL Korean chars are exactly this width
+      case "cyrillic":
+        return uniformScripts.cyrillic // ALL Cyrillic chars are exactly this width
+    }
+
+    // 3. Unmapped Latin or unknown: use MAX width (safe fallback)
+    // This guarantees we NEVER overflow - worst case is slight under-utilization
+    return fallback.latinMaxWidth
+  }
+
+  /**
+   * Get the raw glyph width (before render formula).
+   * Returns undefined for unmapped characters.
+   *
+   * @param char - Single character
+   * @returns Glyph width in pixels, or undefined if not in glyph map
+   */
+  getGlyphWidth(char: string): number | undefined {
+    return this.profile.fontMetrics.glyphWidths.get(char)
+  }
+
+  /**
+   * Check if text fits within a pixel width.
+   *
+   * @param text - Text to check
+   * @param maxWidthPx - Maximum width in pixels
+   * @returns true if text fits
+   */
+  fitsInWidth(text: string, maxWidthPx: number): boolean {
+    return this.measureText(text) <= maxWidthPx
+  }
+
+  /**
+   * Find how many characters fit within a pixel width.
+   *
+   * @param text - Text to measure
+   * @param maxWidthPx - Maximum width in pixels
+   * @param startIndex - Starting index (default: 0)
+   * @returns Number of characters that fit
+   */
+  charsThatFit(text: string, maxWidthPx: number, startIndex: number = 0): number {
+    if (!text || startIndex >= text.length) {
+      return 0
+    }
+
+    let currentWidth = 0
+    let count = 0
+
+    // Use Array.from to handle surrogate pairs correctly
+    const chars = Array.from(text).slice(startIndex)
+
+    for (const char of chars) {
+      const charWidth = this.measureChar(char)
+
+      if (currentWidth + charWidth > maxWidthPx) {
+        break
+      }
+
+      currentWidth += charWidth
+      count++
+    }
+
+    return count
+  }
+
+  /**
+   * Find the pixel position of a character index in text.
+   *
+   * @param text - Text to measure
+   * @param index - Character index
+   * @returns Pixel offset from start of text
+   */
+  getPixelOffset(text: string, index: number): number {
+    if (!text || index <= 0) {
+      return 0
+    }
+
+    const chars = Array.from(text).slice(0, index)
+    let offset = 0
+
+    for (const char of chars) {
+      offset += this.measureChar(char)
+    }
+
+    return offset
+  }
+
+  /**
+   * Detect the script type of a character.
+   *
+   * @param char - Single character
+   * @returns Script type
+   */
+  detectScript(char: string): ScriptType {
+    return detectScript(char)
+  }
+
+  /**
+   * Check if a character is from a uniform-width script.
+   *
+   * @param char - Single character
+   * @returns true if character is from CJK, Korean, or Cyrillic
+   */
+  isUniformWidth(char: string): boolean {
+    return isUniformWidthScript(char)
+  }
+
+  /**
+   * Get the display profile.
+   */
+  getProfile(): DisplayProfile {
+    return this.profile
+  }
+
+  /**
+   * Get the display width in pixels.
+   */
+  getDisplayWidthPx(): number {
+    return this.profile.displayWidthPx
+  }
+
+  /**
+   * Get the maximum number of lines.
+   */
+  getMaxLines(): number {
+    return this.profile.maxLines
+  }
+
+  /**
+   * Get the maximum payload size in bytes.
+   */
+  getMaxPayloadBytes(): number {
+    return this.profile.maxPayloadBytes
+  }
+
+  /**
+   * Calculate the UTF-8 byte size of text.
+   *
+   * @param text - Text to measure
+   * @returns Byte size
+   */
+  getByteSize(text: string): number {
+    return new TextEncoder().encode(text).length
+  }
+
+  /**
+   * Get the width of a hyphen character in rendered pixels.
+   */
+  getHyphenWidth(): number {
+    return this.measureChar("-")
+  }
+
+  /**
+   * Get the width of a space character in rendered pixels.
+   */
+  getSpaceWidth(): number {
+    return this.measureChar(" ")
+  }
+
+  /**
+   * Clear the character cache.
+   * Useful if profile metrics change at runtime.
+   */
+  clearCache(): void {
+    this.charCache.clear()
+    this.buildCharCache()
+  }
+}

package/src/utils/display/measurer/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Text Measurer Module
+ *
+ * Provides pixel-accurate text measurement based on display profiles.
+ * All measurements are in actual rendered pixels, not abstract units.
+ */
+
+// Main class
+export { TextMeasurer } from "./TextMeasurer"
+export type { CharMeasurement, TextMeasurement } from "./TextMeasurer"
+
+// Script detection utilities
+export {
+  detectScript,
+  isCJKCharacter,
+  isKoreanCharacter,
+  isUniformWidthScript,
+  isUnsupportedScript,
+  needsHyphenForBreak,
+  SCRIPT_RANGES,
+} from "./script-detection"

package/src/utils/display/measurer/script-detection.ts

@@ -0,0 +1,218 @@
+import type {ScriptType} from "../profiles/types"
+
+/**
+ * Unicode ranges for script detection.
+ * Used to classify characters for proper width measurement.
+ */
+export const SCRIPT_RANGES = {
+  // CJK Unified Ideographs
+  cjk: [
+    [0x4e00, 0x9fff], // Main block (common Chinese, Japanese Kanji)
+    [0x3400, 0x4dbf], // Extension A
+    [0x20000, 0x2a6df], // Extension B
+    [0x2a700, 0x2b73f], // Extension C
+    [0x2b740, 0x2b81f], // Extension D
+    [0xf900, 0xfaff], // Compatibility Ideographs
+  ] as const,
+
+  // Japanese Hiragana
+  hiragana: [[0x3040, 0x309f]] as const,
+
+  // Japanese Katakana
+  katakana: [
+    [0x30a0, 0x30ff], // Main block
+    [0x31f0, 0x31ff], // Phonetic Extensions
+  ] as const,
+
+  // Korean
+  korean: [
+    [0xac00, 0xd7af], // Hangul Syllables
+    [0x1100, 0x11ff], // Hangul Jamo
+    [0x3130, 0x318f], // Compatibility Jamo
+    [0xa960, 0xa97f], // Jamo Extended-A
+    [0xd7b0, 0xd7ff], // Jamo Extended-B
+  ] as const,
+
+  // Cyrillic
+  cyrillic: [
+    [0x0400, 0x04ff], // Main block
+    [0x0500, 0x052f], // Supplement
+  ] as const,
+
+  // Numbers (ASCII)
+  numbers: [[0x30, 0x39]] as const,
+
+  // Basic punctuation (ASCII)
+  punctuation: [
+    [0x20, 0x2f], // Space and basic punctuation
+    [0x3a, 0x40], // More punctuation
+    [0x5b, 0x60], // Brackets etc.
+    [0x7b, 0x7e], // Braces etc.
+  ] as const,
+
+  // Unsupported scripts (for filtering)
+  arabic: [[0x0600, 0x06ff]] as const,
+  hebrew: [[0x0590, 0x05ff]] as const,
+  thai: [[0x0e00, 0x0e7f]] as const,
+  emoji: [
+    [0x1f600, 0x1f64f], // Emoticons
+    [0x1f300, 0x1f5ff], // Misc Symbols and Pictographs
+    [0x1f680, 0x1f6ff], // Transport and Map
+    [0x1f1e0, 0x1f1ff], // Flags
+    [0x2600, 0x26ff], // Misc Symbols
+    [0x2700, 0x27bf], // Dingbats
+    [0xfe00, 0xfe0f], // Variation Selectors
+    [0x1f900, 0x1f9ff], // Supplemental Symbols
+  ] as const,
+} as const
+
+/**
+ * Check if a code point is within any of the given ranges.
+ */
+function inRanges(codePoint: number, ranges: readonly (readonly [number, number])[]): boolean {
+  for (const [start, end] of ranges) {
+    if (codePoint >= start && codePoint <= end) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Detect the script type of a single character.
+ *
+ * @param char - Single character to classify
+ * @returns The script type of the character
+ */
+export function detectScript(char: string): ScriptType {
+  if (!char || char.length === 0) {
+    return "latin"
+  }
+
+  // Get the code point (handles surrogate pairs for characters outside BMP)
+  const codePoint = char.codePointAt(0)
+  if (codePoint === undefined) {
+    return "latin"
+  }
+
+  // Check each script in order of likelihood/importance
+
+  // CJK (most common for multi-byte)
+  if (inRanges(codePoint, SCRIPT_RANGES.cjk)) {
+    return "cjk"
+  }
+
+  // Japanese kana
+  if (inRanges(codePoint, SCRIPT_RANGES.hiragana)) {
+    return "hiragana"
+  }
+  if (inRanges(codePoint, SCRIPT_RANGES.katakana)) {
+    return "katakana"
+  }
+
+  // Korean
+  if (inRanges(codePoint, SCRIPT_RANGES.korean)) {
+    return "korean"
+  }
+
+  // Cyrillic
+  if (inRanges(codePoint, SCRIPT_RANGES.cyrillic)) {
+    return "cyrillic"
+  }
+
+  // Numbers
+  if (inRanges(codePoint, SCRIPT_RANGES.numbers)) {
+    return "numbers"
+  }
+
+  // Punctuation
+  if (inRanges(codePoint, SCRIPT_RANGES.punctuation)) {
+    return "punctuation"
+  }
+
+  // Unsupported scripts
+  if (
+    inRanges(codePoint, SCRIPT_RANGES.arabic) ||
+    inRanges(codePoint, SCRIPT_RANGES.hebrew) ||
+    inRanges(codePoint, SCRIPT_RANGES.thai) ||
+    inRanges(codePoint, SCRIPT_RANGES.emoji)
+  ) {
+    return "unsupported"
+  }
+
+  // Default to Latin for ASCII letters and anything else
+  return "latin"
+}
+
+/**
+ * Check if a character is a CJK character (Chinese, Japanese Kanji).
+ * CJK characters can break anywhere without needing a hyphen.
+ */
+export function isCJKCharacter(char: string): boolean {
+  const script = detectScript(char)
+  return script === "cjk" || script === "hiragana" || script === "katakana"
+}
+
+/**
+ * Check if a character is Korean Hangul.
+ */
+export function isKoreanCharacter(char: string): boolean {
+  return detectScript(char) === "korean"
+}
+
+/**
+ * Check if a character is from a uniform-width script.
+ * These scripts render all characters at the same width.
+ */
+export function isUniformWidthScript(char: string): boolean {
+  const script = detectScript(char)
+  return (
+    script === "cjk" || script === "hiragana" || script === "katakana" || script === "korean" || script === "cyrillic"
+  )
+}
+
+/**
+ * Check if a character is from an unsupported script.
+ * These characters may not render correctly on the glasses.
+ */
+export function isUnsupportedScript(char: string): boolean {
+  return detectScript(char) === "unsupported"
+}
+
+/**
+ * Check if breaking between two characters requires a hyphen.
+ * Returns false for:
+ * - Breaking after CJK characters (can break anywhere)
+ * - Breaking before or after spaces
+ * - Breaking after punctuation
+ */
+export function needsHyphenForBreak(charBefore: string, charAfter: string): boolean {
+  // No hyphen needed after CJK (can break anywhere)
+  if (isCJKCharacter(charBefore)) {
+    return false
+  }
+
+  // No hyphen needed before CJK
+  if (isCJKCharacter(charAfter)) {
+    return false
+  }
+
+  // No hyphen needed after space
+  if (charBefore === " " || charBefore === "\t") {
+    return false
+  }
+
+  // No hyphen needed before space (the space is a natural break point)
+  if (charAfter === " " || charAfter === "\t") {
+    return false
+  }
+
+  // No hyphen needed after existing punctuation that serves as break
+  const breakPunctuation = ["-", "–", "—", "/", "\\", "|"]
+  if (breakPunctuation.includes(charBefore)) {
+    return false
+  }
+
+  // Default: hyphen is needed for mid-word Latin breaks
+  return true
+}