Skip to content

UI panels

A UI panel is an HTML page that Aperture shows inside a sandboxed iframe at a fixed place in the app. This page covers the slots a panel can use, what the sandbox allows, how a panel talks to the app, and how to size and style it. The host side lives in web/src/ext/ and the serving side in internal/api/ext_static.go.

A panel names its slot in the manifest. Extensions only add to a slot; they never replace or reorder Aperture’s own interface, and with no extensions every screen looks exactly as it would without the extension system.

Slot Where it appears Frame Follows the camera grant
camera-detail Under the picture in the camera window that opens when you click a camera on the Dashboard Card Yes
dashboard-card At the end of the Dashboard’s overview column, on the desktop layout while that column is open Card No
settings Under the open section of Settings, on every section, for every signed-in user Card No
nav-panel A full page at /extensions/<id>, linked from the navigation rail once an administrator pins it Card No
player-toolbar An icon button at the end of the control cluster at the top right of the Playback player; clicking it opens a dropdown that holds the panel Bare Yes
player-osd A widget floating over the Playback picture in one corner, shown when a single camera is selected (not in multi-camera or grid view) Bare Yes

“Follows the camera grant” means the panel appears only on cameras the extension was granted; an extension granted all cameras, or one that asked for none, appears on every camera. See Permissions.

Slot details:

  • Card frames sit inside a card with a dark fill (#1b1e21), a hairline border and 8 px corners. The card draws no title.
  • A player-toolbar button shows the extension’s icon, or the first letter of its name, with the panel title as its label. The dropdown is 288 px wide, has a header with the title and a close button, and is clipped to the video area. It closes when you click outside it.
  • A player-osd widget is placed by its anchor corner, inset 12 px from the edges. In the bottom-left corner it sits beside the player’s keyboard-shortcuts button rather than over it. Widgets that share a corner stack in manifest order. The widget stays the same size and in the same place while you zoom the picture. Only the widget itself takes clicks; the space around it passes them to the video.
  • A nav-panel page is titled with the panel title. Only extensions with a nav-panel can be pinned, and the rail is part of the desktop layout only.

Aperture serves extension files at /ext/<id>/…, and only from the bundle’s ui/ folder. The manifest, the backend code and anything outside ui/ are never served. Files are served only while the extension gate is on and the extension is enabled.

Every response carries:

Content-Security-Policy: default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline';
img-src data: blob:; font-src data:; connect-src 'none'; base-uri 'none';
form-action 'none'; frame-ancestors 'self'
X-Content-Type-Options: nosniff
Cache-Control: no-store

The policy is one header line; it is wrapped here for reading. For an .html file, Aperture inserts two things into the page: a style rule :root{color-scheme:dark} and the script that defines window.aperture. They go before </head>, or after <body> if there is no head, or after the doctype if there is neither, so a bare HTML fragment still works and stays in standards mode.

The host then renders:

<iframe sandbox="allow-scripts" src="/ext/com.example.hello-panel/ui/panel.html?camera=front_door" title="Hello"></iframe>

The title is the panel title, or the extension name.

sandbox="allow-scripts" without allow-same-origin runs the panel as an opaque origin. Together with the security policy above, that means a panel:

Can Cannot
Run its own inline <script> and <style> Load a script, stylesheet, font or image from a URL, including files from its own ui/ folder
Show images and fonts from data: URIs, and images from blob: URLs Make any network request (fetch, XHR, WebSocket, EventSource)
Call window.aperture Read cookies or use localStorage, sessionStorage or IndexedDB (they throw a security error)
Navigate within its own frame Read or change the Aperture page around it
Submit forms, open popups or new windows, show alert, confirm or prompt, start downloads, or navigate the top window

Everything a panel needs therefore lives in its HTML file. Embed small images as data: URIs and use system fonts.

window.aperture is a small script that sends messages to the Aperture page and waits for answers. You normally use it through the SDK methods; this is the protocol underneath, for authors who want to understand or replace it.

The panel posts to its parent:

{ "__apReq": true, "id": 7, "type": "storage.get", "payload": { "key": "last_mode" } }

The host answers with the same id:

{ "__ap": true, "id": 7, "result": "eco" }

or, on failure, with "error": "<message>" instead of result. The host accepts a message only when it comes from that panel’s own iframe, and it always acts for the extension it loaded the panel for: a panel cannot name another extension.

type payload result
api.request { method, path, body? } The API response, parsed from JSON; see the broker
storage.get { key } The value, or null if absent or secret
storage.set { key, value } null; the value is stored as a string
storage.delete { key } null
storage.keys {} Array of keys
settings.get { key } The non-secret value, or null
settings.all {} Object of all non-secret values
net.fetch { url, method?, headers?, body? } { status, ok, body }, or { status: 0, ok: false, error, detail } on a connection failure
ui.resize { height, width? } None; send it without an id

A message with an unknown type gets no answer, so its promise never settles.

The only information that flows from the host to the panel without a request is in the frame’s address:

Query parameter When Value
camera camera-detail, player-toolbar, player-osd The camera id; also available as window.aperture.cameraId
osdAlpha player-toolbar and player-osd The user’s Overlay opacity preference, a number from 0 to 1

The host owns a panel’s position and width; the panel asks for a height.

The injected script measures document.body.scrollHeight whenever the document or its body changes size, and once when the page has loaded, and asks for that height. You can ask yourself at any time with window.aperture.resize(height), or resize(height, width) in the bare slots.

Card slots Bare slots (player-toolbar, player-osd)
Starting height 180 px 0 px: invisible until the panel asks
Height range 80 to 4000 px 0 to 4000 px
Width The card’s full width; width requests are ignored 288 px dropdown or 168 px widget, until the panel asks for a width (1 to 4000 px). A request without a width keeps the last one.

A height of 0 hides an overlay without removing it: the frame keeps laying out, so the panel can measure itself and ask to be shown again. Because the automatic measurement keeps running, a widget that hides itself should also have nothing to measure. The Tapo and Eufy examples render an empty root element and call resize(0, 0) when the camera on screen has no pan and tilt.

Ask for the width an overlay needs. A widget that collapses to a 32 px button but keeps a wide frame leaves an invisible strip over the video that swallows clicks.

Design card panels for a narrow column: the Dashboard’s overview column is 340 px wide including padding. Let content wrap.

A panel is a separate document and cannot use Aperture’s stylesheet, so it brings its own. Three rules keep it from looking pasted on:

  1. Keep the body transparent. In a card the panel sits on the card’s fill; in a player slot it sits on live video. A painted body draws a rectangle.
  2. Stay in the dark colour scheme. Aperture sets color-scheme: dark on the frame and injects the same rule into the panel. If the two disagree, the browser is required to give the frame an opaque canvas, which shows as a white box over the video. Do not set color-scheme: light.
  3. Use Aperture’s colours and sizes.
Token Value Use
--fg #f2f4f5 Primary text
--fg-muted #a5a8ac Secondary text, labels
--fg-faint #6f7378 Hints, captions
--surface #1b1e21 The card fill, inputs
--raised #282a2e Chips, active items
--line #222527 Dividers, card outlines
--line-strong #2f3236 Control borders
--brand #4797ff Links, selection, active icons
--brand-solid #006fff Filled primary buttons
--online #39c66d Healthy, on
--warn #eb9608 Warnings
--danger #f2565b Errors

Aperture’s text is 14 px, controls are 32 px tall with 6 px corners, and cards have 8 px corners. The app’s typeface is Inter, which a panel cannot load from a URL, so use the system font stack.

On the player, match the overlay controls instead. They are white text on a dark glass background whose strength follows the Overlay opacity preference in Settings › General:

  • buttons: 32 × 32 px, 6 px corners, background rgba(24, 26, 29, a) where a = min(0.9, osdAlpha + 0.2);
  • panels: 8 px corners, a 1 px rgba(255, 255, 255, 0.1) border, background rgba(24, 26, 29, a) where a = min(0.94, osdAlpha + 0.3).

Read osdAlpha from the address and set it as a CSS variable, so the user’s one slider moves your widget too:

const alpha = parseFloat(new URLSearchParams(location.search).get("osdAlpha") || "");
if (Number.isFinite(alpha)) document.documentElement.style.setProperty("--osd-alpha", String(alpha));

A card panel with the tokens above:

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<style>
:root {
--fg: #f2f4f5; --fg-muted: #a5a8ac; --fg-faint: #6f7378;
--surface: #1b1e21; --line: #222527; --line-strong: #2f3236;
--brand: #4797ff; --brand-solid: #006fff; --danger: #f2565b;
}
* { box-sizing: border-box; }
body { margin: 0; padding: 14px; background: transparent; color: var(--fg);
font: 14px/1.45 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; }
.row { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
.hint { color: var(--fg-faint); font-size: 12px; }
button { height: 32px; padding: 0 14px; border: 0; border-radius: 6px; cursor: pointer;
background: var(--brand-solid); color: #fff; font: inherit; }
.error { color: var(--danger); }
</style>
</head>
<body>
<div class="row">
<span id="label">Loading…</span>
<button id="go" type="button">Refresh</button>
</div>
<p class="hint" id="hint"></p>
<script>
const ap = window.aperture;
async function load() {
try {
const cams = await ap.cameras.list();
document.getElementById("label").textContent = cams.length + " cameras";
} catch (e) {
const hint = document.getElementById("hint");
hint.textContent = e.message;
hint.className = "error";
}
}
document.getElementById("go").addEventListener("click", load);
load();
</script>
</body>
</html>

In a camera slot, window.aperture.cameraId is the camera being shown. Make the panel about that camera rather than listing every camera:

const id = window.aperture.cameraId;
const cam = id ? await window.aperture.cameras.get(id) : null; // needs data.cameras: "read"

You do not need to filter by grant yourself: the host only mounts the panel on cameras the extension may use.

A panel can act through two paths.

Through Aperture’s API, with window.aperture.request. Calls run with the viewer’s rights cut down to the extension’s, so a viewer may be refused what an administrator is allowed.

Through a declared host, with window.aperture.net.fetch. Aperture’s server makes the request and can add a secret the panel never sees:

const ap = window.aperture;
const base = await ap.settings.get("ha_url");
const rows = (await ap.settings.get("lights")) || [];
const entity = rows.find((r) => r.camera === ap.cameraId)?.entity;
const r = await ap.net.fetch(base + "/api/services/light/toggle", {
method: "POST",
headers: { "Authorization": "Bearer {{secret:ha_token}}", "Content-Type": "application/json" },
body: JSON.stringify({ entity_id: entity }),
});
if (r.status === 0) showError(r.error); // a plain sentence; r.detail holds the raw error

When the work needs a long-lived connection, a protocol a browser cannot speak, or a secret used in a way a header substitution cannot express, put it in a backend and let the panel call the backend. The Tapo and Eufy examples do this: the backend serves a small HTTP API on 127.0.0.1, the manifest declares that address as a network host, and the panel reaches it with net.fetch. Any program on the server can reach that port, so a backend serving one should accept only the requests its panels need.

net.fetch resolves on any answer from the host, including 4xx and 5xx; check ok or status. It resolves with status: 0 on a connection failure, with error naming the host and what went wrong (no answer in time, name not found, connection refused, certificate problem). It rejects only when Aperture refuses the request: the host is not allowed, an address setting is empty, or a {{secret:…}} is not a declared or configured secret. Names ending in .local do not resolve on the server; use an IP address or a real DNS name, and say so in your setting’s help text.

Panels in the settings, dashboard-card and camera slots are shown to every signed-in user who reaches those places, viewers included. What a panel can do for each of them differs:

  • API calls are limited to what that viewer may do; see Panels act for the person viewing them.
  • window.aperture.storage works for administrators only. For a viewer every storage call rejects with “extension storage is available to administrators only”. Catch that error and carry on with defaults; a panel that lets it escape stops working for viewers. The jog wheels of the tapo-control and eufy-control examples show the pattern: a viewer gets the controls, and only an administrator’s slider changes are saved.
  • settings.get and settings.all work for everyone and never return secrets. A viewer gets camera values, and group rows tied to a camera, only for cameras they may see.
  • net.fetch works for everyone who can see the panel. For an extension granted specific cameras, a user who may see none of them is refused.
Symptom Cause
The panel never appears The extension is disabled, the gate is off, the camera is not in its grant, or (for dashboard-card) the overview column is closed or you are on a phone
The panel shows a 404 page The entry is outside ui/
A white or grey rectangle over the video The body has a background, or the document sets a light colour scheme
A script or stylesheet does nothing It is loaded from a file or URL; inline it
An image is broken It is loaded from a file; use a data: URI
localStorage throws The opaque origin has no web storage; use window.aperture.storage
A storage call fails for some users Storage is for administrators only
A promise never settles The message type is not one the host knows
An empty strip over the video blocks clicks The overlay did not ask for a width

Extensions · The SDK · Permissions · Extension security