@mentra/engine 0.1.0-beta.0

package/src/utils/display/profiles/g1.ts

@@ -0,0 +1,236 @@
+import {DisplayProfile} from "./types"
+
+/**
+ * Complete G1 glyph widths from G1FontLoaderKt
+ * These are GLYPH widths - multiply using renderFormula to get rendered pixels.
+ * Rendered width = (glyphWidth + 1) * 2
+ */
+const G1_GLYPH_WIDTHS: Record<string, number> = {
+  // Punctuation & Symbols
+  " ": 2,
+  "!": 1,
+  '"': 2,
+  "#": 6,
+  "$": 5,
+  "%": 6,
+  "&": 7,
+  "'": 1,
+  "(": 2,
+  ")": 2,
+  "*": 3,
+  "+": 4,
+  ",": 1,
+  "-": 4, // Hyphen: 4px glyph → 10px rendered (CRITICAL for breaking!)
+  ".": 1,
+  "/": 3,
+
+  // Numbers
+  "0": 5,
+  "1": 3,
+  "2": 5,
+  "3": 5,
+  "4": 5,
+  "5": 5,
+  "6": 5,
+  "7": 5,
+  "8": 5,
+  "9": 5,
+
+  // More punctuation
+  ":": 1,
+  ";": 1,
+  "<": 4,
+  "=": 4,
+  ">": 4,
+  "?": 5,
+  "@": 7,
+
+  // Uppercase
+  "A": 6,
+  "B": 5,
+  "C": 5,
+  "D": 5,
+  "E": 4,
+  "F": 4,
+  "G": 5,
+  "H": 5,
+  "I": 2,
+  "J": 3,
+  "K": 5,
+  "L": 4,
+  "M": 7,
+  "N": 5,
+  "O": 5,
+  "P": 5,
+  "Q": 5,
+  "R": 5,
+  "S": 5,
+  "T": 5,
+  "U": 5,
+  "V": 6,
+  "W": 7,
+  "X": 6,
+  "Y": 6,
+  "Z": 5,
+
+  // Brackets & special
+  "[": 2,
+  "\\": 3,
+  "]": 2,
+  "^": 4,
+  "_": 3,
+  "`": 2,
+
+  // Lowercase
+  "a": 5,
+  "b": 4,
+  "c": 4,
+  "d": 4,
+  "e": 4,
+  "f": 4,
+  "g": 4,
+  "h": 4,
+  "i": 1,
+  "j": 2,
+  "k": 4,
+  "l": 1,
+  "m": 7,
+  "n": 4,
+  "o": 4,
+  "p": 4,
+  "q": 4,
+  "r": 3,
+  "s": 4,
+  "t": 3,
+  "u": 5,
+  "v": 5,
+  "w": 7,
+  "x": 5,
+  "y": 5,
+  "z": 4,
+
+  // More special
+  "{": 3,
+  "|": 1,
+  "}": 3,
+  "~": 7,
+}
+
+/**
+ * Even Realities G1 Smart Glasses Display Profile
+ *
+ * Verified through empirical testing with actual hardware.
+ * See: line-width-debug-tool/line-width-spec.md
+ */
+export const G1_PROFILE: DisplayProfile = {
+  id: "even-realities-g1",
+  name: "Even Realities G1",
+
+  // Display dimensions
+  displayWidthPx: 576,
+  maxLines: 5,
+
+  // BLE constraints
+  maxPayloadBytes: 390,
+  bleChunkSize: 176,
+
+  // Font metrics
+  fontMetrics: {
+    // Glyph widths from G1FontLoaderKt
+    glyphWidths: new Map(Object.entries(G1_GLYPH_WIDTHS)),
+
+    // Default glyph width for unmapped Latin characters (use max to be safe)
+    defaultGlyphWidth: 7,
+
+    // Rendered width = (glyphWidth + 1) * 2
+    renderFormula: (glyphWidth: number) => (glyphWidth + 1) * 2,
+
+    // Uniform-width scripts - ALL characters in these scripts render at this exact width
+    // These are verified values in RENDERED pixels, NOT averages
+    uniformScripts: {
+      cjk: 18, // ALL Chinese/Japanese Kanji chars = 18px (verified)
+      hiragana: 18, // ALL Hiragana chars = 18px (verified)
+      katakana: 18, // ALL Katakana chars = 18px (verified)
+      korean: 24, // ALL Korean Hangul chars = 24px (verified)
+      cyrillic: 18, // ALL Cyrillic chars = 18px (verified)
+    },
+
+    // Fallback for unmapped Latin characters
+    // Uses MAX width to guarantee no overflow (safe under-utilization)
+    fallback: {
+      latinMaxWidth: 16, // Max Latin = 'm', 'w' at (7+1)*2 = 16px
+      unknownBehavior: "useLatinMax",
+    },
+  },
+
+  constraints: {
+    minCharsBeforeHyphen: 3,
+    // Kinsoku: Characters that should not appear at start of line
+    noStartChars: [".", ",", "!", "?", ":", ";", ")", "]", "}", "。", "，", "！", "？", "：", "；", "）", "】", "」"],
+    // Kinsoku: Characters that should not appear at end of line
+    noEndChars: ["(", "[", "{", "（", "【", "「"],
+  },
+}
+
+/**
+ * G1 Profile for LEGACY mobile clients that have their own wrapping logic.
+ *
+ * Old mobile clients re-wrap text received from the cloud, causing double-wrapping.
+ * This profile uses a reduced display width (~522px instead of 576px) so that
+ * when the mobile client re-wraps, the result still fits within 5 lines.
+ *
+ * Use this profile when:
+ * - Mobile client version < X.X.X (has old wrapping logic)
+ * - You see text getting cut off or exceeding 5 lines
+ *
+ * Once all clients are updated, this can be deprecated.
+ */
+export const G1_PROFILE_LEGACY: DisplayProfile = {
+  id: "even-realities-g1-legacy",
+  name: "Even Realities G1 (Legacy Client Compatibility)",
+
+  // Reduced display width to prevent double-wrapping overflow
+  // Old mobile client wraps at ~90% of true width
+  displayWidthPx: 420,
+  maxLines: 5,
+
+  // BLE constraints (same as standard)
+  maxPayloadBytes: 390,
+  bleChunkSize: 176,
+
+  // Font metrics (same as standard)
+  fontMetrics: {
+    glyphWidths: new Map(Object.entries(G1_GLYPH_WIDTHS)),
+    defaultGlyphWidth: 7,
+    renderFormula: (glyphWidth: number) => (glyphWidth + 1) * 2,
+    uniformScripts: {
+      cjk: 18,
+      hiragana: 18,
+      katakana: 18,
+      korean: 24,
+      cyrillic: 18,
+    },
+    fallback: {
+      latinMaxWidth: 16,
+      unknownBehavior: "useLatinMax",
+    },
+  },
+
+  constraints: {
+    minCharsBeforeHyphen: 3,
+    noStartChars: [".", ",", "!", "?", ":", ";", ")", "]", "}", "。", "，", "！", "？", "：", "；", "）", "】", "」"],
+    noEndChars: ["(", "[", "{", "（", "【", "「"],
+  },
+}
+
+/**
+ * Get the hyphen width for G1 in rendered pixels.
+ * Hyphen glyph = 4px → rendered = (4+1)*2 = 10px
+ */
+export const G1_HYPHEN_WIDTH_PX = 10
+
+/**
+ * Get the space width for G1 in rendered pixels.
+ * Space glyph = 2px → rendered = (2+1)*2 = 6px
+ */
+export const G1_SPACE_WIDTH_PX = 6

package/src/utils/display/profiles/g2.ts

@@ -0,0 +1,39 @@
+import {DisplayProfile} from "./types"
+
+/**
+ * Even Realities G2 Smart Glasses Display Profile
+ *
+ * G2 uses the same display hardware as G1 (green monochrome, ~640x200).
+ * Glyph widths and rendering formula are identical to G1.
+ * The protocol differs (EvenHub protobuf vs G1 binary) but display
+ * characteristics are the same.
+ */
+
+// G2 uses the same glyph widths as G1 (same display hardware/font)
+import {G1_PROFILE} from "./g1"
+
+export const G2_PROFILE: DisplayProfile = {
+  ...G1_PROFILE,
+  id: "even-realities-g2",
+  name: "Even Realities G2",
+  // G2 fits more vertical text than G1 — allow up to 8 lines before the
+  // wrapper truncates (G1 stays at its inherited 5).
+  maxLines: 8,
+  // Hardware-calibrated 2026-07-03: a 28px container overflowed one line of
+  // the firmware font (triggering the fw's overflow indicator tick); 40px is
+  // clean. With this set, the scene pipeline height-clips text so a box is
+  // never handed more lines than fit.
+  lineHeightPx: 40,
+}
+
+/**
+ * Get the hyphen width for G2 in rendered pixels.
+ * Same as G1: Hyphen glyph = 4px → rendered = (4+1)*2 = 10px
+ */
+export const G2_HYPHEN_WIDTH_PX = 10
+
+/**
+ * Get the space width for G2 in rendered pixels.
+ * Same as G1: Space glyph = 2px → rendered = (2+1)*2 = 6px
+ */
+export const G2_SPACE_WIDTH_PX = 6

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

@@ -0,0 +1,28 @@
+/**
+ * Display Profiles
+ *
+ * Hardware-specific configurations for smart glasses displays.
+ * Each profile defines display dimensions, font metrics, and constraints.
+ */
+
+// Types
+export type {
+  DisplayProfile,
+  FontMetrics,
+  UniformScriptWidths,
+  FallbackConfig,
+  DisplayConstraints,
+  ScriptType,
+} from "./types"
+
+// G1 Profiles
+export {G1_PROFILE, G1_PROFILE_LEGACY, G1_HYPHEN_WIDTH_PX, G1_SPACE_WIDTH_PX} from "./g1"
+
+// Z100 Profile
+export {Z100_PROFILE, Z100_HYPHEN_WIDTH_PX, Z100_SPACE_WIDTH_PX} from "./z100"
+
+// G2 Profile
+export {G2_PROFILE, G2_HYPHEN_WIDTH_PX, G2_SPACE_WIDTH_PX} from "./g2"
+
+// Mentra Nex Profile (a.k.a. Mentra Display)
+export {NEX_PROFILE, NEX_HYPHEN_WIDTH_PX, NEX_SPACE_WIDTH_PX} from "./nex"

package/src/utils/display/profiles/nex.ts

@@ -0,0 +1,166 @@
+import { DisplayProfile } from "./types";
+
+/**
+ * Mentra Nex glyph widths
+ */
+const NEX_GLYPH_WIDTHS: Record<string, number> = {
+  // Punctuation & Symbols
+  " ": 5,
+  "!": 5,
+  '"': 8,
+  "#": 14,
+  "$": 12,
+  "%": 18,
+  "&": 14,
+  "'": 5,
+  "(": 7,
+  ")": 7,
+  "*": 8,
+  "+": 12,
+  ",": 5,
+  "-": 8,
+  ".": 5,
+  "/": 7,
+
+  // Numbers
+  "0": 12,
+  "1": 12,
+  "2": 12,
+  "3": 12,
+  "4": 12,
+  "5": 12,
+  "6": 12,
+  "7": 12,
+  "8": 12,
+  "9": 12,
+
+  // More punctuation
+  ":": 6,
+  ";": 6,
+  "<": 12,
+  "=": 12,
+  ">": 12,
+  "?": 9,
+  "@": 18,
+
+  // Uppercase
+  "A": 12,
+  "B": 13,
+  "C": 12,
+  "D": 13,
+  "E": 11,
+  "F": 11,
+  "G": 14,
+  "H": 14,
+  "I": 8,
+  "J": 10,
+  "K": 12,
+  "L": 10,
+  "M": 16,
+  "N": 14,
+  "O": 14,
+  "P": 12,
+  "Q": 14,
+  "R": 13,
+  "S": 11,
+  "T": 11,
+  "U": 13,
+  "V": 12,
+  "W": 18,
+  "X": 12,
+  "Y": 11,
+  "Z": 11,
+
+  // Brackets & special
+  "[": 6,
+  "\\": 7,
+  "]": 6,
+  "^": 12,
+  "_": 11,
+  "`": 12,
+
+  // Lowercase
+  "a": 11,
+  "b": 11,
+  "c": 10,
+  "d": 11,
+  "e": 11,
+  "f": 6,
+  "g": 11,
+  "h": 11,
+  "i": 5,
+  "j": 5,
+  "k": 10,
+  "l": 5,
+  "m": 17,
+  "n": 11,
+  "o": 11,
+  "p": 11,
+  "q": 11,
+  "r": 7,
+  "s": 10,
+  "t": 7,
+  "u": 11,
+  "v": 10,
+  "w": 15,
+  "x": 10,
+  "y": 10,
+  "z": 9,
+
+  // More special
+  "{": 7,
+  "|": 6,
+  "}": 7,
+  "~": 12,
+};
+
+/**
+ * Mentra Nex Smart Glasses Display Profile
+ *
+ * Also known as "Mentra Display" - a new Mentra glasses model with display capabilities.
+ */
+export const NEX_PROFILE: DisplayProfile = {
+  id: "mentra-nex",
+  name: "Mentra Nex",
+
+  // Display dimensions — 500x220 usable region centered in the 640x480 A6N
+  // panel (firmware mos_display_config.c: margins 70/130). Canvas coordinates
+  // are relative to this virtual screen; the physical panel is bigger, 500x220
+  // is the public drawable canvas.
+  displayWidthPx: 480,
+  displayHeightPx: 220,
+  maxLines: 8,
+
+  maxPayloadBytes: 450, // Matches firmware MAX_TEXT_LEN / DisplayText.text cap; delivered via fragmented BLE transport
+  bleChunkSize: 176,
+
+  // Font metrics
+  fontMetrics: {
+    glyphWidths: new Map(Object.entries(NEX_GLYPH_WIDTHS)),
+    defaultGlyphWidth: 16,
+    renderFormula: (glyphWidth: number) => glyphWidth,
+
+    uniformScripts: {
+      cjk: 20,
+      hiragana: 18,
+      katakana: 18,
+      korean: 24,
+      cyrillic: 18,
+    },
+
+    fallback: {
+      latinMaxWidth: 16,
+      unknownBehavior: "useLatinMax",
+    },
+  },
+
+  constraints: {
+    minCharsBeforeHyphen: 3,
+    noStartChars: [".", ",", "!", "?", ":", ";", ")", "]", "}", "。", "，", "！", "？", "：", "；", "）", "】", "」"],
+    noEndChars: ["(", "[", "{", "（", "【", "「"],
+  },
+};
+
+export const NEX_HYPHEN_WIDTH_PX = 8;
+
+export const NEX_SPACE_WIDTH_PX = 4;

package/src/utils/display/profiles/types.ts

@@ -0,0 +1,132 @@
+/**
+ * Display profile for a specific glasses model.
+ * All text measurement and wrapping derives from this configuration.
+ */
+export interface DisplayProfile {
+  /** Unique identifier for this glasses model */
+  id: string
+
+  /** Human-readable name */
+  name: string
+
+  /** Display width in pixels */
+  displayWidthPx: number
+
+  /** Display height in pixels (if applicable) */
+  displayHeightPx?: number
+
+  /** Maximum number of lines that can be displayed */
+  maxLines: number
+
+  /**
+   * CALIBRATED line height in px for box-height→line-count math (scene
+   * pipeline). When absent, host-side height clipping is skipped entirely and
+   * text wraps to the box width with the firmware clipping vertically in-box
+   * (legacy behavior) — it is deliberately NOT derived from canvas math, which
+   * proved wrong on hardware (see profileLineHeightPx in scene/process.ts).
+   */
+  lineHeightPx?: number
+
+  /** Maximum safe payload size in bytes (for BLE transmission) */
+  maxPayloadBytes: number
+
+  /** BLE chunk size for transmission */
+  bleChunkSize: number
+
+  /** Font metrics for text measurement */
+  fontMetrics: FontMetrics
+
+  /** Optional constraints */
+  constraints?: DisplayConstraints
+}
+
+/**
+ * Font metrics for pixel-accurate text measurement.
+ */
+export interface FontMetrics {
+  /**
+   * Map of character to glyph width in pixels.
+   * Keys are single characters.
+   */
+  glyphWidths: Map<string, number>
+
+  /** Default glyph width for unmapped characters */
+  defaultGlyphWidth: number
+
+  /**
+   * Formula to convert glyph width to rendered pixel width.
+   * G1 example: (glyphWidth + 1) * 2
+   */
+  renderFormula: (glyphWidth: number) => number
+
+  /**
+   * Uniform-width scripts - verified to render all characters at same width.
+   * These are NOT averages - they are the actual uniform width in RENDERED pixels.
+   */
+  uniformScripts: UniformScriptWidths
+
+  /**
+   * Fallback configuration for unmapped characters.
+   */
+  fallback: FallbackConfig
+}
+
+/**
+ * Uniform width scripts - these scripts render all characters at the same width.
+ * Values are in RENDERED pixels (after applying renderFormula if applicable).
+ * Verified through hardware testing.
+ */
+export interface UniformScriptWidths {
+  /** Chinese, Japanese Kanji - all chars same width */
+  cjk: number
+  /** Japanese Hiragana - all chars same width */
+  hiragana: number
+  /** Japanese Katakana - all chars same width */
+  katakana: number
+  /** Korean Hangul - all chars same width */
+  korean: number
+  /** Russian, etc. - all chars same width */
+  cyrillic: number
+}
+
+/**
+ * Fallback strategy for unmapped characters.
+ */
+export interface FallbackConfig {
+  /**
+   * Max known Latin width for safe fallback (in rendered pixels).
+   * Using max ensures we never overflow (worst case: slight under-utilization).
+   */
+  latinMaxWidth: number
+
+  /** What to do with completely unknown characters */
+  unknownBehavior: "useLatinMax" | "throw" | "filter"
+}
+
+/**
+ * Optional display constraints.
+ */
+export interface DisplayConstraints {
+  /** Minimum characters before allowing hyphen break */
+  minCharsBeforeHyphen?: number
+
+  /** Characters that should not appear at start of line (kinsoku) */
+  noStartChars?: string[]
+
+  /** Characters that should not appear at end of line (kinsoku) */
+  noEndChars?: string[]
+}
+
+/**
+ * Script type for character classification.
+ */
+export type ScriptType =
+  | "latin"
+  | "cjk"
+  | "hiragana"
+  | "katakana"
+  | "korean"
+  | "cyrillic"
+  | "numbers"
+  | "punctuation"
+  | "unsupported"