# Display

> Render scenes of positioned text, images, and shapes on the glasses.

Source: https://docs.glassly.ai/app-devs/core-concepts/display/layouts/

`session.display.render()` draws to the glasses HUD. Each call describes the
whole frame: everything that should be on screen right now. The phone diffs it
against the previous frame, so elements with a stable `id` update in place (no
flicker), anything you leave out of the new frame comes off the screen, and
`render([])` clears it. Your job is to describe the frame; the phone works out
what changed.

```typescript
session.display.render([
  {type: "text",  id: "stats", box: {x: 12, y: 9, w: 200, h: 40},   text: "863 m · 11 min"},
  {type: "image", id: "map",   box: {x: 335, y: 14, w: 150, h: 150}, data: mapPng},
  {type: "rect",  id: "frame", box: {x: 4, y: 4, w: 490, h: 210},   style: {border: 2, radius: 6}},
]);
```

Display needs no permission, but the glasses do need a screen. Declare a `DISPLAY`
hardware requirement in your [manifest](https://docs.glassly.ai/app-devs/core-concepts/miniapp-manifest.md)
so the miniapp only installs on glasses that can show anything.

## Elements

| Element | Fields | Shows |
|---|---|---|
| `{type: "text", box, text, style?, id?}` | `style`: `border`, `radius`, `overflow`, `breakMode`, `font`, `fontSize`, `color` | Wrapped text inside the box. On the Glassly CFW G2 the glasses draw it themselves, so it updates in a few bytes and animates like a shape. |
| `{type: "image", box, data, id?}` | `data`: base64 PNG/JPEG | A bitmap, converted to the glasses' native format by the phone. |
| `{type: "rect", box, style?, id?}` | `style`: `border`, `radius`, `fill`, `color` | A bordered or filled box. |
| `{type: "circle", box, style?, id?}` | `style`: `border`, `fill`, `color` | A circle inscribed in the box. |
| `{type: "arc", box, startDeg, endDeg, style?, id?}` | `style`: `width`, `color` | An arc of the inscribed circle (degrees, 0 = right, clockwise). |
| `{type: "pie", box, startDeg, endDeg, style?, id?}` | `style`: `color` | A filled sector of the inscribed circle. |
| `{type: "line", points, style?, id?}` | 2 points; `style`: `width`, `color` | A straight line. |
| `{type: "triangle", points, style?, id?}` / `quad` | 3 / 4 points; `style`: `border`, `fill`, `color` | An outlined or filled polygon. |
| `{type: "bezier", points, style?, id?}` | 3 (quadratic) or 4 (cubic) points; `style`: `width`, `color` | A curve. |
| `{type: "svg", box, d, scale?, fillRule?, style?, id?}` | `d`: an SVG path string; `fillRule`: `"nonzero"` (default) or `"evenodd"`; `style`: `color` | An SVG path drawn inside the box. |

Every element also takes `rotation`/`pivot` (shapes and SVG) and `depth` (any
element), described below.

Shapes beyond `rect` render where `capabilities.display.shapes` lists the
type (the Even Realities G2 with the Glassly firmware draws all of them on the
glasses); elsewhere they are dropped and reported. `color` is a gray level
0..15. Points are raw canvas pixels and are not anchored.

### Text fonts

`style.font` picks how text is drawn:

| Value | What it does |
|---|---|
| `"default"` | The phone's proportional face, wrapped to the box. |
| `"mono"` | Fixed-pitch text at `style.fontSize` px, line height 1.2 × size, **not** re-wrapped by the phone: lines are taken as given. For grids, terminals, and tables. Devices with no phone-side rasterizer (stock G2 firmware) fall back to their own proportional font. |
| `"builtin"` | The glasses draw the text with their built-in 20 px proportional font. On the Glassly CFW G2 updates are a few bytes each and animate like shapes; lines are clipped to the box. Other devices and stock firmware use the phone's proportional face. |

`style.fontSize` (default 20) sizes `font: "mono"` text.

### Rotation

Geometric shapes and `svg` elements take a `rotation` in clockwise degrees,
unwrapped, so `0` → `360` is a full turn. `pivot` fixes the centre of rotation
in canvas pixels; it defaults to the target box's centre. Text and image
elements ignore both.

```typescript
session.display.render([
  {type: "svg", id: "arrow", box: {x: 40, y: 40, w: 60, h: 60}, d: "M0 0 L10 20 L20 0 Z",
   rotation: 90},
]);
```

Because `rotation` tweens like any other geometry change, giving a rotating
element a stable `id` and a `transition` spins it on the glasses.

### Depth

Every element takes an optional `depth`: a stereo disparity in canvas pixels
from -16 to 16. Positive values float the element in front of the rest of the
frame, negative values sink it behind. Devices whose
`capabilities.display.depth` is true draw the element `depth` px further right
on the left lens and `depth` px further left on the right lens; every other
device draws it flat, at the same place. Depth never drops an element.

Depth is a cue, not an order: elements still paint in array order. A card that
should sit on top of running content therefore goes **last** in the array and
at a **positive** depth. Because it is only a per-lens offset, a card slides in
over the content with the ordinary `transition` mechanics:

```typescript
import type {RenderElement} from "@glassly/miniapp/background";

const content: RenderElement[] = [/* what the miniapp is showing */];
const card = (x: number): RenderElement[] => [
  {type: "rect", id: "card", box: {x, y: 70, w: 300, h: 150}, style: {fill: true, color: 2, radius: 10},
   depth: 8, transition: {durationMs: 350, easing: "ease-out"}},
  {type: "text", id: "card-title", box: {x: x + 16, y: 82, w: 268, h: 30}, text: "Incoming call",
   style: {font: "builtin"}, depth: 8, transition: {durationMs: 350, easing: "ease-out"}},
];
// Move within the canvas, then await the final transition.
await session.display.render([...content, ...card(20)]);
await session.display.render([...content, ...card(252)]);
// remove the card's elements (or park them again first) to take it away.
```

A depth change with a `transition` glides toward or away from the viewer:
each lens moves the element the opposite way, so it comes closer without
changing size. Text uses `style.font: "builtin"` in the example so a moving box
never re-wraps it on the phone.

## Transitions

Give an element a stable `id` and a `transition`, and geometry changes between
renders animate on devices with `capabilities.display.animation`:

```ts
session.display.render([
  {type: "circle", id: "ball", box: {x: 40, y: 100, w: 30, h: 30}, style: {fill: true},
   transition: {durationMs: 300, easing: "ease-in-out"}},
])
// later: the same id at a new box glides there over 300 ms
session.display.render([
  {type: "circle", id: "ball", box: {x: 400, y: 100, w: 30, h: 30}, style: {fill: true},
   transition: {durationMs: 300, easing: "ease-in-out"}},
])
```

Moves, resizes, point and angle changes, `color` and stroke widths tween;
new text or image pixels switch immediately. Devices without animation jump.
Text with a stable `id` can therefore tick, scroll or fade at tens of updates
per second: re-render with the new string and, optionally, a new box.

### Entering and leaving

`transition.enter` starts a new element at a `dx`/`dy` offset in canvas pixels,
at ink 0, then moves and fades it into place. `transition.exit` moves an
existing element to that offset while fading it to ink 0. Keep the exiting
element in the scene with its stable `id` until `durationMs` has elapsed, then
remove it. Simply omitting an element removes it immediately.

```ts
// Apply to a new element to enter from 40 pixels below its box.
const enterTransition = {durationMs: 300, enter: {dy: 40}}
// Apply to an existing element to leave 40 pixels above its box.
const exitTransition = {durationMs: 300, exit: {dy: -40}}
```

Omitted offsets default to zero, allowing a fade without movement. Devices
without animation show entering elements immediately and omit exiting ones.
An exiting element that was never shown is skipped. Phone and browser mirrors
also preview these transitions.

## Screen sizes

`box` is `{x, y, w, h}` in raw device pixels. Coordinates map 1:1 to the
device canvas, with the origin at the top-left:

| Glasses | Canvas | Positioned elements |
|---|---|---|
| Even Realities G2 | 576 × 288 | Yes |
| NIMO | 500 × 220 | Yes |
| RayNeo iO | 540 × 180 | Yes, via Glassly CFW (stock firmware: text fallback) |
| Even Realities G1 | 640 × 200 to 640 × 380, set by the wearer (default 640 × 340; 640 × 200 before Glassly CFW v49) | Yes, via Glassly CFW (stock firmware: text fallback) |
| Vuzix Z100 | 640 × 480 panel | Text fallback |

**We recommend designing your layout for 500 × 220.** A frame that fits
500 × 220 renders as-is on every positioning device; on the G2's larger canvas
it sits in the top-left with some margin. The RayNeo iO canvas is wider but
only 180 px tall, so keep important content in the top 180 px or read the
canvas size from `capabilities.display` and adapt. Boxes that run past the edge are
clamped, and elements past the device's budget are dropped tail-first. Both
show up in the render result, so you find out.

### Anchoring to a corner

For elements that hug a screen corner (a minimap bottom-right, a status glyph
bottom-left), give the box an `anchor`. `x`/`y` then become insets from that
corner, growing inward, and the phone resolves the box against the connected
device's real canvas. The element lands flush on every resolution with
nothing to clamp:

```typescript
session.display.render([
  {type: "image", id: "map", box: {x: 0, y: 0, w: 120, h: 120, anchor: "bottom-right"}, data: mapPng},
]);
```

`anchor` is one of `"top-left"` (the default), `"top-right"`,
`"bottom-left"`, `"bottom-right"`. Corners only, there is no center or edge
anchoring, and no scaling.

When you want an exact fit instead (a full-screen caption), compute boxes
from the connected device's real canvas. `session.capabilities.display`
carries it, populated on the `"ready"` event:

```typescript
const d = session.capabilities?.display;
session.display.render([
  {type: "text", id: "caption", box: {x: 0, y: 0, w: d?.width ?? 576, h: d?.height ?? 288}, text},
]);
```

## Older glasses

Even Realities G1 and Vuzix Z100 show text but can't place elements at
coordinates, and their displays can't show bitmaps. Render the same scene
anyway: the phone converts it for them. Text elements collapse into a single
full-view text layout in reading order (top to bottom, then left to right),
and image and rect elements are dropped. The result tells you what happened
(`degraded: true`, plus the dropped ids), and
`session.capabilities.display.canPosition` tells you up front which kind of
device you're on.

In practice a text-first miniapp works everywhere with zero branching: a
caption app's single full-canvas text element reads the same on every device.
If your layout leans on positioning or images, like a HUD with a minimap,
check `canPosition` and render a text-only variant for these devices.

## Updating and clearing

Give any element that changes over time a stable `id`. Re-rendering with the
same id updates that element in place on the glasses, and unchanged elements
never re-cross Bluetooth, so pushing the whole frame on every change is cheap.
To take something off screen, leave it out of the next frame. To clear
everything:

```typescript
session.display.render([]);
```

## Options and results

`render(elements, options?)` takes `{view, durationMs}`. `view` picks
`"main"` (default) or `"dashboard"`, and `durationMs` auto-clears the frame
after that many milliseconds.

Awaiting is opt-in. A plain fire-and-forget call is fine, and the returned
promise never rejects:

```typescript
const result = await session.display.render(elements);
// result.status: "displayed" (the host accepted the frame) or "blocked"
//                (another app owns the display, or the request failed;
//                result.reason says why)
// result.degraded: true when the phone adjusted the scene for the device
// result.dropped: ids of elements the phone had to drop
// result.presented: true once the glasses have shown this frame's content
//                and its transitions finished; absent on legacy/degraded
//                paths, where "displayed" just means sent
// result.superseded: a newer render() from this app landed before this one
//                 was reported; its content is what's on screen
```

## Just showing text

The simplest useful frame is one text element covering the whole canvas:
a status line, a caption, a "Saved" confirmation.

```typescript
const d = session.capabilities?.display;
session.display.render([
  {type: "text", id: "message", box: {x: 0, y: 0, w: d?.width ?? 576, h: d?.height ?? 288}, text: "Saved"},
], {durationMs: 2000});
```

Per-element `style.breakMode` (`"character" | "character-no-hyphen" | "word" |
"strict-word"`) controls how the text wraps inside its box.

## Helpers

Two optional helpers ship from `@glassly/miniapp`:

```typescript
import { monoTextRows, LatestRenderScheduler } from "@glassly/miniapp";
```

`monoTextRows({id, text, box, fontSize})` splits a fixed-pitch block into one
`text` element per line, each with a stable `${id}-row-N` id, using the G2 mono
renderer's metrics. On G2 custom firmware a line containing unsupported Unicode
then rasterizes only its own row instead of the whole grid. It's opt-in: one row
costs one text element, so check the device's text budget first, and include
every returned row (blanks included) in each replacement scene.

`new LatestRenderScheduler(() => intervalMs)` paces a producer that can generate
frames faster than the glasses can show them. `request(fn)` keeps at most one
render in flight and one replaceable pending callback, so no scene is built
until it can be sent; `clearPending()` drops the queued one and `dispose()`
stops the scheduler. It bounds SDK work, not Bluetooth traffic, and never
cancels work already handed to the phone.

### Text measurement and pixel art

`@glassly/miniapp/display` now exposes the same pure TypeScript text primitives
the host uses. They work in a miniapp background without DOM or native imports:

```typescript
import {G2_PROFILE, TextMeasurer, TextWrapper, pixelArtPng, pixelArtSize} from "@glassly/miniapp/display";

const measurer = new TextMeasurer(G2_PROFILE);
const wrapper = new TextWrapper(measurer);
const wrapped = wrapper.wrap("Next stop: Market Street", {
  maxWidthPx: 280, maxLines: 2, breakMode: "word",
});
const arrow = ["..#..", ".###.", "#####", "..#.."] as const;

await session.display.render([
  {type: "text", id: "directions", box: {x: 12, y: 12, w: 280, h: 80}, text: wrapped.lines.join("\n")},
  {type: "image", id: "arrow", box: {x: 300, y: 12, ...pixelArtSize(arrow)}, data: pixelArtPng(arrow)},
]);
```

Choose `G1_PROFILE`, `G1_PROFILE_LEGACY`, `G2_PROFILE`, `Z100_PROFILE`,
`NEX_PROFILE` (Mentra Display), `RAYNEO_IO_PROFILE` (the RayNeo iO's stock
subtitle page), or `RAYNEO_IO_CFW_PROFILE` (the RayNeo iO's Glassly CFW page) for
your target's text metrics. Read live
capabilities for the canvas size and element budgets, and pass the text box's
width and line limit explicitly. Profiles do not measure arbitrary browser
fonts or `font: "mono"` at a custom size.

Run text from the phone, such as notification titles and bodies, through
`normalizeDisplayText(text)` before laying it out. It drops invisible format
and control characters, collapses every run of spaces, tabs and no-break
spaces to one space, and trims each row, so no row starts with what looks like
a blank. Pass `{multiLine: false}` to fold line breaks into spaces for a
one-row field.

`measureText(text)` returns pixel width. `wrap()` returns `lines`, `truncated`,
`maxLineWidthPx`, `totalBytes`, and per-line `lineMetrics`, plus the original
text and chosen break mode. `wrapToLines()` returns just the lines. Wrapping
also accepts `maxBytes`; its default break mode is `"character-no-hyphen"`.

Pixel-art rows must have equal widths: `.` is black, `#` is full intensity,
and `0`–`f` are gray levels. `pixelArtPng(rows)` returns base64 PNG data;
`pixelArtSize(rows)` returns `{w, h}`. Keep the rows array immutable and reuse
it so encoding can be cached. Image support and element budgets still apply.
The subpath also exports shared scene types such as `SceneElementInput`,
`SceneFrame`, and `SceneTransition`.

## Dashboard view

The dashboard view is one overlay slot above retained main content. The
dashboard is a role, and the running dashboard holds it. A miniapp must declare
manifest `type: "dashboard"` to be eligible. One dashboard runs at a time:
starting one from the Glassly App stops the one running, and only one dashboard
can be Always On. The bundled `com.glassly.dashboard` ships Always On;
uninstalling the running dashboard starts no other. Only the dashboard that
holds the role can take the slot, and only while
`session.capabilities?.display?.views` includes `"dashboard"`. Currently this
requires connected glasses running Glassly CFW and the wearer's dashboard
setting enabled. Check capabilities again when they change.

`showView("dashboard")` takes the slot; `showView("main")` releases it and
restores retained main content. Both are idempotent and resolve with
`{status: "shown" | "unsupported", reason?}` rather than rejecting. A
`dashboard` miniapp that does not hold the role gets
`reason: "not the active dashboard"`; a miniapp of any other type gets
`reason: 'The dashboard view belongs to miniapps of type "dashboard"'`. Rendering
with `{view: "dashboard"}` alone does not acquire the slot.

```typescript
// In a dashboard miniapp's background handler:
session.display.onViewChange(({view, reason}) => {
  if (view === "main") {
    // The page closed or eligibility changed.
    void session.input.setClaimedGestures([], {scope: "page"});
  }
  console.log(view, reason);
});

if (session.capabilities?.display?.views?.includes("dashboard")) {
  const result = await session.display.showView("dashboard");
  if (result.status === "shown") {
    await session.input.setClaimedGestures(["single_tap", "swipe_up"], {scope: "page"});
    await session.display.render([
      {type: "text", id: "page-title", box: {x: 12, y: 12, w: 300, h: 40}, text: "Dashboard page"},
    ], {view: "dashboard"});
  }
}

// When your page closes:
await session.input.setClaimedGestures([], {scope: "page"});
await session.display.showView("main");
```

`onViewChange` reasons are `"shown"`, `"hidden"`, and `"ineligible"`.
`"app_stopped"` and `"replaced"` are included in the reason type but are not
delivered: one dashboard runs at a time, so starting another stops yours.
`onViewChange` returns an unsubscribe function and fires only for the running
dashboard. Release temporary [gesture claims](https://docs.glassly.ai/app-devs/core-concepts/input.md#claiming-gestures)
when a page loses the view.

### Native dashboard

`session.dashboard.showNativeDashboard()` is a different thing: it brings the
glasses' own OS-level idle screen to the foreground. On G2 this tears down the
current page, and the display comes back when the wearer dismisses the dashboard
or you render again. It resolves with `{status: "shown" | "unsupported", reason?}`
and never rejects; `"unsupported"` means the host refused, for instance because
the native nav UI owns the screen.

`session.dashboard.setContent()` remains a deferred widget API and has no
visible effect. Use `session.display` for overlay scenes.

## Native navigation UI

Glasses that report `capabilities.hasNativeNavigation` (the G2) have a
firmware-drawn turn-by-turn screen. Three display methods feed it while a trip is
active. Each resolves with `{status: "sent" | "unsupported" | "blocked", reason?}`
and never rejects; on `"unsupported"` there is no native nav UI or no active trip,
so fall back to `render()`.

```typescript
if (session.capabilities?.hasNativeNavigation) {
  await session.display.sendNativeNavInfo({
    directionIcon: 3,          // firmware direction-icon index, 0…35
    distance: "500 m",
    roadName: "Market St",
    spendTime: "11 min",       // remaining trip duration
    remainDistance: "0.9 km",
    etaTime: "18:18",
    speed: "5 km/h",
  });
}
```

Every `NativeNavInfo` field but `directionIcon` is a pre-formatted display
string the device renders verbatim, so format units and times yourself
(`session.preferences` carries the user's unit system and clock).

`sendNativeNavMiniMap(data, {rotationDeg?, border?})` pushes the live mini map as
a base64 BMP or PNG; the phone re-encodes and scales it to the device's slot
(176 × 176 on G2). Draw it north-up with the cursor centred and let the device
rotate it by `rotationDeg`. `sendNativeNavOverviewMap(data)` pushes the
full-route overview map (576 × 188 on G2).
