Sealed Engine
From Dash 1.5, widgets run in a JavaScript engine (QuickJS, compiled to WebAssembly) with no access to the page. The official GlassHome widgets share one engine, and display-only widgets share an engine with the same publisher’s display-only widgets; a widget installed from your own machine, and any widget that can control the home or read sensitive data, gets an engine of its own. What your widget draws is copied onto the dashboard through an allowlist, and Home Assistant is reached only through the SDK, checked against your capabilities. It is the only engine; there is no setting to run a widget in the page.
This is the developer’s view. For what it means for a homeowner, see Widget Security.
To test your own code, run bun widget connect <dashboard-url> against a Dash 1.5 dashboard as usual. Hot reload keeps the sealed engine. bun widget preview and the Hub’s preview images run in the sealed engine too, so a preview shows what a dashboard shows. The preview takes its engine from the dashboard you name with --dash <url>, or from the demo at https://demo.glasshome.app (Widget CLI).
What your code can use
Write the widget as you do today, with the SDK. A widget that only uses @glasshome/widget-sdk parts and hooks usually works unchanged.
Import only these modules; the engine provides no other package:
@glasshome/widget-sdksolid-js,solid-js/store,solid-js/web
Entity state, callService and icons come through the host. A widget only receives the entities its read capabilities cover.
These globals are stand-ins:
| Global | In the sealed engine |
|---|---|
window |
A plain object holding document and every HTML and SVG element class |
document |
A private document; your changes are copied to the dashboard through the allowlist |
localStorage, sessionStorage |
Two in-memory stores per widget, shared by every copy of that widget on the dashboard and empty again after every reload. They keep widgets apart, but they are no wall: widgets that share an engine share its memory. Your module’s top level reads and writes your widget’s store; a callback it schedules there, such as a timer, runs for no widget, so storage throws SecurityError in it, which you can catch, and nothing else stops. Keep what must last with useWidgetState, which the dashboard stores for each person, or in the widget’s config with updateConfig when it is a setting |
location |
about:blank |
navigator |
A fixed userAgent; language, languages and maxTouchPoints are the dashboard’s |
devicePixelRatio |
The dashboard’s |
document.hasFocus() |
The dashboard’s |
document.documentElement |
Carries the dashboard’s dark and reduce-motion classes and its lang and dir, kept current. getComputedStyle on it answers theme variables, never layout |
document.hidden, visibilityState |
The dashboard’s; visibilitychange fires on document |
setTimeout, setInterval, requestAnimationFrame, requestIdleCallback |
Run by the host; intervals are at least 16 ms apart |
ResizeObserver, IntersectionObserver, innerWidth, innerHeight, documentElement.clientWidth, clientHeight |
Answered by the host; observers count toward the observer limit, and a rootMargin takes pixels or percent, as in a browser |
matchMedia |
Answered by the host; a change listener fires and counts toward the observer limit |
Math.random |
Seeded per widget |
These do not exist: fetch, XMLHttpRequest, WebSocket, RTCPeerConnection, cookies, Capacitor (window.Capacitor, so no haptics yet), and any route into the dashboard’s own code. Camera video and its full screen come through the SDK’s CameraStream, which the dashboard plays for your widget. Built-in objects are frozen, so z.config(...) and other global patches throw.
What reaches the dashboard
Your widget’s DOM is mirrored onto the dashboard, change by change. Anything outside the allowlist is dropped and recorded as a refusal:
- Elements. Ordinary HTML and SVG elements.
<style>,<link>and<script>are refused: put CSS in your widget’s stylesheet, which is checked once when the widget loads. - Attributes.
class,id,style,role,tabindex,title,hidden,aria-*,data-*, the usual per-element attributes, and SVG presentation attributes. - Images.
src,srcsetandpostertake adata:image/...URL, ablob:URL from the dashboard,/ha-proxy/media, or your household’s own pictures, throughimageSrcorimageUrl. Any other address is refused. - CSS. Inline styles and your stylesheet may use the standard CSS functions;
url()follows the image rule above. A stylesheet that breaks the rules stops the widget with “widget styles refused”. - Properties and calls. You can set
value,checked,scrollTopandscrollLeft, and callfocus(),blur(),scrollIntoView()and the pointer-capture methods, which reach the dashboard.click()presses the element within your widget. - Layout reads. Sizes, offsets and
getComputedStylework for layout properties and your own custom properties. - Events. Listen to any event; you receive its plain fields (
type, coordinates, keys,value,checked, touches). Touch and wheel listeners are always passive.
Limits
Each widget gets its own budget. Each publisher’s display-only widgets share one engine and one budget; a widget installed from your own machine runs alone.
A widget’s code acts only for its own widget: calling another widget’s handler does nothing for the host.
GlassHome knows which widget is acting from its components, effects, event handlers and timers. Code that runs after an await, in a .then callback or in queueMicrotask, started by an effect that reacts to entity changes, belongs to no widget, so its ctx calls (updateConfig, callService, onShell and the others) are refused. Code after await ctx.callService(...) still acts for your widget. For any other async work, put the result in a signal and make the ctx call from an effect:
const [result, setResult] = createSignal<Summary>();
createEffect(() => {
const entity = state.entities[entityId];
if (entity) summarize(entity).then(setResult);
});
createEffect(() => {
const next = result();
if (next) ctx.updateConfig({ summary: next });
});
| Limit | Value | When crossed |
|---|---|---|
| CPU | A steady share of each second, measured against the device’s speed, with room for short bursts | The widget stops |
| Setup | A larger allowance for defining and mounting | The widget stops |
| Longest single run | A short slice at once; three long runs within a minute also count as too much | The widget stops |
| Memory | 256 MB | The engine crashes |
| Elements | 20,000 | Further elements are refused |
| Timers | 512 running at once | Further timers are refused |
| Observers | 128 | Further observers are refused |
| Layout reads | 4,000 per frame | Further reads answer 0 |
| Event types listened to | 256 | Further listeners are refused |
A widget that runs over its limits, or hangs the tab, is stopped: it shows “This widget stopped your dashboard” until the homeowner presses Turn back on. It does not restart by itself, and the widgets beside it keep running. When one publisher’s widgets run over together and none of them did it alone, they show Paused with one Turn back on. A widget that throws crashes like it does today and is turned off after three crashes. Running out of memory ends the whole engine: a widget alone in it crashes, and widgets sharing it are paused until the homeowner turns them back on or reloads.
Read the refusals
With Developer Mode on, Settings shows a Sealed widgets card. It updates every second while open. Each widget row shows:
- what it may read and control;
- how hard it is working, from “Barely working” to “Over its limit”;
- Stopped if it went over its limits, with Let it run again;
- Paused if its publisher’s widgets went over together, with Let them run again;
- its five most recent refusals, each a sentence and its code.
| Code starts with | Sentence | Usual cause |
|---|---|---|
tag style, tag link |
Tried to add its own style sheet | A <style> element; move the CSS to the stylesheet |
tag script |
Tried to run a script of its own | A <script> element |
tag |
Tried to add a page element that is not allowed | An element outside the allowlist |
url |
Tried to load something from another address | An image from the internet or a raw Home Assistant path |
style |
Tried to use a style that is not allowed | A CSS function or url() outside the rules |
attr |
Tried to set an attribute that is not allowed | An event handler attribute or an unknown attribute |
prop, value |
Tried to change a property / set a value that is not allowed | A property other than value, checked or scroll |
num |
Tried to read a size that is not allowed | A layout read outside the list |
call |
Tried to call a page function | Another element method |
quota nodes |
Built more of the page than allowed | Over 20,000 elements |
timers |
Started more timers than allowed | Over 512 timers |
observers |
Watched more of the page than allowed | Over 128 observers |
listen |
Listened for more events than allowed | Over 256 event types |
intl |
Asked for a date or number format that is not supported | An Intl option the host does not know |
icons |
Asked for an icon with a broken name | An icon name that is not prefix:name |
callService |
Sent a device request GlassHome could not read | A malformed service call |
size |
Sent an update that was too large | One change or request over 256 KB |
The codes op, tree, batch, args and settle mean the engine received something it cannot read; they point at a bug in GlassHome or the SDK. Please report them.
Known gaps
Some things worked in the page and do not yet in the sealed engine:
- Haptics do nothing.
These are being closed. If your widget hits something else, ask in the GlassHome Discord.