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-toolbarbutton shows the extension’s icon, or the first letter of its name, with the paneltitleas 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-osdwidget is placed by itsanchorcorner, 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-panelpage is titled with the paneltitle. Only extensions with anav-panelcan be pinned, and the rail is part of the desktop layout only.
How a panel is loaded
Section titled “How a panel is loaded”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: nosniffCache-Control: no-storeThe 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.
What the sandbox allows
Section titled “What the sandbox allows”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.
The host bridge
Section titled “The host bridge”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 |
Sizing
Section titled “Sizing”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.
Make it look like part of Aperture
Section titled “Make it look like part of Aperture”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:
- 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.
- Stay in the dark colour scheme. Aperture sets
color-scheme: darkon 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 setcolor-scheme: light. - 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)wherea = min(0.9, osdAlpha + 0.2); - panels: 8 px corners, a 1 px
rgba(255, 255, 255, 0.1)border, backgroundrgba(24, 26, 29, a)wherea = 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));Starter
Section titled “Starter”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>React to the camera on screen
Section titled “React to the camera on screen”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.
Do something
Section titled “Do something”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 errorWhen 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.
Who sees what
Section titled “Who sees what”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.storageworks 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 thetapo-controlandeufy-controlexamples show the pattern: a viewer gets the controls, and only an administrator’s slider changes are saved.settings.getandsettings.allwork for everyone and never return secrets. A viewer getscameravalues, and group rows tied to a camera, only for cameras they may see.net.fetchworks for everyone who can see the panel. For an extension granted specific cameras, a user who may see none of them is refused.
Troubleshooting
Section titled “Troubleshooting”| 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 |