# Display mirror

> Query the intended glasses display and preview it in your miniapp's phone UI.

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

`session.mirror` reads the current intended glasses display, including content
from other miniapps and the active dashboard or notification overlay. Declare
`DISPLAY_MIRROR` in your [manifest](https://docs.dev.glassly.ai/app-devs/core-concepts/miniapp-manifest.md):

```json
{
  "permissions": [
    {"type": "DISPLAY_MIRROR", "description": "Show a live glasses preview."}
  ]
}
```

## Query and subscribe

| Method | Returns | Behavior |
|---|---|---|
| `getCurrent()` | `Promise<MirrorSnapshot>` | Query the current intended output. |
| `onUpdate(handler)` | Unsubscribe function | Receive the current snapshot, then updates paced to at most about 30 Hz. |
| `hasPermission` | `boolean` | Whether the manifest declares `DISPLAY_MIRROR`; also available as `session.permissions.has("displayMirror")`. |

```typescript
// In your background layer; send snapshots over a declared UI channel.
const frame = await session.mirror.getCurrent();
session.ui.send("mirror:frame", frame);
const off = session.mirror.onUpdate((next) => {
  session.ui.send("mirror:frame", next);
});
// Call when the preview is hidden or its UI closes.
off();
```

Query first and handle rejection when supporting older hosts, which do not
recognize the request. Missing `DISPLAY_MIRROR` rejects `getCurrent()` with
`PERMISSION_NOT_DECLARED`. Subscriptions are fire-and-forget: an undeclared
subscription receives no frames. Additional listeners receive the SDK's cached
current snapshot. When combining asynchronous queries and a stream, ignore
older `revision` values so a delayed query cannot replace a newer frame.

## Snapshot contents

`MirrorSnapshot` is serializable and includes:

| Field | Meaning |
|---|---|
| `revision`, `updatedAt` | Increasing revision within the host runtime, and snapshot time. |
| `connected`, `model` | Glasses connection and model. A disconnected snapshot may retain the last preview; a model change invalidates it. |
| `canvas` | `{width, height}` in glasses pixels, or `null` without a display. |
| `view`, `appId` | Selected `"main"` / `"dashboard"` view and source miniapp, or `null` when unknown. |
| `content` | A tagged union: `scene` (`elements`, `epoch`), `bitmap` (`data`, base64), `empty`, or `unavailable` (`reason`). |
| `glyphWidths` | Text advances for characters in the snapshot. |

Scene elements are ordered and processed by the host, with stable ids, resolved
coordinates, and pre-wrapped text. Check `content.kind` before reading its
variant's fields.

## Render in the phone UI

Send snapshots over the [two-layer message bus](https://docs.dev.glassly.ai/app-devs/core-concepts/two-layer-architecture.md#talking-between-layers).
The background has no DOM; the canvas belongs in your WebView:

```tsx
import {MirrorCanvas} from "@glassly/miniapp/ui";
import type {MirrorSnapshot} from "@glassly/miniapp/mirror";

export function Preview({frame}: {frame: MirrorSnapshot | null}) {
  return <MirrorCanvas frame={frame} style={{maxWidth: 576, background: "black"}} />;
}
```

`MirrorCanvas` is also exported from `@glassly/miniapp/react`. It paints green
ink on a transparent canvas and sizes to its container. For non-React UIs,
import `MirrorCanvasRenderer` from `@glassly/miniapp/mirror`, construct it with
an HTML canvas, call `update(frame)`, and call `dispose()` on teardown.

The mirror shows output after host arbitration and processing, before hardware
presentation confirmation. It cannot read screenshots from the glasses.
Known native dashboard/navigation handoffs report `unavailable`; firmware
changes the host does not hear about cannot be detected. Browser fonts can
differ from the glasses, and the preview is flat without stereo disparity.
Continuous scenes animate locally; initial snapshots, epoch changes, and
skipped frames snap to their target pose.
