@glassly/engine 0.1.0-dev.99 → 0.2.8-dev.445

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

@@ -1,198 +1,2 @@
-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
+// Moved into the SDK (@glassly/miniapp/display) so miniapps lay text out the way the host measures it; this path re-exports it for the engine.
+export {Z100_PROFILE, Z100_HYPHEN_WIDTH_PX, Z100_SPACE_WIDTH_PX} from "@glassly/miniapp/display"

package/src/utils/display/scene/degrade.ts

@@ -37,6 +37,9 @@ export function degradeScene(input: readonly SceneElementInput[]): DegradedScene
 
   const texts: TextEl[] = []
   input.forEach((el, index) => {
+    if (el && typeof el === "object" && Array.isArray((el as {points?: unknown}).points)) {
+      return // vector shapes: decoration on a text wall
+    }
     if (!el || typeof el !== "object" || !el.box) {
       // Malformed element — report it like the positioning pipeline does
       // instead of silently pretending the render was clean.
@@ -50,7 +53,7 @@ export function degradeScene(input: readonly SceneElementInput[]): DegradedScene
       dropped.push(el.id ?? `image[${index}]`)
       degraded = true
     }
-    // rects: silent drop — pure decoration on a text wall.
+    // rects and other shapes: silent drop — pure decoration on a text wall.
   })
 
   if (texts.length === 0) {

package/src/utils/display/scene/differ.ts

@@ -15,17 +15,30 @@
  * prefixed "~" so they can never collide with app-supplied ids.
  */
 
-import type {FrameElement, SceneBox, SceneChange, SceneElementType} from "./types"
+import type {FrameElement, SceneBox, SceneChange, SceneElementType, ScenePoint, SceneTransition} from "./types"
 import {boxesEqual} from "./types"
 
 /** A processed (clamped/wrapped) element, pre-diff: id optional, no annotation yet. */
 export interface DiffableElement {
+  /** SVG path and its checked firmware command stream (Q4 coordinates). */
+  d?: string
+  path?: number[]
+  pathScale?: number
+  fillRule?: "nonzero" | "evenodd"
+  rotation?: number
+  pivot?: ScenePoint
+  depth?: number
+
   id?: string
   type: SceneElementType
   box: SceneBox
   text?: string
   data?: string
   style?: FrameElement["style"]
+  points?: ScenePoint[]
+  startDeg?: number
+  endDeg?: number
+  transition?: SceneTransition
   contentHash: string
 }
 
@@ -54,6 +67,17 @@ function buildFrameElement(el: DiffableElement, id: string, change: SceneChange)
   if (el.text !== undefined) out.text = el.text
   if (el.data !== undefined) out.data = el.data
   if (el.style !== undefined) out.style = el.style
+  if (el.points !== undefined) out.points = el.points
+  if (el.startDeg !== undefined) out.startDeg = el.startDeg
+  if (el.endDeg !== undefined) out.endDeg = el.endDeg
+  if (el.transition !== undefined) out.transition = el.transition
+  if (el.d !== undefined) out.d = el.d
+  if (el.path !== undefined) out.path = el.path
+  if (el.pathScale !== undefined) out.pathScale = el.pathScale
+  if (el.fillRule !== undefined) out.fillRule = el.fillRule
+  if (el.rotation !== undefined) out.rotation = el.rotation
+  if (el.pivot !== undefined) out.pivot = el.pivot
+  if (el.depth !== undefined) out.depth = el.depth
   return out
 }
 

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

@@ -9,9 +9,14 @@ export type {
   SceneElementInput,
   SceneElementType,
   SceneFrame,
+  SceneImageStyle,
+  ScenePoint,
   SceneProcessResult,
   SceneRectStyle,
+  SceneShapeStyle,
+  SceneStrokeStyle,
   SceneTextStyle,
+  SceneTransition,
 } from "./types"
 export {boxesEqual, contentHash, elementContentHash} from "./types"
 export {resolveAnchors} from "./anchor"

package/src/utils/display/scene/process.ts

@@ -8,12 +8,21 @@
  * design doc's image "reject" to per-element drop).
  */
 
+import {compileSvgPath} from "./svgPath"
 import {TextMeasurer} from "../measurer/TextMeasurer"
 import {TextWrapper} from "../wrapper/TextWrapper"
 import type {DisplayProfile} from "../profiles/types"
 import type {DiffableElement} from "./differ"
-import type {SceneBox, SceneDisplayCapabilities, SceneElementInput, SceneTextStyle} from "./types"
-import {elementContentHash} from "./types"
+import type {
+  SceneBox,
+  SceneBoxInput,
+  SceneDisplayCapabilities,
+  SceneElementInput,
+  ScenePoint,
+  SceneTextStyle,
+  SceneTransition,
+} from "./types"
+import {MAX_SCENE_DEPTH, POINT_SHAPE_ARITY, POINT_SHAPE_TYPES, elementContentHash} from "./types"
 
 export interface ProcessedScene {
   elements: DiffableElement[]
@@ -35,6 +44,35 @@ function clampBox(box: SceneBox, width: number, height: number): SceneBox | null
   return {x: x1, y: y1, w: x2 - x1, h: y2 - y1}
 }
 
+const isFinite = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n)
+
+/** Integer points, or null when the count/values are invalid for the type. */
+function validPoints(el: SceneElementInput): ScenePoint[] | null {
+  const raw = (el as {points?: unknown}).points
+  if (!Array.isArray(raw) || !(POINT_SHAPE_ARITY[el.type] ?? []).includes(raw.length)) return null
+  const points: ScenePoint[] = []
+  for (const p of raw) {
+    if (!p || typeof p !== "object" || !isFinite((p as ScenePoint).x) || !isFinite((p as ScenePoint).y)) return null
+    points.push({x: Math.floor((p as ScenePoint).x), y: Math.floor((p as ScenePoint).y)})
+  }
+  return points
+}
+
+function pointsBox(points: ScenePoint[]): SceneBox {
+  const xs = points.map((p) => p.x)
+  const ys = points.map((p) => p.y)
+  const x = Math.min(...xs)
+  const y = Math.min(...ys)
+  return {x, y, w: Math.max(...xs) - x + 1, h: Math.max(...ys) - y + 1}
+}
+
+function validTransition(t: unknown): SceneTransition | undefined {
+  if (!t || typeof t !== "object") return undefined
+  const {durationMs, easing} = t as SceneTransition
+  if (!isFinite(durationMs) || durationMs <= 0) return undefined
+  return easing ? {durationMs, easing} : {durationMs}
+}
+
 function boxShrunk(orig: SceneBox, clamped: SceneBox): boolean {
   return (
     clamped.x !== Math.floor(orig.x) ||
@@ -77,17 +115,38 @@ export function processScene(
 
   // Validate + dedupe explicit ids (first occurrence wins; dupes are dev error).
   const seenIds = new Set<string>()
-  const valid: {el: SceneElementInput; index: number}[] = []
+  const valid: {el: SceneElementInput; index: number; box: SceneBoxInput; points?: ScenePoint[]}[] = []
   input.forEach((raw, index) => {
-    if (!raw || typeof raw !== "object" || !raw.box) {
+    if (!raw || typeof raw !== "object") {
       dropped.push(reportId(raw ?? ({type: "text"} as SceneElementInput), index))
       degraded = true
       return
     }
+    let points: ScenePoint[] | undefined
+    if (POINT_SHAPE_TYPES.includes(raw.type)) {
+      const valid = validPoints(raw)
+      if (!valid) {
+        dropped.push(reportId(raw, index))
+        degraded = true
+        return
+      }
+      points = valid
+      raw = {...raw, box: pointsBox(valid)} as SceneElementInput
+    }
+    if (!raw.box) {
+      dropped.push(reportId(raw, index))
+      degraded = true
+      return
+    }
     // Non-finite box numbers (NaN/±Infinity/non-number) would survive the
     // Math.* clamp below and poison the frame all the way to native ints.
     const b = raw.box
-    if (![b.x, b.y, b.w, b.h].every((n) => typeof n === "number" && Number.isFinite(n))) {
+    if (![b.x, b.y, b.w, b.h].every(isFinite)) {
+      dropped.push(reportId(raw, index))
+      degraded = true
+      return
+    }
+    if ((raw.type === "arc" || raw.type === "pie") && !(isFinite(raw.startDeg) && isFinite(raw.endDeg))) {
       dropped.push(reportId(raw, index))
       degraded = true
       return
@@ -105,24 +164,138 @@ export function processScene(
       }
       seenIds.add(key)
     }
-    valid.push({el, index})
+    valid.push({el, index, box: el.box as SceneBoxInput, points})
   })
 
   // Clamp + per-type limits, then budget in array order.
   let textBudget = caps.maxTextElements
   let imageBudget = caps.maxImageElements
   const out: DiffableElement[] = []
+  let pathEdges = 0
 
-  for (const {el, index} of valid) {
-    const clamped = clampBox(el.box, caps.width, caps.height)
+  for (const {el, index, box, points} of valid) {
+    const transition = validTransition((el as {transition?: unknown}).transition)
+    const transform: {rotation?: number; pivot?: ScenePoint} = {}
+    if (el.rotation !== undefined || el.pivot !== undefined) {
+      const angle = el.rotation ?? 0
+      const pivot = el.pivot ?? {x: box.x + box.w / 2, y: box.y + box.h / 2}
+      if (
+        !isFinite(angle) ||
+        Math.abs(angle) > 36000 ||
+        !isFinite(pivot.x) ||
+        !isFinite(pivot.y) ||
+        Math.abs(pivot.x) > 32767 ||
+        Math.abs(pivot.y) > 32767 ||
+        !caps.rotation ||
+        el.type === "image" ||
+        el.type === "text"
+      ) {
+        dropped.push(reportId(el, index))
+        degraded = true
+        continue
+      }
+      transform.rotation = Math.round(angle * 256) / 256
+      transform.pivot = {x: Math.round(pivot.x), y: Math.round(pivot.y)}
+      if (transition) transition.durationMs = Math.min(65535, transition.durationMs)
+    }
+    const transformHash =
+      transform.rotation === undefined ? undefined : `${transform.rotation}:${transform.pivot?.x}:${transform.pivot?.y}`
+    // Depth is a lens disparity, not content: devices without it draw the
+    // element flat instead of dropping it. A non-number is still a dev error.
+    let depth: number | undefined
+    if (el.depth !== undefined) {
+      if (!isFinite(el.depth)) {
+        dropped.push(reportId(el, index))
+        degraded = true
+        continue
+      }
+      const d = Math.max(-MAX_SCENE_DEPTH, Math.min(MAX_SCENE_DEPTH, Math.round(el.depth)))
+      if (caps.depth && d !== 0) depth = d
+    }
+    const plane = depth === undefined ? {} : {depth}
+    const clamped = clampBox(box, caps.width, caps.height)
     if (!clamped) {
       dropped.push(reportId(el, index))
       degraded = true
       continue
     }
-    const shrunk = boxShrunk(el.box, clamped)
+    const shrunk = boxShrunk(box, clamped)
     if (shrunk) degraded = true
 
+    if (el.type === "svg") {
+      try {
+        if (!caps.shapes.includes("svg") || textBudget <= 0 || shrunk)
+          throw new Error("SVG unavailable or out of bounds")
+        const scale = el.scale ?? 1
+        if (
+          !isFinite(scale) ||
+          scale < 0 ||
+          scale > 8 ||
+          (el.fillRule !== undefined && el.fillRule !== "evenodd" && el.fillRule !== "nonzero")
+        )
+          throw new Error("Invalid SVG scale or fill rule")
+        const compiled = compileSvgPath(el.d)
+        if (pathEdges + compiled.edges > 4096) throw new Error("SVG scene exceeds the edge budget")
+        pathEdges += compiled.edges
+        textBudget--
+        out.push({
+          id: el.id,
+          type: "svg",
+          box: clamped,
+          d: el.d,
+          path: compiled.commands,
+          pathScale: Math.round(scale * 256),
+          fillRule: el.fillRule ?? "nonzero",
+          style: el.style,
+          ...transform,
+          ...plane,
+          ...(transition ? {transition} : {}),
+          contentHash: elementContentHash({
+            type: "svg",
+            data: `${el.d}:${scale}:${el.fillRule}:${transformHash}`,
+            style: el.style,
+            depth,
+          }),
+        })
+      } catch {
+        dropped.push(reportId(el, index))
+        degraded = true
+      }
+      continue
+    }
+
+    if (el.type !== "text" && el.type !== "image" && el.type !== "rect") {
+      // Vector shapes: only devices that draw them get them; the device clips
+      // point shapes itself, so an off-canvas point is not a drop.
+      if (!caps.shapes.includes(el.type) || textBudget <= 0) {
+        dropped.push(reportId(el, index))
+        degraded = true
+        continue
+      }
+      textBudget--
+      const angles = el.type === "arc" || el.type === "pie" ? {startDeg: el.startDeg, endDeg: el.endDeg} : {}
+      out.push({
+        id: el.id,
+        type: el.type,
+        box: clamped,
+        style: el.style,
+        ...(points ? {points} : {}),
+        ...angles,
+        ...(transition ? {transition} : {}),
+        ...transform,
+        ...plane,
+        contentHash: elementContentHash({
+          type: el.type,
+          style: el.style,
+          points,
+          ...angles,
+          data: transformHash,
+          depth,
+        }),
+      })
+      continue
+    }
+
     if (el.type === "image") {
       // Images: a shrunk box can't be honored (we don't crop pixels host-side)
       // and per-image device limits are box-level (the firmware allocates the
@@ -148,7 +321,10 @@ export function processScene(
         type: "image",
         box: clamped,
         data: el.data,
-        contentHash: elementContentHash({type: "image", data: el.data}),
+        ...(el.style ? {style: el.style} : {}),
+        ...(transition ? {transition} : {}),
+        ...plane,
+        contentHash: elementContentHash({type: "image", data: el.data, style: el.style, depth}),
       })
       continue
     }
@@ -167,7 +343,10 @@ export function processScene(
         type: "rect",
         box: clamped,
         style: el.style,
-        contentHash: elementContentHash({type: "rect", style: el.style}),
+        ...(transition ? {transition} : {}),
+        ...transform,
+        ...plane,
+        contentHash: elementContentHash({type: "rect", style: el.style, data: transformHash, depth}),
       })
       continue
     }
@@ -188,7 +367,9 @@ export function processScene(
         box: clamped,
         text: monoText,
         style: el.style,
-        contentHash: elementContentHash({type: "text", text: monoText, style: el.style}),
+        ...(transition ? {transition} : {}),
+        ...plane,
+        contentHash: elementContentHash({type: "text", text: monoText, style: el.style, depth}),
       })
       continue
     }
@@ -221,7 +402,9 @@ export function processScene(
       box: clamped,
       text: wrappedText,
       style: el.style,
-      contentHash: elementContentHash({type: "text", text: wrappedText, style: el.style}),
+      ...(transition ? {transition} : {}),
+      ...plane,
+      contentHash: elementContentHash({type: "text", text: wrappedText, style: el.style, depth}),
     })
   }