Skip to content

Updated

View MarkdownOpen in ChatGPTOpen in Claude

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-sdk
  • solid-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, srcset and poster take a data:image/... URL, a blob: URL from the dashboard, /ha-proxy/media, or your household’s own pictures, through imageSrc or imageUrl. 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, scrollTop and scrollLeft, and call focus(), blur(), scrollIntoView() and the pointer-capture methods, which reach the dashboard. click() presses the element within your widget.
  • Layout reads. Sizes, offsets and getComputedStyle work 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.