---
title: "Sealed Engine"
description: "Widgets run in a sealed space with no page, network or storage of their own. What changes for your code, the limits, and how to read what GlassHome refused."
canonical: https://glasshome.app/docs/widgets/widget-sealed-engine
section: "Build Widgets"
updated: 2026-11-06
---
# 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](/docs/widgets/widget-capabilities). It is the only engine; there is no setting to run a widget in the page.

> **Info:** 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](/docs/widgets/widget-cli#preview)).

## 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:

```tsx
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](https://discord.gg/FJYdeDmrzv).