@glassly/miniapp 0.3.0-dev.2 → 0.3.0-dev.460

package/src/display/pixelArt.ts

@@ -0,0 +1,141 @@
+/**
+ * Pixel-art icons for scene `image` elements.
+ *
+ * An icon is a list of equal-length rows, one character per pixel: "." is
+ * black (gray 0), "#" is full ink (15), and a hex digit is that gray level.
+ * The rows encode to a grayscale PNG once per icon (base64, memoized by
+ * identity), so every element built from the same rows carries byte-identical
+ * `data` and the glasses cache one texture for all of them.
+ */
+import type {SceneElementInput} from "./scene/types"
+
+export type PixelArt = readonly string[]
+
+const encoded = new WeakMap<PixelArt, string>()
+
+export function pixelArtSize(rows: PixelArt): {w: number; h: number} {
+  return {w: rows[0]?.length ?? 0, h: rows.length}
+}
+
+/** Gray level 0..15 of one pixel character. */
+export function pixelLevel(ch: string): number {
+  if (ch === ".") return 0
+  if (ch === "#") return 15
+  const level = parseInt(ch, 16)
+  if (Number.isNaN(level)) throw new Error(`pixel art: unknown pixel "${ch}"`)
+  return level
+}
+
+/** The icon as a base64 8-bit grayscale PNG. */
+export function pixelArtPng(rows: PixelArt): string {
+  const cached = encoded.get(rows)
+  if (cached !== undefined) return cached
+  const {w, h} = pixelArtSize(rows)
+  if (w === 0 || h === 0) throw new Error("pixel art: empty icon")
+  const raw = new Uint8Array((w + 1) * h)
+  rows.forEach((row, y) => {
+    if (row.length !== w) throw new Error(`pixel art: row ${y} is ${row.length} wide, expected ${w}`)
+    for (let x = 0; x < w; x++) raw[y * (w + 1) + 1 + x] = pixelLevel(row[x]) * 17
+  })
+  const png = encodePng(w, h, raw)
+  const out = base64(png)
+  encoded.set(rows, out)
+  return out
+}
+
+/** An image element drawing `rows` with its top-left at (x, y); `color` is the ink level (absent = full). */
+export function pixelArtElement(id: string, rows: PixelArt, x: number, y: number, color?: number): SceneElementInput {
+  const {w, h} = pixelArtSize(rows)
+  return {
+    type: "image",
+    id,
+    box: {x, y, w, h},
+    data: pixelArtPng(rows),
+    ...(color === undefined ? {} : {style: {color}}),
+  }
+}
+
+// ---- PNG (grayscale, stored deflate) ---------------------------------------
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256)
+  for (let n = 0; n < 256; n++) {
+    let c = n
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    table[n] = c >>> 0
+  }
+  return table
+})()
+
+function crc32(bytes: Uint8Array): number {
+  let c = 0xffffffff
+  for (const b of bytes) c = CRC_TABLE[(c ^ b) & 0xff] ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+
+function adler32(bytes: Uint8Array): number {
+  let a = 1
+  let b = 0
+  for (const byte of bytes) {
+    a = (a + byte) % 65521
+    b = (b + a) % 65521
+  }
+  return ((b << 16) | a) >>> 0
+}
+
+function u32(value: number): number[] {
+  return [(value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff]
+}
+
+function chunk(type: string, body: number[]): number[] {
+  const typed = [...type].map((ch) => ch.charCodeAt(0))
+  const crc = crc32(Uint8Array.from([...typed, ...body]))
+  return [...u32(body.length), ...typed, ...body, ...u32(crc)]
+}
+
+/** zlib stream of stored (uncompressed) blocks, 65535 bytes each at most. */
+function zlibStored(raw: Uint8Array): number[] {
+  const out = [0x78, 0x01]
+  for (let offset = 0; offset < raw.length || offset === 0; offset += 65535) {
+    const block = raw.subarray(offset, Math.min(raw.length, offset + 65535))
+    const last = offset + block.length >= raw.length
+    out.push(last ? 1 : 0, block.length & 0xff, block.length >>> 8, ~block.length & 0xff, (~block.length >>> 8) & 0xff)
+    for (const b of block) out.push(b)
+    if (last) break
+  }
+  out.push(...u32(adler32(raw)))
+  return out
+}
+
+function encodePng(w: number, h: number, raw: Uint8Array): Uint8Array {
+  const header = [...u32(w), ...u32(h), 8, 0, 0, 0, 0] // 8-bit grayscale, deflate, no interlace
+  return Uint8Array.from([
+    0x89,
+    0x50,
+    0x4e,
+    0x47,
+    0x0d,
+    0x0a,
+    0x1a,
+    0x0a,
+    ...chunk("IHDR", header),
+    ...chunk("IDAT", zlibStored(raw)),
+    ...chunk("IEND", []),
+  ])
+}
+
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+
+function base64(bytes: Uint8Array): string {
+  let out = ""
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i]
+    const b = i + 1 < bytes.length ? bytes[i + 1] : 0
+    const c = i + 2 < bytes.length ? bytes[i + 2] : 0
+    const triple = (a << 16) | (b << 8) | c
+    out += B64[(triple >>> 18) & 63] + B64[(triple >>> 12) & 63]
+    out += i + 1 < bytes.length ? B64[(triple >>> 6) & 63] : "="
+    out += i + 2 < bytes.length ? B64[triple & 63] : "="
+  }
+  return out
+}

package/src/display/profiles/g1.ts

@@ -0,0 +1,237 @@
+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,
+  "\u00b7": 1, // Middle dot (notification "sender \u00b7 thread" titles); width assumed to match the period
+
+  // 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/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/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/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 Glassly 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