### Declare widget examples in defineWidget manifest

Source: https://glasshome.app/docs/widgets/widget-previews

Adds an examples array to the manifest in defineWidget. Each entry contains a label, size in grid tiles, and a config that must satisfy the configSchema. The first example is used as the widget's thumbnail. Up to 20 examples are rendered; extras are ignored.

```TypeScript
export default defineWidget<LightConfig>({
  manifest: {
    name: "Light",
    minSize: { w: 1, h: 1 },
    maxSize: { w: 4, h: 4 },
    sdkVersion: "^1.7.0",
    examples: [
      {
        label: "Single light",
        size: { w: 2, h: 2 },
        config: { title: "Reading Lamp", entityIds: ["light.bedroom_ceiling"] },
      },
      {
        label: "Room group",
        size: { w: 3, h: 2 },
        config: {
          title: "Living Room",
          entityIds: ["light.living_room_main", "light.kitchen_counter"],
        },
      },
    ],
  },
  configSchema,
  component: LightWidget,
});
```

--------------------------------

### Install Playwright Chromium for widget preview

Source: https://glasshome.app/docs/widgets/troubleshooting

Run this command to install Playwright's Chromium browser, which is required for the `widget preview` command to start its browser. Use when the CLI reports it cannot start its browser.

```bash
bunx playwright install chromium
```

--------------------------------

### Preview a single widget

Source: https://glasshome.app/docs/widgets/widget-previews

Pass a widget name to render only that widget's examples.

```bash
bun widget preview light
```

--------------------------------

### Generate previews at custom sizes with bun widget preview

Source: https://glasshome.app/docs/widgets/widget-previews

Renders each example at the specified pixel sizes into `preview/sweep/`, producing a contact sheet per example and theme. The `grid` keyword covers common dashboard sizes, skipping heights not allowed by the manifest.

```bash
bun widget preview light --sizes 150x156,340x242 --theme dark
bun widget preview light --sizes grid
```

--------------------------------

### Run widget preview

Source: https://glasshome.app/docs/widgets/widget-previews

Renders all widget examples locally, saving images to preview/ named <widget>-<label>-<theme>.png.

```bash
bun widget preview
```

--------------------------------

### bun widget upgrade [--to <version>]

Source: https://glasshome.app/docs/widgets/widget-cli

Moves the project to a newer @glasshome/widget-sdk and syncs the sdkVersion in every manifest.json to what is then installed.

```APIDOC
## bun widget upgrade [--to <version>]

### Description
Moves the project to a newer `@glasshome/widget-sdk` and syncs the `sdkVersion` in every `manifest.json` to what is then installed. In a **standalone project**: `bun add`s the SDK at `latest` (or `--to <version>`) into whichever section already declares it, which also pulls in the `@glasshome/ui` it peers, then syncs the manifests and re-runs `bun widget validate`. In a **monorepo workspace** (a `package.json` with a `workspaces` field at or above the project): reads the SDK version from the workspace package, runs `bun install` from the root, syncs every manifest, then re-runs `bun widget validate`.

CLI 0.15+

`upgrade` also points your coding agent at the widget guide the new SDK ships ([Building with a coding agent](https://glasshome.app/docs/widgets/widget-development#building-with-a-coding-agent)).

### Usage
```bash
bun widget upgrade [--to <version>]
```

### Flags
- `--to <version>` - Specify the target SDK version to upgrade to.
```

--------------------------------

### Install Playwright browser

Source: https://glasshome.app/docs/widgets/widget-previews

Required if the browser is missing; the preview command will tell you to run this.

```bash
bun add -d playwright && bunx playwright install chromium
```

--------------------------------

### Example migration from v1 to v2 config

Source: https://glasshome.app/docs/widgets/widget-migrations

Shows a full widget definition with a migrate function that transforms a v1 config (with an optional entity string) to a v2 config (with entityId array and showLabel toggle). The migrate function checks fromVersion and returns a complete config, using defaults for missing fields. The example includes the manifest with configVersion: 2 and a component that uses the new config shape.

```typescript
// src/my-widget/index.tsx
import { defineConfig, defineWidget, field, type Infer } from "@glasshome/widget-sdk";

// v2 config (current)
const configSchema = defineConfig({
  entityId: field.entity("light", { title: "Light" }),
  showLabel: field.toggle({ title: "Show label", default: true }),
});

type Config = Infer<typeof configSchema>;

// The shape v1 configs were saved in. A type, not a schema: it costs nothing at
// runtime, and the compiler checks the old field names you reference below
// instead of you having to remember them.
type ConfigV1 = { entity?: string };

function MyWidget(props: { config: Config }) {
  // field.entity is a single-select picker, but it stores an array, so a later
  // switch to field.entities is not another config break.
  return (
    <div>
      <span>{props.config.entityId[0]}</span>
    </div>
  );
}

export default defineWidget<Config>({
  manifest: {
    name: "My Widget",
    sdkVersion: "^1.4.0",
    minSize: { w: 1, h: 1 },
    maxSize: { w: 4, h: 4 },
    configVersion: 2,
  },
  configSchema,
  migrate(oldConfig, fromVersion) {
    if (fromVersion < 2) {
      const old = oldConfig as ConfigV1;
      return {
        entityId: old.entity ? [old.entity] : [],
        showLabel: true,
      };
    }
    return oldConfig;
  },
  component: MyWidget,
});
```

--------------------------------

### Basic Tile with Widget.Content

Source: https://glasshome.app/docs/widgets/widget-sheets

Example of a tile using Widget.Content with a glyph, head, hero, and controls. Requires SDK 1.17 and a manifest sdkVersion floor of 1.17.

```jsx
<Widget tone="accent" gestures={gestures}>
  <Widget.Content>
    <Widget.Glyph icon="mdi:fan" />
    <Widget.Head icon="mdi:fan" eyebrow="Auto" name="Bedroom Fan" active={isOn()} />
    <Widget.Hero value={speed()} unit="%" art={<img src={fanArt} alt="" />} />
    <Widget.Controls>
      <Widget.Stepper label="Speed" onStep={step} />
    </Widget.Controls>
  </Widget.Content>
</Widget>
```

--------------------------------

### Bug report template

Source: https://glasshome.app/docs/dash/bug-reports

Copy-paste this template into Discord and fill it in to provide a structured bug report. It includes sections for what happened, steps to reproduce, expected behavior, version, device, install method, and logs/screenshots.

```markdown
**What happened:**
[describe the bug]

**Steps to reproduce:**
1. [first step]
2. [second step]
3. [what goes wrong]

**Expected behavior:**
[what should have happened]

**Version:** [e.g. 1.4.0]
**Device:** [e.g. iPad, Chrome on Windows, Pixel 8]
**Install method:** [HA addon / Docker]

**Logs / screenshots:**
[paste logs or attach screenshots]
```

--------------------------------

### Scaffold a new widget project with bunx @glasshome/widget-cli

Source: https://glasshome.app/docs/widgets/widget-development

Run this command with no arguments to create a project and your first widget. Use inside a scaffolded project or with bunx elsewhere.

```bash
bunx @glasshome/widget-cli@latest
```

--------------------------------

### Set CHROMIUM_PATH to use existing Chromium

Source: https://glasshome.app/docs/widgets/troubleshooting

Set the CHROMIUM_PATH environment variable to point the CLI at a Chromium browser you already have installed, as an alternative to installing Playwright's Chromium.

```bash
CHROMIUM_PATH=/path/to/chromium
```

--------------------------------

### bun widget info [name]

Source: https://glasshome.app/docs/widgets/widget-cli

Prints the project header, local registry summary, and per-widget metadata + bundle size.

```APIDOC
## bun widget info [name]

### Description
Prints the project header, local registry summary, and per-widget metadata + bundle size.

### Usage
```bash
bun widget info [name]
```

### Parameters
- `name` (optional) - The name of the widget to show info for. If omitted, shows info for all widgets.
```

--------------------------------

### trackEntityHistory / untrackEntityHistory

Source: https://glasshome.app/docs/widgets/widget-api-reference

Start or stop history tracking for an entity. Each takes an entityId.

```APIDOC
## trackEntityHistory / untrackEntityHistory

### Description
Start or stop history tracking for an entity.

### Signature
`(entityId) => void`

### Parameters
- **entityId** (string) - Required - The ID of the entity to track or untrack.

### Usage
Call `trackEntityHistory(entityId)` to start tracking, `untrackEntityHistory(entityId)` to stop.
```

--------------------------------

### startWebRtcSession

Source: https://glasshome.app/docs/widgets/widget-api-reference

Begin a WebRTC camera session. Starts a WebRTC session for camera streaming.

```APIDOC
## startWebRtcSession

### Description
Begin a WebRTC camera session. Starts a WebRTC session for camera streaming.

### Type
function

### Usage
Call this function to start a WebRTC camera session.
```

--------------------------------

### Rebuild and publish widget

Source: https://glasshome.app/docs/widgets/widget-sdk-1-0

Run the build and publish commands. The build emits index.js + index.css + an updated registry. The publish flow verifies the bundle hash and capability declaration.

```bash
bun run build          # emits index.js + index.css + an updated registry
bun widget publish --scope <your-scope>
```

--------------------------------

### presetValue(key)

Source: https://glasshome.app/docs/widgets/widget-sdk/config

Returns the value that the picker stores for a given preset key. Useful for setting a default or example value.

```APIDOC
## presetValue(key)

### Description
Returns the value that the picker stores for a given preset key. Useful for setting a default or example value.

### Method
presetValue()

### Parameters
- **key** (string) - Required - The preset key (e.g., "coast").

### Returns
- **string** - The stored value for the preset.

### Example
```js
presetValue("coast")
```
```

--------------------------------

### buildWidgets(options?)

Source: https://glasshome.app/docs/widgets/widget-sdk

Programmatic build of all widgets, used by the `bun widget build` command.

```APIDOC
## buildWidgets(options?)

### Description
Programmatic build of all widgets, used by the `bun widget build` command.

### Method
Function

### Endpoint
`buildWidgets(options?)`

### Parameters
- **options** (object) - Optional - Build options.

### Returns
Promise that resolves when the build is complete.
```

--------------------------------

### @glasshome/widget-sdk/vite

Source: https://glasshome.app/docs/widgets/widget-api-reference

Build plugins and helpers for vite.config.ts. The scaffolded config wires these; reach for them only in custom setups. See Build tooling.

```APIDOC
## @glasshome/widget-sdk/vite

### Description
Build plugins and helpers for `vite.config.ts`. The scaffolded config wires these; reach for them only in custom setups. See [Build tooling](https://glasshome.app/docs/widgets/widget-sdk#build-tooling).

### Exports

| Export | Signature | What it is |
| --- | --- | --- |
| `glasshomeWidget` | `(options?: GlasshomeWidgetOptions) => Plugin[]` | Single-widget plugin: dev preview + library build. |
| `glasshomeWidgets` | `(options?: GlasshomeWidgetsOptions) => Plugin[]` | Multi-widget plugin: per-widget builds + `registry.json`. |
| `buildWidgets` | `(options?: BuildWidgetsOptions) => Promise<void>` | Programmatic build of all widgets (used by `bun widget build`). |
| `discoverWidgets` | `(srcDir: string) => DiscoveredWidget[]` | Scan `src/` for subdirs with `index.tsx` + `manifest.json`. |
| `generateRegistry` | `(srcDir: string, outDir: string) => void` | Write a `registry.json` from discovered manifests. |
| `isWidgetExternal` | `(id: string) => boolean` | `true` for host-provided packages (kept out of the bundle). |

### Option Shapes

- `GlasshomeWidgetsOptions`: `{ srcDir?, outDir? }` only.
- `BuildWidgetsOptions`: `{ srcDir?, outDir?, plugins?, viteConfig?, only? }` (`plugins`, `viteConfig`, and `only` are `buildWidgets`-only; `glasshomeWidgets` does not accept them).
- `GlasshomeWidgetOptions`: `{ entry? }` (defaults to `"src/index.tsx"`).
```

--------------------------------

### Add a new widget with bun widget add

Source: https://glasshome.app/docs/widgets/widget-development

Optional command to add more widgets. Prompts for name and description, creates src/<name>/index.tsx and src/<name>/manifest.json.

```bash
bun widget add
```

--------------------------------

### Scaffold a new widget project with bunx @glasshome/widget-cli

Source: https://glasshome.app/docs/widgets/widget-development

Run this command to scaffold a new widget project. It generates package.json, vite.config.ts, tsconfig.json, the 'widget' script alias, and your first widget, prompting for name and description.

```bash
bunx @glasshome/widget-cli@latest
cd <project-name>
```

--------------------------------

### Run GlassHome Dash beta as a standalone container

Source: https://glasshome.app/docs/dash/docker

Runs the glasshome-dash-beta container with the beta image. It uses port 3124 and a separate volume glasshome_beta_data. Open beta at http://<host>:3124.

```bash
docker run -d \
  --name glasshome-dash-beta \
  -p 3124:3123 \
  -v glasshome_beta_data:/data \
  --restart unless-stopped \
  ghcr.io/glasshome/dash:beta
```

--------------------------------

### SDK_VERSION

Source: https://glasshome.app/docs/widgets/widget-api-reference

The installed package version, e.g. "1.2.0". The host compares SDK_VERSION against each widget's manifest.sdkVersion range.

```APIDOC
## SDK_VERSION

### Description
The installed package version, e.g. "1.2.0". The host compares `SDK_VERSION` against each widget's `manifest.sdkVersion` range.

### Type
`string`
```

--------------------------------

### bun widget add

Source: https://glasshome.app/docs/widgets/widget-cli

Prompts for a name and description, then creates src/{name}/index.tsx and src/{name}/manifest.json.

```APIDOC
## bun widget add

### Description
Prompts for a name and description, then creates `src/{name}/index.tsx` and `src/{name}/manifest.json`.

### Usage
```bash
bun widget add
```

### Notes
- Creates a new widget source file and manifest.
```

--------------------------------

### POST /api/v1/widgets/{scope}/{name}

Source: https://glasshome.app/docs/hub/api-reference

Increments the download counter for a widget. This endpoint is called by dashboards on install and is best-effort with no rate-limiting or deduplication.

```APIDOC
## POST /api/v1/widgets/{scope}/{name}

### Description
Increments the download counter for a widget. This endpoint is called by dashboards on install and is best-effort with no rate-limiting or deduplication.

### Method
POST

### Endpoint
/api/v1/widgets/{scope}/{name}

### Parameters
#### Path Parameters
- **scope** (string) - Required - The scope of the widget.
- **name** (string) - Required - The name of the widget.

### Request Body
None

### Response
#### Success Response (200)
- **success** (boolean) - Always true.

#### Response Example
{ "success": true }

### Error Responses
| Status | Condition |
| --- | --- |
| 404 | Widget not found |
```

--------------------------------

### Log in to GlassHome Hub (bun widget login)

Source: https://glasshome.app/docs/widgets/widget-publishing

Optional step to authenticate before publishing. Runs an OAuth PKCE flow against Hub, opening a browser and landing on http://127.0.0.1:9274/callback. The token is stored locally and reused. Separate from 'bun widget connect'.

```bash
bun widget login
```

--------------------------------

### Cloudflared additional_hosts configuration

Source: https://glasshome.app/docs/dash/remote-access

Configuration for the Cloudflared add-on to point a hostname at Dash. Add this as an additional_hosts entry, then start the tunnel and follow the authorization link once.

```yaml
additional_hosts:
  - hostname: dash.example.com
    service: http://192.168.1.100:3123

```

--------------------------------

### JSX: Pass sheet to WidgetDialog when there are extras

Source: https://glasshome.app/docs/widgets/widget-sheets

Pass a sheet render function to WidgetDialog only when there is something extra. This example conditionally adds a sheet using hasExtras().

```jsx
<WidgetDialog
  {...widgetDialogProps}
  {...dialogProps}
  title={name()}
  configSchema={configSchema}
  config={props.config}
  onConfigSave={(c) => ctx.updateConfig(c)}
  {...(hasExtras() ? { sheet: () => <MySheet /> } : {})}
/>
```

--------------------------------

### Integration services dual-domain grant example

Source: https://glasshome.app/docs/widgets/widget-capabilities

Shows the `capabilities` array required for integration services that act on another domain's entities. Both the target entity's domain and the service's own domain must be granted.

```json
"capabilities": [
  { "domain": "media_player", "access": "control" },   // the speaker it acts on
  { "domain": "music_assistant", "access": "control" } // the service it calls
]
```