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

package/src/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"

package/src/display/profiles/z100.ts

@@ -0,0 +1,198 @@
+import {DisplayProfile} from "./types"
+
+/**
+ * Vuzix Z100 glyph widths - extracted from NotoSans-Regular.ttf at 21px
+ *
+ * These are pixel widths at the default font size used by the Z100 display.
+ * The Z100 uses Noto Sans as its system font.
+ *
+ * Extracted using: node scripts/extract-font-metrics.js NotoSans-Regular.ttf 21
+ */
+const Z100_GLYPH_WIDTHS: Record<string, number> = {
+  // Space and punctuation
+  " ": 5,
+  "!": 6,
+  '"': 9,
+  "#": 14,
+  "$": 12,
+  "%": 17,
+  "&": 15,
+  "'": 5,
+  "(": 6,
+  ")": 6,
+  "*": 12,
+  "+": 12,
+  ",": 6,
+  "-": 7, // Hyphen width - important for line breaking
+  ".": 6,
+  "/": 8,
+
+  // 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,
+  "@": 19,
+
+  // Uppercase
+  "A": 13,
+  "B": 14,
+  "C": 13,
+  "D": 15,
+  "E": 12,
+  "F": 11,
+  "G": 15,
+  "H": 16,
+  "I": 7,
+  "J": 6,
+  "K": 13,
+  "L": 11,
+  "M": 19,
+  "N": 16,
+  "O": 16,
+  "P": 13,
+  "Q": 16,
+  "R": 13,
+  "S": 12,
+  "T": 12,
+  "U": 15,
+  "V": 13,
+  "W": 20,
+  "X": 12,
+  "Y": 12,
+  "Z": 12,
+
+  // Brackets & special
+  "[": 7,
+  "\\": 8,
+  "]": 7,
+  "^": 12,
+  "_": 9,
+  "`": 6,
+
+  // Lowercase
+  "a": 12,
+  "b": 13,
+  "c": 10,
+  "d": 13,
+  "e": 12,
+  "f": 7,
+  "g": 13,
+  "h": 13,
+  "i": 5,
+  "j": 5,
+  "k": 11,
+  "l": 5,
+  "m": 20,
+  "n": 13,
+  "o": 13,
+  "p": 13,
+  "q": 13,
+  "r": 9,
+  "s": 10,
+  "t": 8,
+  "u": 13,
+  "v": 11,
+  "w": 17,
+  "x": 11,
+  "y": 11,
+  "z": 10,
+
+  // More special
+  "{": 8,
+  "|": 12,
+  "}": 8,
+  "~": 12,
+}
+
+/**
+ * Vuzix Z100 Smart Glasses Display Profile
+ *
+ * The Z100 has a green monochrome display with 640x480 resolution.
+ * It uses the Vuzix Ultralite SDK and Noto Sans font family.
+ *
+ * Display specs:
+ * - Resolution: 640x480
+ * - Usable text width: ~390px (empirically tested - SDK applies margins)
+ * - Color: Green monochrome
+ * - Max text lines: 7
+ * - Font: Noto Sans Regular at 21px
+ * - No bitmap support via text commands
+ * - Adjustable brightness
+ *
+ * NOTE: The Vuzix Ultralite SDK handles text rendering internally and applies
+ * its own margins/padding. The usable text width is significantly less than
+ * the physical 640px resolution. Empirical testing shows ~42 characters of
+ * mixed text (387px measured) fits on one line before the SDK wraps.
+ */
+export const Z100_PROFILE: DisplayProfile = {
+  id: "vuzix-z100",
+  name: "Vuzix Z100",
+
+  // Display dimensions
+  // Empirically tested: ~42 chars of mixed text (387px) fits before SDK wraps
+  // Using 390px to account for measurement variance
+  displayWidthPx: 390,
+  maxLines: 7,
+
+  // BLE constraints
+  // Z100 uses Vuzix Ultralite SDK which handles chunking internally
+  // These are conservative values for direct BLE if needed
+  maxPayloadBytes: 512,
+  bleChunkSize: 180,
+
+  // Font metrics - Noto Sans Regular at 21px
+  fontMetrics: {
+    glyphWidths: new Map(Object.entries(Z100_GLYPH_WIDTHS)),
+    defaultGlyphWidth: 12, // Average width from extracted metrics
+    // Z100 uses direct pixel widths, no render formula needed
+    renderFormula: (glyphWidth: number) => glyphWidth,
+
+    // Uniform-width scripts for CJK and other non-Latin
+    // Noto Sans CJK characters are typically wider
+    uniformScripts: {
+      cjk: 21, // Full-width CJK characters
+      hiragana: 21,
+      katakana: 21,
+      korean: 21,
+      cyrillic: 14, // Cyrillic is similar to Latin in Noto Sans
+    },
+
+    fallback: {
+      latinMaxWidth: 20, // 'W' and 'm' are the widest at 20px
+      unknownBehavior: "useLatinMax",
+    },
+  },
+
+  constraints: {
+    minCharsBeforeHyphen: 3,
+    noStartChars: [".", ",", "!", "?", ":", ";", ")", "]", "}", "。", "，", "！", "？", "：", "；", "）", "】", "」"],
+    noEndChars: ["(", "[", "{", "（", "【", "「"],
+  },
+}
+
+/**
+ * Get the hyphen width for Z100 in pixels.
+ * Used for line breaking calculations.
+ */
+export const Z100_HYPHEN_WIDTH_PX = 7
+
+/**
+ * Get the space width for Z100 in pixels.
+ * Used for column alignment calculations.
+ */
+export const Z100_SPACE_WIDTH_PX = 5

package/src/display/scene/types.ts

@@ -0,0 +1,335 @@
+/**
+ * Scene pipeline types — the host half of the miniapp `render()` display API.
+ *
+ * A miniapp describes a full frame ("scene") of positioned elements; the host
+ * clamps/budgets/wraps it, diffs it against the last frame sent to the device,
+ * and ships ONE annotated SceneFrame over the bridge. SGCs either walk the
+ * per-element annotations (G2, Mentra Display) or serialize the whole frame
+ * (full-frame devices). Spec: notes/miniapp-display-render-implementation-spec.md
+ */
+
+export interface SceneBox {
+  x: number
+  y: number
+  w: number
+  h: number
+}
+
+/** Canvas corner a box's x/y are measured from (insets grow inward). */
+export type SceneAnchor = "top-left" | "top-right" | "bottom-left" | "bottom-right"
+
+/**
+ * A box as it arrives from the miniapp SDK: optionally corner-anchored.
+ * `resolveAnchors` turns these into plain top-left SceneBoxes against the
+ * device's real canvas before any processing/degrading — anchors never reach
+ * FrameElement, the differ, or the wire.
+ */
+export interface SceneBoxInput extends SceneBox {
+  anchor?: SceneAnchor
+}
+
+export type SceneBreakMode = "character" | "character-no-hyphen" | "word" | "strict-word"
+
+export interface SceneTextStyle {
+  /** Border width in px (0/absent = none). */
+  border?: number
+  /** Border corner radius in px. */
+  radius?: number
+  /** What happens to text that doesn't fit the box after wrapping. Default "clip". */
+  overflow?: "clip" | "ellipsis"
+  /** Line-break policy for wrapping. */
+  breakMode?: SceneBreakMode
+  /**
+   * "mono": fixed-pitch at `fontSize` px, lines taken as given (no host wrap).
+   * "builtin": drawn by the glasses' own 20 px font engine (Glassly CFW G2);
+   * lines taken as given, other devices fall back to the default face.
+   */
+  font?: "default" | "mono" | "builtin"
+  fontSize?: number
+  /** Gray level 0..15 for device-drawn text. */
+  color?: number
+}
+
+export interface SceneRectStyle {
+  border?: number
+  radius?: number
+  /** Solid fill instead of an outline. */
+  fill?: boolean
+  /** Gray level 0..15 (15 = brightest). Default 15. */
+  color?: number
+}
+
+/** Closed shapes (circle, triangle, quad): outline of `border` px, or filled. */
+export interface SceneShapeStyle {
+  border?: number
+  fill?: boolean
+  color?: number
+}
+
+/** Images: gray level 0..15 the pixels scale to (15 = as drawn); tweens on devices that fade textures. */
+export interface SceneImageStyle {
+  color?: number
+}
+
+/** Open strokes (line, bezier, arc). */
+export interface SceneStrokeStyle {
+  width?: number
+  color?: number
+}
+
+export interface ScenePoint {
+  x: number
+  y: number
+}
+
+export type SceneEasing = "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out"
+
+/** Animate geometry changes of an element with a stable id (devices with `animation`). */
+export interface SceneTransition {
+  durationMs: number
+  easing?: SceneEasing
+}
+
+export type SceneShape = "rect" | "circle" | "arc" | "pie" | "line" | "triangle" | "quad" | "bezier" | "svg"
+
+/** A scene element as it arrives from the miniapp SDK (pre-processing). */
+export type SceneElementInput = (
+  | {type: "text"; id?: string; box: SceneBoxInput; text: string; style?: SceneTextStyle; transition?: SceneTransition}
+  | {
+      type: "image"
+      id?: string
+      box: SceneBoxInput
+      data: string
+      style?: SceneImageStyle
+      transition?: SceneTransition
+    }
+  | {type: "rect"; id?: string; box: SceneBoxInput; style?: SceneRectStyle; transition?: SceneTransition}
+  | {type: "circle"; id?: string; box: SceneBoxInput; style?: SceneShapeStyle; transition?: SceneTransition}
+  | {
+      type: "arc"
+      id?: string
+      box: SceneBoxInput
+      startDeg: number
+      endDeg: number
+      style?: SceneStrokeStyle
+      transition?: SceneTransition
+    }
+  | {
+      type: "pie"
+      id?: string
+      box: SceneBoxInput
+      startDeg: number
+      endDeg: number
+      style?: {color?: number}
+      transition?: SceneTransition
+    }
+  | {
+      type: "line"
+      id?: string
+      points: ScenePoint[]
+      box?: SceneBoxInput
+      style?: SceneStrokeStyle
+      transition?: SceneTransition
+    }
+  | {
+      type: "triangle"
+      id?: string
+      points: ScenePoint[]
+      box?: SceneBoxInput
+      style?: SceneShapeStyle
+      transition?: SceneTransition
+    }
+  | {
+      type: "quad"
+      id?: string
+      points: ScenePoint[]
+      box?: SceneBoxInput
+      style?: SceneShapeStyle
+      transition?: SceneTransition
+    }
+  | {
+      type: "bezier"
+      id?: string
+      points: ScenePoint[]
+      box?: SceneBoxInput
+      style?: SceneStrokeStyle
+      transition?: SceneTransition
+    }
+  | {
+      type: "svg"
+      id?: string
+      box: SceneBoxInput
+      d: string
+      scale?: number
+      fillRule?: "nonzero" | "evenodd"
+      style?: {color?: number}
+      transition?: SceneTransition
+    }
+) & {
+  /** Clockwise degrees, unwrapped (0 to 360 makes a full turn). Geometric shapes and SVG only. */
+  rotation?: number
+  /** Fixed pivot in canvas pixels; defaults to the target box center. */
+  pivot?: ScenePoint
+  /** Stereo depth in canvas pixels (±MAX_SCENE_DEPTH): positive is nearer the viewer. */
+  depth?: number
+}
+
+export type SceneElementType = SceneElementInput["type"]
+
+/** Largest per-lens disparity an element may ask for, in canvas pixels. */
+export const MAX_SCENE_DEPTH = 16
+
+export type SceneElementStyle =
+  | SceneTextStyle
+  | SceneRectStyle
+  | SceneShapeStyle
+  | SceneStrokeStyle
+  | SceneImageStyle
+  | {color?: number}
+
+/** Elements positioned by a point list; the host derives `box` (their bounding box) before processing. */
+export const POINT_SHAPE_TYPES: readonly SceneElementType[] = ["line", "triangle", "quad", "bezier"]
+
+/** Point counts each point shape accepts. */
+export const POINT_SHAPE_ARITY: Record<string, readonly number[]> = {
+  line: [2],
+  triangle: [3],
+  quad: [4],
+  bezier: [3, 4],
+}
+
+export type SceneChange = "created" | "updated" | "moved" | "unchanged"
+
+/**
+ * A processed element inside a SceneFrame: id definitely assigned, box clamped,
+ * text pre-wrapped (newlines inserted), annotated with what changed vs the last
+ * frame sent to this device.
+ */
+export interface FrameElement {
+  /** SVG path and its checked firmware command stream (Q4 coordinates). */
+  d?: string
+  path?: number[]
+  pathScale?: number
+  fillRule?: "nonzero" | "evenodd"
+  rotation?: number
+  pivot?: ScenePoint
+  /** Stereo disparity in px (left lens +depth, right lens -depth); absent = the frame's plane. */
+  depth?: number
+
+  id: string
+  type: SceneElementType
+  box: SceneBox
+  text?: string
+  /** Image pixels, base64 (PNG documented; SGCs decode → re-encode to wire format and scale to box). */
+  data?: string
+  style?: SceneElementStyle
+  /** Point shapes: the points, in canvas pixels; `box` is their bounding box. */
+  points?: ScenePoint[]
+  startDeg?: number
+  endDeg?: number
+  transition?: SceneTransition
+  change: SceneChange
+  /** Hash of the element's content (text/data + style) — lets SGCs skip BLE re-upload without retaining pixels. */
+  contentHash: string
+}
+
+/** The unit that crosses the JS→native bridge: one whole frame per render(). */
+export interface SceneFrame {
+  appId: string
+  view: "main" | "dashboard"
+  /** Bumps on replay / app switch / reconnect; a bumped epoch bypasses native dedup. */
+  sceneEpoch: number
+  /**
+   * Host-wide monotonic frame number. Native reports it back in
+   * `scene_frame_presented` once the device has the frame; a report for N
+   * also covers every earlier frame (the native pacer folds unsent frames
+   * into the next one, so their content is on the glasses by then).
+   */
+  seq: number
+  /** True when the device is expected to rebuild from scratch (all elements arrive "created"). */
+  replay?: boolean
+  elements: FrameElement[]
+  /** Element ids present in the previous frame but absent now — host-computed; apps never send removes. */
+  removed: string[]
+  /** Canvas the boxes were clamped against — lets a full-frame SGC place a legacy-sized frame correctly. */
+  canvas?: {width: number; height: number}
+}
+
+/**
+ * Typed display capabilities block (host-side mirror of the SDK's
+ * DisplayCapabilities). All limits are DATA — the pipeline acts on them
+ * generically; no device names appear in pipeline code.
+ */
+export interface SceneDisplayCapabilities {
+  /** Public drawable canvas in px (the device's safe area, not the physical panel). */
+  width: number
+  height: number
+  /** False ⇒ scenes degrade to legacy text layouts host-side; only sugar-shaped content renders. */
+  canPosition: boolean
+  /** Text-element budget. Rects share this pool on container-based devices. */
+  maxTextElements: number
+  maxImageElements: number
+  /** Max per-image dimensions the device accepts (box-level check), if limited. */
+  maxImagePx?: {width: number; height: number}
+  shapes: SceneShape[]
+  /** True ⇒ element transitions animate on the device. */
+  animation: boolean
+  rotation?: boolean
+  /** True ⇒ per-element `depth` is drawn as a lens disparity (otherwise stripped). */
+  depth?: boolean
+  intensityLevels: number
+  partialUpdate: boolean
+}
+
+/** Result of processing a scene — feeds the awaitable render() result. */
+export interface SceneProcessResult {
+  frame: SceneFrame
+  degraded: boolean
+  /** Ids (or synthesized ids) of elements dropped by budget/bounds/image limits. */
+  dropped: string[]
+}
+
+/** Cheap stable string hash (FNV-1a, 32-bit) — content identity for diff + native dedup. */
+export function contentHash(...parts: (string | number | undefined)[]): string {
+  let h = 0x811c9dc5
+  for (const part of parts) {
+    const s = part === undefined ? "" : String(part)
+    for (let i = 0; i < s.length; i++) {
+      h ^= s.charCodeAt(i)
+      h = Math.imul(h, 0x01000193)
+    }
+    h ^= 0x1f
+    h = Math.imul(h, 0x01000193)
+  }
+  return (h >>> 0).toString(36)
+}
+
+export function boxesEqual(a: SceneBox, b: SceneBox): boolean {
+  return a.x === b.x && a.y === b.y && a.w === b.w && a.h === b.h
+}
+
+/**
+ * Content identity of an element (text/data/points/angles + style + depth),
+ * excluding its box. A nonzero depth joins the hash so a depth change is a
+ * change (the box alone does not move); zero/absent leaves the hash as before.
+ */
+export function elementContentHash(el: {
+  type: SceneElementType
+  text?: string
+  data?: string
+  style?: SceneElementStyle
+  points?: ScenePoint[]
+  startDeg?: number
+  endDeg?: number
+  depth?: number
+}): string {
+  const style = el.style ?? {}
+  const styleKey = Object.keys(style)
+    .sort()
+    .map((k) => `${k}=${(style as Record<string, unknown>)[k]}`)
+    .join(",")
+  const pointsKey = el.points?.map((p) => `${p.x},${p.y}`).join(";")
+  const angleKey = el.startDeg !== undefined || el.endDeg !== undefined ? `${el.startDeg}-${el.endDeg}` : undefined
+  const depthKey = el.depth ? [`depth=${el.depth}`] : []
+  return contentHash(el.type, el.text, el.data, styleKey, pointsKey, angleKey, ...depthKey)
+}