...
` as above: the
class sets `overflow-y: auto` and lets the div shrink inside the panel. Every
scrolling element gets the DeskDash scrollbar from app 0.4.3, inside the
components too. On older apps only a `.dd-scroll` element has it, so scroll
the wrapper rather than the panel's `surface` part.
| Attribute | Effect |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| `heading="..."` | render a title row. Use `heading`, not `title` (the native tooltip) |
| `transparent` | glassy surface instead of solid |
| `bare` | no paint at all: the card keeps its box (padding, layout) but drops background and border |
| `row` | lay children horizontally |
| `settings="panelStyle"` | auto-wire the panel-style preset (see below) |
| Slot | For |
| --------- | ----------------------------------------------------- |
| (default) | the panel body |
| `heading` | a custom or dynamic heading, instead of the attribute |
| `actions` | controls pinned to the right of the header |
| Part | For |
| --------- | -------------------------------------------------- |
| `surface` | the card itself (override padding, layout, border) |
| `header` | the heading row |
| `heading` | the heading text |
Knob: `--dd-panel-pad` sets the surface padding (default
`var(--dd-space-3) var(--dd-space-4)`). The header row renders only when
there is a `heading` attribute or slotted `heading`/`actions` content; an
empty header hides itself.
```css
/* the surface lives in the shadow, so reach it via the part */
#panel::part(surface) { flex-direction: row; gap: 4vw; padding: 0; }
```
## dd-bar [#dd-bar]
A bar segment, for `kind: "bar"` (taskbar) widgets only. Wrap the bar's
visible content in one or more of these: each segment's box is the area
that takes the mouse, and bar-window space outside every segment clicks
through to the desktop or the maximized window beneath. Items may animate
between segments; the SDK follows the boxes automatically.
```html
...
```
| Attribute | Effect |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `edge` | `left` or `right` (absent = bottom). The screen edge the bar window docks to; set it from `ctx.bar.edge`. The host fixes to that edge and lays out along it, as a column on a side edge. |
| `place` | where along the edge. Bottom: `left`, `center`, `right` or `fill` (default). Side edges: `top`, `center`, `bottom` or `fill`. The first three shrink-wrap the content, `fill` spans the edge. |
| `reach="35"` | extra interactive headroom on the inner side of the content (above a bottom bar, beside a side bar), in CSS px, inside the capture box. Hover and magnify animations that rise past the surface stay hoverable in it. |
| `pill` | paint the surface with the house pill look (rounded-full, strong surface, border, shadow). Default is unpainted: the segment is first a capture container; put a `dd-panel` (or anything) inside for visuals. |
Part: `surface` (the inner edge-aligned flex row, a column on a side edge). The element marks
itself `data-dd-interactive` one settled frame after connect; that first
report is what switches the bar window from native input everywhere to
segment-scoped capture. See [Interactivity](/docs/guides/interactivity) for
the bar subsection. Grid widgets have no use for this element.
## dd-button [#dd-button]
The standard button. `variant` is `solid` (default), `ghost`, or `outline`;
content (a label, a `dd-icon`) is projected; `disabled` blocks it. Part:
`button`.
```html
Save
Clear done
Connect
```
```js
btn.addEventListener("click", () => { /* ... */ }); // host click bubbles out
btn.setAttribute("disabled", ""); // reflects onto the inner button
```
## dd-icon-button [#dd-icon-button]
The square (or `round` circle) icon button: transparent at rest, surface on
hover. The glyph comes from `name` (a built-in glyph) or the slot (a
`dd-icon`, or custom SVG built with `dd.ui.create`). Boolean attributes:
`round`, `active` (accent border and text), `off` (muted), `disabled`.
Part: `button`.
```html
Other networks...
On
```
```css
/* an app-specific state, via the part */
dd-chip.is-hidden::part(chip) { text-decoration: line-through; }
```
## dd-app-tile [#dd-app-tile]
A launcher tile: an icon (or a letter fallback) with an optional label.
```html
`](#dd-audio-devices) in it: outputs and inputs, or
only the inputs on an `input` pill; the default checked, a click
switches. The card is an overlay, so
the layout under the pill does not move, but your document needs room for
it (about 12em below the pill; it scrolls past 14em). A second chevron
click or a press outside closes it. Leave the attribute off in a pane only
as tall as the pill.
* Parts: `pill`, `slider`, `value`, `devices` (the card). The mute, chevron
and gear buttons expose no parts.
* Slider input is throttled internally to roughly 10 volume calls per
second, and the thumb and percent hold still during a drag.
* Event `dragchange` (bubbling, composed, `detail: { dragging }`) fires as
the user grabs and releases the slider. A pane document should relay it so
the base widget's [flyout helper](/docs/reference/api/widgets-together#ddpopoutflyout)
holds its hover-retract during a drag:
```js
pill.addEventListener("dragchange", (e) => dd.popout.send(e.detail));
```
## dd-audio-devices [#dd-audio-devices]
The audio device list, with a check on the Windows default. A click makes
that device the default for its direction (output or input) in every role,
as the Windows sound menu does.
```html
`](#dd-radio-toggle).
* A Connect or Disconnect click is the gesture the host asks for. The row
reads "Connecting..." until Windows reports the new state, or 8 seconds
pass.
* `no-add` hides the "Add device" link, which opens the Windows Bluetooth
page (there is no pairing here).
* Parts: `list`, `row`, `glyph`, `name`, `state`, `action`, `empty`, `add`.
## dd-brightness [#dd-brightness]
Brightness sliders: one per display whose brightness can be set (a laptop's
built-in panel, external monitors that answer DDC/CI), primary first. The
display names show only when there is more than one.
```html
` renders one `` per entry of
[dd.bar.store()](/docs/reference/api/bar-widgets#ddbarstore) (the host's
[strip](/docs/reference/api/bar-widgets#ddbarstrip): pins and running apps
in the user's order, windows merged by `appKey`) as its own light-DOM
children, keyed and reconciled in place, never rebuilt. Every behavior is
the store's, so two bars composed from this click, launch, preview, pin
and reorder the same way: a launcher launches once, behind a lock that
holds until its window lands; a single window focuses, or minimizes when it
is the focused one; a stack toggles the host-drawn preview flyout; icons
are cached, the flyout state mirrors the host, the pins toggle gates the
launchers, a drag moves a row. Needs a `kind: "bar"` widget with the
`taskbar` permission.
Go only as deep as the look needs:
0. The tag above, paired with the `pins` preset: no widget code.
1. Restyle. The host is the box: size `dd-app` in widget CSS, measure it,
write inline custom properties on it, animate its layout on it. State
reflects as host attributes (`running`, `pin`, `focused`, `minimized`,
`count="n"`, `noicon`, `launching`, `entering`, `leaving`, `dragging`,
`low-motion`; `sorting` on `` itself for a drag's duration),
so `dd-app[focused] { outline: ... }` is a focus ring with no indicator
at all. The anatomy is parts: `button` > `lift` >
(`icon` | `fallback`) + `ring`; `indicator` > `dot` (one per window,
capped by `max`); `label`. A host state goes in front of the part:
`dd-app[focused]::part(dot)`, `dd-app:hover::part(label)`,
`dd-app[launching]::part(lift)`.
2. Replace a piece. A `` child of `` is cloned into
every entry as slotted light DOM (`slot="indicator"`, `slot="label"`
replace the built-in parts) and widget CSS styles it as
`dd-app[focused] > [slot=indicator]`. Cancelable events (bubble,
composed): `dd-activate` `{ entry }` on click, `dd-launch` `{ entry }`
before the launch, `dd-flyout-open` `{ entry, style }` before a preview
opens (`detail.style` is the style the open sends; edit it in place),
`dd-sort` `{ key, before }` on the drop of a sort, before the move
(`before` is the entry key the row lands in front of, `null` for the
end). `preventDefault()` replaces the default (for `dd-sort`: the host
order comes back).
3. Your own reconcile: `` standalone, fed a `BarEntry` through its
`entry` property, keeps its click, icon, menu tag and launch state.
4. Your own markup: `dd.bar.store()` and `dd.ui.create`.
* `` attributes: `settings="pins"`; `indicator` = `dots` (default)
\| `ticks` (stacked, for a side bar) | `none`; `max` (default 3); `label`
\= `hover` (default) | `none`; `previews` = `click` (default) | `hover`
(a 400 ms dwell opens the preview, a quick sweep opens nothing, a switch
while one is open waits the same dwell, leaving a button closes
nothing); `dwell` (ms); `stagger` (boot cascade step, ms, default 30);
`sortable` (app 0.3.5+; drag to reorder: a press that travels past 6 px picks the
entry up, it moves live under the pointer along the strip's axis, the
release inside the segment commits the move through the store and the
host's stream confirms it; a release outside the segment, a cancel or an
unchanged order puts the host order back; the flyout closes and hover
pauses for the drag, the click the release lands is swallowed, and every
live move fires `dd-change`). `indicator`, `max` and `label` forward to
every entry. A widget that writes inline geometry on the entries should
rest while `` carries `sorting`.
* Lifecycle: a new entry carries `entering` until its finite animations
end (at once when none run); a removed one carries `leaving`, stops
taking input and leaves the DOM when its animations end (700 ms
backstop). Low motion skips both. The first render sets
`--dd-app-delay` (and an inline `animation-delay`) per entry; read it in
your own keyframes as `animation-delay: var(--dd-app-delay, 0s)`.
* Reorders slide: when entries land in new slots (a host emit, a drag
shuffle), every surviving entry plays a short FLIP on the host transform
(Web Animations, `--dd-anim-fast` / `--dd-ease`); low motion skips it.
Leave the host `transform` alone in widget CSS and keep hover and press
transforms on the parts, or the slide fights them.
* Geometry keyframes (width, height) belong on the host, in light DOM,
where the capture-region tracker sees their `animationend`; parts
animate transform and opacity only. Keyframes declared in widget CSS and
applied through `::part()` resolve in the widget stylesheet's scope.
* `dd-change` (bubbles, `detail: { entries }`) fires on `` after
every settled reconcile, entrance and exit, for widget code that measures
the entries. `apps.items` is the live entries in row order,
`apps.appFor(key)` one of them.
* `` stamps the app-menu tag (`data-dd-app` / `data-dd-window` /
`data-dd-pin`) itself, so a right-click opens the host's per-app menu;
`disabled` (set by `dd.ui.pressGuard`) mirrors onto the inner button.
`low-motion` on the host stops every animation and transition inside the
shadow; outside it, override the tokens the components read
(`body.low-motion { --dd-anim-slow: var(--dd-anim-fast) }`) rather than a
`*` selector, which stops at the shadow boundary.
## dd-bar-button [#dd-bar-button]
The start button, a button for one of Windows' own menus, or the trigger
for a pane of the bar's own:
```html
`) or the `icon` attribute (a built-in glyph name, or an SVG
path rendered tinted). A start button with neither draws the four-pane
logo itself, in `currentColor` and sized by `--dd-icon-size` on the host:
parts `logo` and `pane`, `pane-1` to `pane-4`, so a bar can animate the
panes one by one (`dd-bar-button:hover::part(pane-2) { animation-delay:
150ms }`). A `quick-settings` or `notifications` button with neither
draws a sliders or bell glyph (part `glyph`, stroked in `currentColor`,
the same size). `label` is the hover label; `delay` (ms) staggers the
entrance like an entry's.
* `badge` (app 0.4.2 or newer) shows a count or short text as an accent
pill on the icon's top right corner (part `badge`), inside the lift so it
moves with the icon. Absent or empty hides it. The text shows as given,
so cap it yourself (`"99+"`).
* Parts: `button` > `press` (the pressed backplate, a real element because
a pseudo-element on a shadow host never renders) + `lift` > the icon and
`badge`; `label`. Reflects `pressed`, `entering`, `low-motion`, `disabled`. The
host is the box, like ``.
## dd-tray-caret [#dd-tray-caret]
The system-tray caret for a bar widget, in one tag:
```html
`](#dd-bar-button) with that one job: the same
parts (`button`, `press`, `lift`, `glyph`, `label`, `badge`) and
attributes (`icon`, `label`, `delay`, `disabled`), so it styles like your
other bar buttons. Style it by its own tag name
(`dd-notification-bell::part(lift)`) next to your `dd-bar-button` rules.
* It draws a bell, or a moon while Do not disturb is on, and shows the
count as its badge ("99+" above 99, none at 0).
* Reflects `pressed` while its window is open and `dnd` while Do not
disturb is on. The host closes the window on its own (an outside press,
Escape, a click that opened an app, the bar ducking or going away), and
the pressed look follows that, never a local guess.
* `settings="notificationCenter"` follows the preset's "Show notifications"
switch: hidden, and its window closed, while it is off. Without the
preset the bell is always on.
* `` still opens Windows' own
notification center.
## Settings presets on components [#settings-presets-on-components]
The `settings` attribute wires a component to a
[setting preset](/docs/reference/manifest#setting-presets) by name, and
accepts a comma-separated list. `` observes
the `panel` setting and toggles its own `transparent`/`bare` attributes,
and (app 0.2.4+) paints the preset's optional background image by setting
`--dd-panel-image` / `--dd-panel-image-fit` on its surface, with zero widget
code. Raw-class widgets can set the same two custom properties on their
`.dd-panel` element by hand. Reading settings needs no permission, and
presets never write settings.
Two notes: the wiring happens once, when the element first connects
(changing the attribute later does nothing), and `accentColor` is a
fields-only preset with no component-side behavior; read it with
[dd.theme.accent()](/docs/reference/api/environment#ddthemeaccent) instead
of putting it in a `settings` attribute.
## Overriding [#overriding]
Two tiers, matching how much you want to change:
* **Style hooks.** `::part()`, the custom-property knobs, and named slots,
as documented per component above.
* **Subclass and call super.** The constructors are exposed on
`dd.ui.components` (`DdElement`, `DdPanel`, `DdText`, `DdIcon`,
`DdButton`, `DdIconButton`, `DdChip`, `DdMeter`, `DdAppTile`,
`DdVolumePill`, `DdTrayCaret`, `DdApps`, `DdApp`, `DdBarButton`,
`DdNotificationBell`). Extend one, override a method (`build`, `render`,
`applyPreset`), call the super method to keep the original behavior or
skip it to replace it, then register your own tag:
```js
class MyPanel extends dd.ui.components.DdPanel {
render() {
super.render(); // keep the panel's own logic...
this.surface.classList.toggle("my-flag", flag); // ...and add to it
}
}
customElements.define("my-panel", MyPanel);
```
## Building the rest [#building-the-rest]
Components cover chrome. Build everything else with
[dd.ui.create](/docs/reference/api/ui#dduicreate); components compose with
it and with each other (a `dd-panel` heading is itself a `dd-text`).
# Errors and versioning (/docs/reference/errors-versioning)
## Error codes [#error-codes]
Every failed bridge call rejects with an `Error` carrying a `code`:
| Code | When |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `PERMISSION_DENIED` | the method or resource is not granted by the widget's manifest (or, for `dd.widgets`, the target is not user-approved) |
| `INVALID_PARAMS` | params failed host-side validation |
| `NOT_FOUND` | the referenced entity (a key, an item id, a saved network) does not exist; for ids, re-list and retry |
| `PAYLOAD_TOO_LARGE` | a request or response exceeds its documented cap |
| `TIMEOUT` | the operation timed out (host-side, or the SDK's own 15 second client timer) |
| `RATE_LIMITED` | a per-instance rate limit was exceeded; back off |
| `GONE` | the method existed in an older API and was removed. Permanent; the message names the replacement |
| `INTERNAL` | an unexpected host error; details go to the host log |
Handle errors like any other rejected promise, and degrade instead of
crashing:
```js
try {
await dd.media.playPause();
} catch (err) {
if (err.code === "RATE_LIMITED") return; // ignore, the user is mashing
dd.log("warn", "playPause failed", err.code);
}
```
Timeouts: the SDK rejects requests client-side after 15 seconds, except the
`dd.dialogs.*` pickers, which wait on the user (the host guarantees they
settle: a 1 hour backstop plus force-cancel on edit mode, reload, and
removal).
## apiVersion: the bridge contract [#apiversion-the-bridge-contract]
Your manifest's `apiVersion` declares which bridge API the widget was
written against. The host runs everything in the range
`[minSupported ..= version]`; both numbers ride `context.api` and are
currently both `1`.
* **Newer than the host**: the manifest is quarantined at scan ("requires a
newer dashboard") and the widget never loads.
* **Older than `minSupported`**: the widget stays listed, but its instances
render a "needs an update" tile instead of mounting, and every bridge call
would fail `GONE`.
## Deprecation, then removal [#deprecation-then-removal]
API surface is never removed silently:
1. A method (or a change in its output) is first **deprecated**. It keeps
working for at least one release; the SDK warns once per method in your
own console (`[dd] is deprecated: `), and the current
table rides `context.api.deprecated`.
2. When `apiVersion` bumps, deprecated methods move to **removed**: calls
reject with `GONE` and a message naming the replacement.
Rules of thumb: watch your console during development, treat any `[dd]`
deprecation warning as a to-do before the next API bump, and feature-detect
with `context.api.version` when one widget build should span versions.
## minAppVersion: the feature floor [#minappversion-the-feature-floor]
`minAppVersion` and `apiVersion` gate different things. `apiVersion` is the
bridge contract. `minAppVersion` (a plain `x.y.z`) says "this widget needs
DeskDash x.y.z or newer":
* An app older than the floor quarantines the manifest with "needs DeskDash
x.y.z or newer" instead of a raw parse error.
* The marketplace shows such a listing with a "Needs app update" chip and a
disabled Install button.
**The store sets it for you.** The app keeps a table of the release that last
changed each part of the widget surface: every permission, setting type,
setting key, preset, bundled font and manifest field, the bar kind, and one
entry for everything no permission gates (ungated methods, the `dd.*`
helpers, the `dd-*` components, tokens and events). Every new version you
publish is stamped with the newest entry its manifest matches. A value you
write yourself only counts when it is higher, and a published version keeps
the floor it shipped with. Nothing to declare, and nothing to get wrong.
The releases behind the entries, for reference:
| Feature | Since |
| -------------------------------------------------------------------------------------------------------------- | -------- |
| the `power` permission | `0.1.9` |
| the `folders` permission | `0.1.10` |
| the `games` permission | `0.3.2` |
| the `launchers` and `feeds` permissions, the `url` setting type and a fractional `minSize` | `0.3.9` |
| `kind: "bar"`, the `taskbar` permission and the `pins` / `systray` presets | `0.3.0` |
| `dd.bar.strip`, `bar.strip.changed` and `` | `0.3.5` |
| `restartAdvanced` for `dd.power.run` | `0.3.7` |
| `dd.settings.open`, `dd.links.open`, `dd.dialogs.pickDesktopItems` and `dd.power.run` from a bar or its pane | `0.3.7` |
| `dd.feeds.open` | `0.3.11` |
| `dd.notificationCenter`, ``, the `notificationCenter` preset and `` | `0.4.2` |
| `placeholder` and `pick` on setting fields | `0.1.10` |
| the `fonts` manifest field | `0.2.0` |
Because a permission's entry moves whenever that permission gains a method,
an update of your widget can need a newer app than its previous version did
even when your code did not change. The stamp shows on the upload's success
screen and on your submissions page.
# Event reference (/docs/reference/events)
Widgets subscribe to events through the SDK's `on*` methods (`dd.time.onTick`,
`dd.system.onVitals`, ...); every one returns an unsubscribe function. Events
deliver only while the widget is mounted and holds the gating permission;
hidden widgets unmount entirely and receive nothing. A peek (every widget
concealed by the user) keeps widgets mounted, so events keep flowing.
## The topics [#the-topics]
| Topic | Needs | Payload | Delivery |
| ---------------------------- | ---------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `time.tick` | `time` | `{ epochMs }` | second-aligned wall clock |
| `settings.changed` | nothing | effective settings object | on every edit, including live previews from the settings dialog |
| `theme.tokens` | nothing | full `--dd-*` token map | on every theme change and every per-widget style edit (previews and the revert included), to every widget; the SDK re-applies it to `:root` |
| `cursor.hover` | nothing | `{ inside }` | enter and leave over the widget-plus-pane footprint |
| `cursor.move` | nothing | `{ x, y }` viewport fractions | roughly 30 Hz while the cursor is inside |
| `desktop.changed` | `desktop` | `{}` ping | desktop item set changed; re-list |
| `folders.changed` | `folders` | `{}` ping | a granted folder changed; only to affected instances; debounced \~400 ms |
| `launchers.drag` | `launchers` | `{ inside, count, kinds }` | targeted: an OS drag entered or left this instance's drop rect; emitted on target change only |
| `launchers.drop` | `launchers` | `{ items }` | targeted: the drop landed on this instance; the items are already in the widget's store |
| `launchers.changed` | `launchers` | `{}` ping | the widget's store changed (a drop, a forget, an uninstall); every frame of the widget type |
| `system.vitals` | `system` | `SystemVitals` | 1 Hz sampler snapshot |
| `media.nowPlaying` | `media` | `NowPlaying` | change-driven, not fixed-rate |
| `audio.spectrum` | `audio` | `{ bins: number[] }` | \~30 Hz while media plays (20 Hz low-spec) |
| `widgets.changed` | `control` | `{}` ping | some approved instance's state changed; re-list |
| `popout.changed` | manifest `popout` | `{ active, side? }` | open, reshape, close, including host force-closes; both documents |
| `windows.changed` | `taskbar` + kind `bar` | `{ windows }`, the full `dd.windows.list` snapshot | change-driven: a window opened or closed, focus moved, a title changed, minimize state flipped, a window changed monitors; the driver for a taskbar's focus indicator |
| `pins.changed` | `taskbar` + kind `bar` | `{ pins }`, the full `dd.pins.list` snapshot | change-driven: a pin made or removed, or the pinned order moved |
| `bar.strip.changed` | `taskbar` + kind `bar` | `{ items }`, the full `dd.bar.strip.list` snapshot | change-driven: a row added or dropped, a pin made or removed, a move on any bar; the render order for a taskbar, to the bar document and its pane |
| `bar.flyout.changed` | `taskbar` + kind `bar` | `{ open, key }` | the preview flyout's real state, on every open, switch and close, whoever caused it; the bar document only |
| `systray.changed` | `taskbar` + kind `bar` | `{ count, open }` | the notification area's state, on every tray change and every open or close of the host list; the driver for a caret's pressed look. From app 0.4.2, `open` is true only on the bar whose caret opened it |
| `notificationCenter.changed` | `taskbar` + kind `bar` | `{ count, open, dnd, access }`, never the notifications | every change of the count, the access or the Do not disturb mode, and every open or close of the host's notification center; `open` is true only on the bar whose bell opened it. App 0.4.2+ |
| `popout.message` | manifest `popout` | whatever the other document sent | main and pane relay, up to 8 KB per message |
| `peers.drag` | `peers` | `{ active, self }` | drag lifecycle, to same-type frames |
| `peers.drop` | `peers` | `{ data, x, y }` | targeted: only the drop target sees the payload |
| `peers.end` | `peers` | `{ accepted, outside }` | targeted to the drag's source |
## Payload notes [#payload-notes]
**`settings.changed`** carries the effective settings. While the user tries
values in the settings dialog it fires with live-previewed (unsaved) values,
and once more with the stored values if they dismiss; treat every event the
same and re-apply. `dd.settings.get()` always returns the persisted state.
**`theme.tokens`** is delivered to every widget, subscribed or not, and the
SDK re-applies the map to `:root` automatically, so plain CSS needs nothing.
Per-widget style edits (the Style tab of your widget's settings window)
arrive the same way, live previews included. Subscribe (via
`dd.theme.onChange`) only when you resolve token values in JS; never cache
across it. Since app 0.4.0 theme colors fade on screen, and the handlers run
once the fade has settled (at once when there is no fade).
**`cursor.hover` and `cursor.move`** work for non-interactive widgets too:
the window stays click-through, you get the signal without capturing input.
While a popout is open the footprint is the bounding box of widget plus pane
(crossing the gap never flickers a leave), both documents receive `hover`,
and `move` goes to the document the cursor is actually over. For simple
element hover, skip the subscription: mark elements `data-dd-hover` and the
SDK toggles a `dd-hover` class.
**The `{}` pings** (`desktop.changed`, `folders.changed`, `launchers.changed`, `widgets.changed`)
carry no data on purpose: they tell you your last listing is stale, and the
matching `list` call is the read path.
**`system.vitals`**: the payload shape and its nullability contract are on
[the system page](/docs/reference/api/system#ddsystemonvitals). Every field
fails independently; render nulls as absent, not zero.
**`media.nowPlaying`**: shape, the session selection policy, and the local
position interpolation recipe are on
[the media page](/docs/reference/api/media-audio#ddmediaonnowplaying). Seed
with `dd.media.status()`.
**`audio.spectrum`**: 500 loudness bands, the silence marker frame, the
demand-driven capture rule, and the render-loop contract are on
[the audio section](/docs/reference/api/media-audio#ddaudio).
**`popout.changed` and `popout.message`**: lifecycle causes and the 8 KB
relay cap are on
[the popouts page](/docs/reference/api/widgets-together#ddpopout).
**`peers.*`**: the full drag lifecycle, including what `accepted` and
`outside` mean, is on
[the peers section](/docs/reference/api/widgets-together#ddpeers).
**The taskbar streams** (`windows.changed`, `pins.changed`,
`bar.strip.changed`, `bar.flyout.changed`, `systray.changed`) are the whole
truth for a bar: never move a focus indicator, a pressed caret or a row
from your own click, follow the stream. `dd.bar.store()` does that for
you; the shapes and the seed calls are on
[the bar widgets page](/docs/reference/api/bar-widgets).
# Manifest reference (/docs/reference/manifest)
`manifest.json` sits at the root of the widget folder and declares everything
about the widget up front: identity, what it may touch, its settings, and its
size on the grid. The loader is strict: unknown fields are rejected, and an
invalid manifest quarantines the widget with a reason instead of loading it.
A minimal manifest:
```json
{
"$schema": "./.deskdash/manifest.schema.json",
"id": "clock",
"name": "Clock",
"version": "0.1.0",
"apiVersion": 1,
"permissions": { "time": true },
"defaultSize": { "w": 4, "h": 2 }
}
```
## Top-level fields [#top-level-fields]
| Field | Type | Required | Default | Meaning |
| --------------- | ---------- | -------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$schema` | string | no | none | Editor tooling metadata (the dev kit writes `./.deskdash/manifest.schema.json`). Accepted and ignored by the app. |
| `id` | string | yes | | The widget id. Lowercase letters, digits, `.` and `-`, starting with a letter or digit. Must equal the folder name. |
| `name` | string | yes | | Display name. |
| `version` | string | yes | | The widget version. The app treats it as opaque; the marketplace requires dotted numbers (like `1.2.3`) and a strictly higher version on every update. |
| `apiVersion` | number | yes | | The bridge API contract the widget was written against (currently `1`). See [errors and versioning](/docs/reference/errors-versioning). |
| `minAppVersion` | string | no | none | "This widget needs DeskDash x.y.z or newer." A feature floor, checked before anything else, so a too-old app shows a friendly message instead of a parse error. The store stamps it on every published version ([how](/docs/reference/errors-versioning#minappversion-the-feature-floor)); leave it out unless you need a higher one. |
| `entry` | string | no | `index.html` | The widget document, a file inside the widget folder. Relative paths only: no leading `/`, no `..`, no `\`. |
| `description` | string | no | `""` | Short description. |
| `author` | string | no | `""` | Author name. Marketplace installs get this stamped by the store. |
| `permissions` | object | no | all off | What the widget may touch. See [the permissions reference](/docs/reference/permissions). |
| `interactive` | boolean | no | `false` | The widget wants real mouse input: while the cursor is over it, the window captures the mouse. Non-interactive widgets can never be clicked. |
| `contextMenu` | boolean | no | `true` | `false` opts the widget out of the right-click widget menu: in view mode right-clicks pass through it (to a widget beneath, or to the desktop's own menu), so a decorative widget is fully inert. Edit mode ignores the flag, so the widget stays configurable and removable there. App 0.2.3+. |
| `settings` | array | no | `[]` | Setting fields and preset names, mixed. The marketplace accepts up to 32 entries; a preset name counts as one. See below. |
| `defaultSize` | `{ w, h }` | no | `{ "w": 4, "h": 2 }` | Size in grid cells when the widget is added. Each dimension 1..64. |
| `minSize` | `{ w, h }` | no | `{ "w": 1, "h": 1 }` | The smallest the user can resize it to. Each dimension 0.25..64, in steps of 0.25. The app rounds it up to whole cells of the user's grid scale, never below one cell. A fraction is app 0.3.9+. |
| `popout` | object | no | none | Declares the popout capability. See below. |
| `fonts` | object | no | none | Bundled font pins. App 0.2.0+. See below. |
## Settings [#settings]
Each `settings` entry is either a full field object or a preset name string;
the array accepts both, mixed:
```json
"settings": [
{ "key": "title", "type": "text", "label": "Title", "default": "Tasks" },
"panelStyle"
]
```
The marketplace accepts up to 32 entries in `settings`; a preset name counts
as one entry, whatever it expands to.
### Field objects [#field-objects]
| Key | Type | Required | Meaning |
| ------------- | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key` | string | yes | The name your code reads the value under. |
| `type` | string | yes | One of the field types below. |
| `label` | string | yes | Shown in the settings dialog. |
| `default` | any | no | The value before the user edits anything. Ignored for `secretRef`, `filePath`, `instances`, and `url` (see below). |
| `options` | string\[] | no | The choices for a `select`. A `select` with no `default` falls back to its first option. |
| `min`, `max` | number | no | Bounds for a `number`, and `max` caps the rows of a `list`. They are numbers, so `date` and `time` take no bounds. |
| `placeholder` | string | no | Hint text for empty `text`, `filePath` and `url` inputs, and for an empty `list` row. App 0.1.10+. |
| `pick` | `"file"` or `"folder"` | no | Adds a Browse button beside a `filePath` input and controls what it picks. App 0.1.10+. |
| `showIf` | `{ "key", "equals" }` | no | Renders the field only while the sibling setting named `key` has the value `equals` (its default counts while unset). Use primitive values; a key that names no sibling fails open and the field shows. App 0.2.6+. |
The `date` and `time` types are app 0.3.4+, and `list` is app 0.3.7+. Older
apps do not know them and quarantine the widget; the store sets
`minAppVersion` for you.
### Field types [#field-types]
| Type | The user gets | Your code gets |
| ----------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `text` | a text input | string |
| `number` | a number input (`min`/`max` bounds) | number |
| `boolean` | a toggle | boolean |
| `select` | a dropdown of `options` | string |
| `color` | a color picker | string |
| `date` | a calendar picker | a `"YYYY-MM-DD"` string, or `""` while unset; [`dd.dates.fromDayKey`](/docs/reference/api/environment#dddatesfromdaykey) makes it a local `Date` |
| `time` | a clock picker | an `"HH:MM"` string, or `""` while unset |
| `list` | text rows they add, reorder and remove | `string[]`, always an array; `[]` when they added nothing and the manifest declares no `default` |
| `secretRef` | a picker over their stored secrets | a name usable in `dd.http.fetch` secrets; never the value |
| `filePath` | a path input (plus Browse with `pick`) | nothing directly; used as `settingKey` in `dd.files`, `dd.folders`, `dd.dialogs`, `dd.claudeUsage` |
| `instances` | a picker over other widget instances | nothing directly; feeds `dd.widgets` |
| `url` | a web address input, flagged unless https (http on localhost) | nothing directly; used as `settingKey` in `dd.feeds`. App 0.3.9+ |
The four consent-bearing types (`secretRef`, `filePath`, `instances`, `url`)
never inherit a manifest default. Their value grants access to something the
user owns or chooses (a credential, a file, other widgets, a web address), so only a value the user actively
picked counts; a published widget cannot ship pre-pointed at anyone's
private data.
### Setting presets [#setting-presets]
A preset bundles a recurring field (or field pair) with the code that applies
it, declared by name:
| Preset | Expands to | Applied by |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `panelStyle` | a `Panel style` select (`none` / `solid` / `transparent` / `image`, default `solid`, key `panel`), plus from app 0.2.4 a `Background image` file picker (key `panelImage`) and an `Image fit` select (key `panelImageFit`), both shown in the settings dialog only while the style is `image` | `` toggles its `transparent` / `bare` attributes and paints the image; zero widget code |
| `accentColor` | a `Use theme accent color` toggle (key `useAccent`, default on) plus a `Custom color` picker (key `color`) | your code, via `dd.theme.accent(settings)` or `dd.theme.bindAccent(cb)`; it has no component-side auto-apply |
| `systray` | a `Show the system tray` toggle (key `showTray`, default on) | [``](/docs/reference/components#dd-tray-caret) shows or hides the caret; zero widget code |
| `notificationCenter` | a `Show notifications` toggle (key `showNotifications`, default on); app 0.4.2+ | [``](/docs/reference/components#dd-notification-bell) shows or hides the bell (and closes its window when turned off); zero widget code |
| `pins` | a `Show pinned apps` toggle (key `showPins`, default on) | [``](/docs/reference/components#dd-apps-and-dd-app) shows or hides the launchers (and never asks the host for pins while off); zero widget code. Bar widgets only, app 0.3.0+ |
| `weekStart` | a `Week starts on` select (`monday` / `sunday`, key `weekStart`); app 0.3.4+ | your code, via [`dd.dates.startOfWeek(d, settings.weekStart)`](/docs/reference/api/environment#dddatesstartofweek), which takes the string as stored |
| `textScale` | a `Text size` select (`tiny` / `small` / `medium` / `large` / `huge`, key `textSize`); app 0.3.4+ | your code mirrors it onto the body (`document.body.dataset.textScale = value`); the base stylesheet turns it into the `--dd-text-scale` multiplier, which the [autoscale skeleton](/docs/guides/theming#autoscale-readouts-that-follow-the-widgets-size) and any `calc(... * var(--dd-text-scale, 1))` of your own ride |
An unknown preset name quarantines the manifest. To keep a preset's behavior
but change its default, declare the field inline with the same `key` and your
default, and still put the preset name on the component; it keys off the
setting value regardless of how the field was declared. Declare all of the
preset's fields when you do, and drop the preset name from the manifest:
expansion appends without deduplicating, so keeping both lists a field twice.
Published manifests carry presets already expanded (the store renders the
field list from them), so a preset gaining a field reaches installed widgets
only through a new widget version.
## Bar [#bar]
```json
"kind": "bar",
"bar": {
"thickness": 64, "reserve": 64, "edges": ["left", "right"], "allowOverlay": true,
"autoHide": { "hideDelay": 150, "revealBand": 2, "slide": 140 }
}
```
A `kind: "bar"` manifest renders as the taskbar instead of a grid widget
and must carry a `bar` block. `thickness` (logical px, 24 to 128) is the
window's extent away from its edge, and the user may scale it (the Size
slider in the bar's settings dialog, 50% to 200%), so treat it as the design
size and lay out against the viewport; `reserve` (0 to thickness, default =
thickness) is the strip the OS reserves, and a smaller value leaves
transparent headroom for hover animations; `edges` (default `["bottom"]`;
`"left"` and `"right"` make a vertical bar) lists the edges the bar can
dock to, the first being the default and several giving the user a Side
choice; `allowOverlay` (default `true`) lets the user drop the reservation;
`autoHide` (optional, every field optional) tunes the user's auto-hide:
`hideDelay` ms before the bar hides (0 to 2000, default 150), `revealBand`
logical px on the screen edge that reveals it (1 to 8, default 2), `slide`
ms for the slide (0 to 600, default 140). Side, auto-hide and overlay are
picked in the bar's own settings dialog. Bars are app 0.3.0+ (the store
sets `minAppVersion`). The [bar widgets
reference](/docs/reference/api/bar-widgets) covers the surface.
A bar declares no explicit `filePath`, `secretRef`, `instances` or `url` field: the
bar's settings dialog never offers those types, so the user could never set
one, and the loader, the upload validator and the CI check all refuse the
manifest (app 0.3.7 or newer; older apps loaded it and never showed the
field). Preset names are exempt: `panelStyle` keeps its image field on a bar,
and its `image` option stays unavailable there (`solid` and `transparent`
work).
## Popout [#popout]
```json
"popout": { "max": { "w": 8, "h": 6 }, "entry": "pane.html" }
```
Presence declares that the widget may temporarily extend past its grid rect
via [dd.popout.open](/docs/reference/api/widgets-together#ddpopoutopen). It
is a geometry capability like `interactive`, not a privacy permission: the
pane is a second sandboxed document with the same grants. A `kind: "bar"`
widget declares it without `max` (its pane renders beside the strip, capped
to the display).
| Key | Meaning |
| ------- | -------------------------------------------------------------------------------- |
| `max` | Caps the pane size, in base grid cells like `defaultSize`. Each dimension 1..64. |
| `entry` | The pane document, a file in the widget folder (same path rules as `entry`). |
## Fonts [#fonts]
Optional, and app 0.2.0+ (older apps do not know the key; the store sets
`minAppVersion`). Pins a font onto one or more of the three face tokens, in this
widget's documents only:
```json
"fonts": { "use": { "display": "audiowide" } }
```
`use` takes any of `sans`, `display`, `mono`. Values are bundled catalog ids
(`audiowide`, `nunito`, `nunito-sans`, and from app 0.2.4 the pixel set
`pixelify-sans`, `press-start-2p`, `silkscreen`; an unknown id quarantines
the manifest, so the pixel ids need app 0.2.4+) or a
`self:` reference to a family the widget ships itself:
```json
"fonts": {
"bundle": [{ "id": "heading", "files": [{ "src": "fonts/mine.woff2", "weight": "400" }] }],
"use": { "display": "self:heading" }
}
```
| Key | Meaning |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| `bundle` | Families shipped in the widget folder. Each has an `id` (for `self:` references) and 1..6 `files`. |
| `bundle[].files[].src` | Path inside the widget folder, charset `A-Za-z0-9._/-`. |
| `bundle[].files[].weight` | One value or a variable range (`"200 1000"`), each within 1..1000. Default `"400"`. |
| `bundle[].files[].style` | `"normal"` (default) or `"italic"`. |
| `use` | Optional pins: `sans`, `display`, `mono`, each a catalog id or `self:`. |
Rules, enforced at manifest load and again by the marketplace validators:
woff2 only (sniffed by magic number, never by extension); at most 4 families,
6 files per family, 2 MB per file, and 4 MB of fonts per widget. The host
generates all resulting CSS itself and names families by index, so nothing a
manifest says ever reaches a stylesheet.
The pin wins over themes and user overrides inside your documents. Your CSS
keeps using the token (`font-family: var(--dd-font-display)`). Two notes:
`dd.theme.tokens()` does not see pins, `dd.ui.token()` does, so canvas
drawing must resolve faces through
[dd.ui.token()](/docs/reference/api/ui#dduitoken). Every bundled catalog face
also exists as a convenience var (`--dd-font-audiowide`, `--dd-font-nunito`,
`--dd-font-nunito-sans`, `--dd-font-pixelify-sans`,
`--dd-font-press-start-2p`, `--dd-font-silkscreen`), so a `select` setting
can offer a font choice without a literal family name in widget code.
Publishing note: the marketplace requires every font-shaped file in the
folder to be declared in `fonts.bundle`, holds font-carrying submissions for
licensing review, and requires the font's license to permit embedding and
redistribution, with the license text included in the widget.
## Validation [#validation]
What the loader enforces, in order:
1. `minAppVersion`, when present, must be a string that parses as `x.y.z`,
and the running app must satisfy it. A too-old app reports "needs
DeskDash x.y.z or newer".
2. `apiVersion` newer than the host reports "requires a newer dashboard".
3. The strict parse: unknown fields anywhere are rejected.
4. `id` must match `^[a-z0-9][a-z0-9.-]*$` and equal the folder name.
5. `entry` (and `popout.entry`) must be a relative path inside the widget
folder: no leading `/`, no `..`, no `\`.
6. Sizes (`defaultSize`, `popout.max`) must each be 1..64 cells per
dimension, and `minSize` 0.25..64 in steps of 0.25; `popout.max` is required for grid widgets and absent on
bars. `bar.edges` is a non-empty list of distinct edges; `bar.autoHide`
fields must sit in their ranges (`hideDelay` 0 to 2000, `revealBand` 1
to 8, `slide` 0 to 600).
7. A `kind: "bar"` manifest may not declare an explicit `filePath`,
`secretRef` or `instances` field (app 0.3.7 or newer), or a `url` field
(app 0.3.9 or newer); preset names are exempt.
8. `fonts`, when present, is validated file by file (existence, format,
caps) before the widget loads. Fail closed: a bad font spec quarantines
the manifest.
A quarantined widget shows up with its reason in the widget list; it never
takes the rest of the dashboard down.
# Permissions reference (/docs/reference/permissions)
Everything is denied by default. A widget declares what it needs in the
manifest's `permissions` object, and the user consents at install time,
permission by permission. Three rules shape the system:
* **Consent can only narrow.** What the user granted is intersected with the
manifest; nothing can escalate past what the manifest declared, and the
user may grant less.
* **Updates re-prompt only for additions.** An update that adds a permission
asks again; removals apply silently.
* **Ask for what you use.** Every grant is shown to the user in plain
language (the wording below). A widget requesting more than it visibly
needs reads as suspicious in review and to users.
## The permissions [#the-permissions]
The wording in the second column is exactly what the marketplace shows the
user at install time.
| Permission | Shown to the user as | Unlocks |
| ---------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `time` | Reads the current time from the dashboard's clock | [dd.time](/docs/reference/api/environment#ddtime), the `time.tick` event |
| `storage` | Saves its own data inside the dashboard | [dd.storage](/docs/reference/api/settings-storage#ddstorage) |
| `files` | Reads files or folders you explicitly pick for it | [dd.files.read](/docs/reference/api/settings-storage#ddfiles) of user-set `filePath` settings |
| `desktop` | Integrates with your desktop (icons, wallpaper area) | [dd.desktop](/docs/reference/api/desktop-apps#dddesktop), `desktop.changed`, [dd.dialogs.pickDesktopItems](/docs/reference/api/notifications-dialogs#dddialogspickdesktopitems) |
| `system` | Reads system stats like CPU, memory and battery | [dd.system.status / onVitals](/docs/reference/api/system#ddsystem), the `system.vitals` stream |
| `systemControls` | Changes system settings such as volume, sound devices, Wi-Fi, Bluetooth and brightness | the [dd.system](/docs/reference/api/system#ddsystem) write surface: volume, mute, the microphone, the radio switch, Wi-Fi, openSettings, the audio device list and switch, the per-app mixer, the paired Bluetooth list and connect, display brightness. Useless without `system` |
| `media` | Sees what music or video is playing | [dd.media.status / onNowPlaying](/docs/reference/api/media-audio#ddmedia), the `media.nowPlaying` stream |
| `mediaControls` | Controls media playback | the [dd.media](/docs/reference/api/media-audio#transport-controls) transport verbs. Useless without `media` |
| `audio` | Reads audio levels (for visualizations) | the [audio.spectrum](/docs/reference/api/media-audio#ddaudio) stream. Loudness bands only, never raw audio |
| `control` | Controls other widgets you grant it access to | [dd.widgets](/docs/reference/api/widgets-together#ddwidgets) over user-approved targets, `widgets.changed` |
| `peers` | Talks to other widgets of the same type | [dd.peers](/docs/reference/api/widgets-together#ddpeers) drag and drop |
| `systemApps` | Opens system apps you pick for it | [dd.apps](/docs/reference/api/desktop-apps#ddapps), catalog keys only |
| `claudeUsage` | Reads your local Claude Code usage summary | [dd.claudeUsage.status](/docs/reference/api/data-services#ddclaudeusage), aggregated only |
| `notifications` | Shows you reminders, even when the widget is hidden | [dd.notify.sync](/docs/reference/api/notifications-dialogs#ddnotify) |
| `power` | Shuts down, restarts (also into advanced startup), sleeps, locks or signs out of this PC | [dd.power](/docs/reference/api/system#ddpower) |
| `folders` | Lists and opens items in folders you pick for it | [dd.folders](/docs/reference/api/desktop-apps#ddfolders), `folders.changed`, [dd.dialogs.pickFolderItems](/docs/reference/api/notifications-dialogs#dddialogspickfolderitems) |
| `games` | Sees the games installed on this PC and can start them | [dd.games](/docs/reference/api/desktop-apps#ddgames), opaque ids and local cover art |
| `taskbar` | Reads your taskbar: open windows, pinned apps, the notification area and how many notifications you have | the bar-only surface (`kind: "bar"` widgets): [dd.windows](/docs/reference/api/bar-widgets#ddwindows), [dd.pins](/docs/reference/api/bar-widgets#ddpins), [dd.bar.strip](/docs/reference/api/bar-widgets#ddbarstrip) (with its one write, a reorder on the user's drag), [dd.bar.flyout](/docs/reference/api/bar-widgets#ddbarflyout), [dd.systray](/docs/reference/api/bar-widgets#ddsystray), [dd.notificationCenter](/docs/reference/api/bar-widgets#ddnotificationcenter) (0.4.2+: a count and open and close; the notifications stay in a host-drawn window), [dd.bar.openStartMenu](/docs/reference/api/bar-widgets#ddbaropenstartmenu), [dd.bar.openQuickSettings](/docs/reference/api/bar-widgets#ddbaropenquicksettings) and [dd.bar.openNotifications](/docs/reference/api/bar-widgets#ddbaropennotifications) |
| `launchers` | Opens the files, folders and apps you drop on it | [dd.launchers](/docs/reference/api/desktop-apps#ddlaunchers), the `launchers.drag`, `launchers.drop` and `launchers.changed` events. Grid widgets only: the drop gesture is the consent, and the widget only ever sees opaque ids |
| `feeds` | Reads news feeds from web addresses you enter in its settings and opens their articles when you click them | [dd.feeds.fetch](/docs/reference/api/data-services#ddfeeds), the address the user typed into a `url` setting. The host fetches and parses the feed; only titles, links and dates reach the widget. [dd.feeds.open](/docs/reference/api/data-services#ddfeedsopen) (0.3.11+) opens those links from a click, no `links` grant needed |
## The scoped grants [#the-scoped-grants]
`http` and `links` are objects, not booleans, and their scope is part of the
consent.
### http [#http]
```json
"permissions": { "http": { "hosts": ["api.open-meteo.com"], "rateLimit": 60 } }
```
* `hosts`: exact hostnames the widget may fetch through
[dd.http.fetch](/docs/reference/api/data-services#ddhttpfetch). Shown to
the user as: "Talks to the internet, only to:" followed by the list. No
wildcards; every hop of a redirect is re-checked.
* `rateLimit`: requests per minute, optional. Omitted means the host default
of 30; values are clamped to 120. Never shown at install.
### links [#links]
```json
"permissions": { "links": { "prefixes": ["steam://run/"] } }
```
* `prefixes`: URL prefixes
[dd.links.open](/docs/reference/api/core#ddlinksopen) may launch, each a
full `scheme://...` string. Shown to the user as: "Can open these link
types on your PC:" followed by the list. Empty means no access, and
dangerous schemes are refused at call time no matter what a manifest
declares.
## Read and control pairs [#read-and-control-pairs]
Two capabilities are split so that reading never implies acting:
* `system` reads vitals; `systemControls` changes volume, the
microphone, the radios, Wi-Fi, the sound device, per-app volume,
Bluetooth connections and brightness, and opens settings panels. The
lists that name your apps, devices and displays are `systemControls`
reads too. Controls without `system` are useless.
* `media` reads now-playing; `mediaControls` drives playback.
`power` is deliberately its own permission rather than part of
`systemControls`: granting a volume slider is not granting the ability to
turn the machine off.
## Version floors [#version-floors]
Some permissions did not exist in the earliest app releases, and others
gained methods later. You do not declare anything for this: the store
stamps every new version's `minAppVersion` from the release that last
changed each permission it requests (see
[the feature floor](/docs/reference/errors-versioning#minappversion-the-feature-floor)).
The entries above the oldest supported app, today:
| Permission | Last changed in |
| ---------------------------------------------------- | --------------- |
| `audio` | `0.3.0` |
| `games` | `0.3.2` |
| `desktop`, `folders`, `links`, `power`, `systemApps` | `0.3.7` |
| `launchers` | `0.3.9` |
| `feeds` | `0.3.11` |
| `system`, `systemControls`, `taskbar` (bar widgets) | `0.4.2` |
## Consent-bearing settings [#consent-bearing-settings]
Four setting types are part of the permission story:
`filePath` (which file or folder), `secretRef` (which credential),
`instances` (which other widgets), and `url` (which web address a feed
comes from). Their manifest defaults are always
ignored; only what the user actively picked counts. See
[the manifest reference](/docs/reference/manifest#field-types). Bar widgets
cannot declare these fields at all: the manifest refuses them, see
[Bar](/docs/reference/manifest#bar).
One API rides this model with no grant of its own:
[dd.image.load](/docs/reference/api/settings-storage#ddimageload) returns
the image the user picked in a `filePath` setting as a `data:` URL. The
picked file IS the consent; the method can read nothing else, and only
sniffed image bytes with an 8 MB cap ever cross the bridge.
For the containment model behind all of this, see
[How the sandbox works](/docs/concepts/security).
# Token reference (/docs/reference/tokens)
Every visual in DeskDash rides the `--dd-*` design tokens: the shell, the
built-in widgets, and yours. Style with tokens and your widget follows every
theme automatically; hardcode a color and it sticks out the moment the user
switches themes.
The values below are the defaults (a dark baseline). Themes may change any
of them at runtime: plain CSS picks changes up automatically, and JS that
resolved a token (canvas, inline SVG) should re-read via
[dd.ui.token()](/docs/reference/api/ui#dduitoken) inside
[dd.theme.onChange](/docs/reference/api/environment#ddthemeonchange).
## Surfaces [#surfaces]
| Token | Default | Used for |
| -------------------------- | --------------------------- | --------------------------------------------------- |
| `--dd-bg` | `transparent` | the widget document background; keep it transparent |
| `--dd-surface` | `rgba(17, 22, 31, 0.72)` | the standard panel surface |
| `--dd-surface-strong` | `rgba(13, 17, 24, 0.92)` | emphasized surfaces (popovers, panes) |
| `--dd-surface-transparent` | `rgba(17, 22, 31, 0.35)` | the barely-there glass panel style |
| `--dd-border` | `rgba(148, 163, 184, 0.16)` | hairline borders |
`--dd-surface-transparent` is transparent by contract: widgets using it
should read as floating on the desktop, and the user's surface-opacity
setting deliberately leaves it alone (that knob solidifies the solid
panels).
## Text [#text]
| Token | Default |
| ----------------- | --------- |
| `--dd-text` | `#e7edf5` |
| `--dd-text-muted` | `#94a3b8` |
## Accent and status [#accent-and-status]
| Token | Default | Used for |
| ---------------------- | --------- | -------------------- |
| `--dd-accent` | `#7dd3fc` | the theme accent |
| `--dd-accent-strong` | `#38bdf8` | emphasized accent |
| `--dd-accent-contrast` | `#0b1220` | text on accent fills |
| `--dd-success` | `#4ade80` | good / done |
| `--dd-warning` | `#fbbf24` | caution |
| `--dd-danger` | `#f87171` | errors / critical |
## Chart palette [#chart-palette]
A data-series palette, themable as a set. Use them in order.
| Token | Default |
| -------------- | ------------------ |
| `--dd-chart-1` | `#6ee7a0` (green) |
| `--dd-chart-2` | `#6cb2f7` (blue) |
| `--dd-chart-3` | `#b18af8` (purple) |
| `--dd-chart-4` | `#f5a962` (orange) |
| `--dd-chart-5` | `#5fd4d0` (teal) |
## Font faces [#font-faces]
| Token | Default |
| ------------------- | ------------------------------------------------------------- |
| `--dd-font-sans` | `"Segoe UI Variable Text", "Segoe UI", system-ui, sans-serif` |
| `--dd-font-display` | `var(--dd-font-sans)` |
| `--dd-font-mono` | `"Cascadia Mono", Consolas, monospace` |
`--dd-font-display` is the headline face: themes point it at a character
font while everything else stays sans. The `dd-text` variants `title` and
`value` use it. A widget with a
[manifest font pin](/docs/reference/manifest#fonts) gets these rewritten in
its own documents, and each bundled catalog face also exists as a
convenience var: `--dd-font-audiowide`, `--dd-font-nunito`,
`--dd-font-nunito-sans`, `--dd-font-pixelify-sans`,
`--dd-font-press-start-2p`, `--dd-font-silkscreen`.
## Type scale [#type-scale]
`` maps to these; any widget can override.
| Token | Default |
| -------------------- | ------- |
| `--dd-font-size-xs` | `11px` |
| `--dd-font-size-sm` | `12px` |
| `--dd-font-size-md` | `14px` |
| `--dd-font-size-lg` | `18px` |
| `--dd-font-size-xl` | `24px` |
| `--dd-font-size-2xl` | `32px` |
## Font weights [#font-weights]
`` maps to these.
| Token | Default |
| --------------------------- | ------- |
| `--dd-font-weight-normal` | `400` |
| `--dd-font-weight-medium` | `500` |
| `--dd-font-weight-semibold` | `600` |
| `--dd-font-weight-bold` | `700` |
## Tracking [#tracking]
| Token | Default | Used for |
| -------------------- | -------- | --------------------------------------------------------------- |
| `--dd-tracking-wide` | `0.08em` | uppercase label tracking (the one letter-spacing in the system) |
## Radii [#radii]
| Token | Default | Used for |
| ------------------ | ------- | ----------------- |
| `--dd-radius-sm` | `6px` | small controls |
| `--dd-radius-md` | `10px` | buttons, chips |
| `--dd-radius-lg` | `16px` | panels |
| `--dd-radius-full` | `999px` | pills and circles |
## Spacing [#spacing]
| Token | Default |
| -------------- | ------- |
| `--dd-space-1` | `4px` |
| `--dd-space-2` | `8px` |
| `--dd-space-3` | `12px` |
| `--dd-space-4` | `16px` |
| `--dd-space-6` | `24px` |
There is no `--dd-space-5`; the scale jumps from 16 to 24.
## Elevation and dimming [#elevation-and-dimming]
| Token | Default |
| ------------------ | -------------------------------- |
| `--dd-shadow` | `0 8px 24px rgba(0, 0, 0, 0.35)` |
| `--dd-opacity-dim` | `0.6` |
## Motion [#motion]
Durations plus the house easing (fast start, soft landing). Component
transitions ride these, and themes can retime them. The OS reduced-motion
preference disables the built-in motion regardless.
The user's Animation speed setting (Settings > General: off, fast, normal,
slow) multiplies both durations after the theme, so a theme's retime and the
user's choice compose, and Off makes everything instant. You read the result
through the tokens like any other value; there is nothing to declare.
| Token | Default |
| ---------------- | ---------------------------- |
| `--dd-anim-fast` | `140ms` |
| `--dd-anim-slow` | `260ms` |
| `--dd-ease` | `cubic-bezier(0.2, 0, 0, 1)` |
## Stacking [#stacking]
| Token | Default | Used for |
| --------------- | ------- | ----------------------------------- |
| `--dd-z-popout` | `10` | popouts paint above their neighbors |
## Autoscale [#autoscale]
For widgets whose one big readout should scale with the widget: the target
font size is a fraction of the container's smaller edge, capped at a
maximum. Overridable per widget by setting the vars on any element inside
the container.
| Token | Default |
| --------------------- | --------- |
| `--dd-autoscale-size` | `36cqmin` |
| `--dd-autoscale-max` | `44px` |
## How themes layer [#how-themes-layer]
The host computes the effective map as defaults, then the active theme's
tokens, then the user's own overrides, and broadcasts the result to every
widget document (the `theme.tokens` event; the SDK re-applies it to
`:root`). One more layer is per widget: a user can override any token on a
single widget instance from the Style tab of its settings window, and the
shell merges that map over the effective one for that instance's documents
only. Your widget sees it as a different `var()` value, previews included,
and `dd.theme.tokens()` returns the same merged map. Widgets never read
theme files: the current map is always just `var(--dd-*)` in CSS or
`dd.ui.token()` in JS.
# Bar widgets (/docs/reference/api/bar-widgets)
Some methods exist only for a `kind: "bar"` widget that also holds the
[`taskbar`](/docs/reference/permissions) permission. The bridge refuses the
whole surface for a regular desktop widget before permissions are even read,
so "a desktop widget can never see your open windows" stays a one-line
guarantee.
This page is the reference. [Building a taskbar](/docs/guides/taskbars)
explains what a bar is, what the host does for it, and how to make one.
Most bars never call any of it directly: the
[bar components](/docs/reference/components#dd-apps-and-dd-app)
(``, ``, ``) carry the behavior on
[dd.bar.store](#ddbarstore), and a bar differs in its CSS. The primitives
under them stay public for a bar that draws its own buttons: the strip (the
host-owned order), the windows, the pins, the preview flyout, the tray
mirror, the start-menu tap and the app menu.
Two rules hold everywhere on this page. Every id is an opaque host token: a
stale one rejects with `NOT_FOUND`, and the fix is always to re-list from
the matching stream. A popup anchor is an element (the SDK measures it) or
a rect in the bar document's CSS px; `y` and `h` matter beside a side bar,
where every popup opens to the side of the strip.
A bar has two documents, the strip and its pane, and not every verb serves
both. Bar window only: `dd.bar.flyout.*`, `dd.bar.appMenu`,
`dd.bar.openStartMenu`, `dd.bar.openQuickSettings`,
`dd.bar.openNotifications`, `dd.systray.open` and `close`, `dd.bar.strip.move`,
`dd.popout.open` and the region reporting. Both, under the cursor-inside
gate (the bar window, or the pane and its anchor button), from app 0.3.7:
`dd.settings.open`, `dd.links.open`, `dd.dialogs.pickDesktopItems` and
`dd.power.run`; older apps refuse them from a bar. Both, with no gate: the
streams, `dd.bar.strip.list`, the `dd.windows` reads and `dd.pins.list`.
## Types [#types]
```ts
interface OsWindow {
/** Valid only while the window is in the current list. */
id: string;
title: string;
/** Stable per-app icon key for dd.windows.icons; empty when the host
* could not read the process. */
iconKey: string;
/** The id of the strip row that claims this window (a pin's id, or the
* id of the row a running app got), stamped by the host before either
* list goes out and fixed while the window is listed. Empty only on a
* host older than 0.3.5. */
appKey: string;
focused: boolean;
minimized: boolean;
/** Stable display id of the window's monitor (its restore monitor while
* minimized). The host already cuts the list to what this bar shows, so
* a bar never filters on it. */
displayId: string;
}
interface PinnedApp {
/** The only handle dd.pins.launch accepts; stable across rescans and
* across unpin and re-pin of the same app. */
id: string;
name: string;
/** Equals id: the host stamps it onto every window the pin claims. */
appKey: string;
/** Shares the windows icon space: a pinned and running app is one cache entry. */
iconKey: string;
}
interface StripRow {
/** The row's identity everywhere: the appKey, the iconKey, the id that
* pins.launch and strip.move take. Survives pin, unpin and re-pin. */
id: string;
/** A pin (stays when its windows close) or a transient row (drops a
* moment after its last window closes). */
pinned: boolean;
/** The pin's display name; empty for a transient row (show the window title). */
name: string;
/** Equals id. */
iconKey: string;
}
interface BarEntry {
key: string;
/** The running windows; empty for a launcher. */
wins: OsWindow[];
/** The pin behind the entry; null for an unpinned running app. */
pin: PinnedApp | null;
}
interface BarFlyoutStyle {
/** Preview width in CSS px, 120 to 320; height follows 16:9. */
previewW?: number;
/** Panel corner radius in px, 0 to 24. */
radius?: number;
/** Gap between cards in px, 0 to 24. */
gap?: number;
/** Panel background, #rrggbb or #rrggbbaa only. */
surface?: string;
/** Panel border color, #rrggbb or #rrggbbaa only. */
border?: string;
showTitle?: boolean;
showClose?: boolean;
}
/** A popup anchor by hand: CSS px of the bar viewport. */
type BarAnchor = { x: number; y?: number; w: number; h?: number };
```
One key ties the three lists together. A strip row's `id` is the `appKey`
the host stamps onto every window the row claims, the `iconKey` for
[dd.windows.icons](#ddwindowsicons), the id [dd.pins.launch](#ddpinslaunch)
takes for a pinned row, and the id [dd.bar.strip.move](#ddbarstripmove)
takes. Attaching windows to rows is a plain equality, and a bar never keeps
an order of its own.
## dd.bar.store [#ddbarstore]
```ts
dd.bar.store(): BarStore
```
The headless taskbar state, one lazy instance per bar document. Signals
(`dd.ui.signal`, read `.value` inside an `effect`, `.peek()` outside):
`strip` (the host's ordered rows, see [dd.bar.strip](#ddbarstrip)) and
`windows` (the host snapshots), `pins` (the pinned rows as `PinnedApp`, a
projection of the strip), `entries` (the render list: the strip with the
windows attached, one entry per row that has something to show, in strip
order, or in the local order during a drag or a move in flight), `flyout`
(`{ open, key }`, from `bar.flyout.changed` only), `pinsEnabled`,
`sorting`, `lowMotion` (low-spec host or reduced motion), `edge`; per key,
`icon(iconKey)` (the data URI, fetched in batches on first read; a key the
host has no icon for stays `undefined` and is never asked again) and
`launching(key)`. `entryByKey(key)` returns the entry behind a key, or
`undefined`. `ready` resolves after the seed (the strip first, then the
windows), with every listener already registered.
Actions: `activate(key, anchorEl)` is the click tree (a launcher launches
once, behind a lock that holds until its window lands or 6 s; a single
window focuses, or minimizes when it is the focused one; a stack toggles the
preview flyout anchored on the element), with `launch`, `openFlyout`,
`closeFlyout` and `toggleFlyout` as its pieces; `hoverEnter(key, el)` and
`hoverLeave()` run the hover dwell when `configure({ previews: "hover" })`
is set (a sweep opens nothing, a switch while open waits the same dwell,
leaving a button closes nothing); `pointerEntered()` and `pointerLeft()`
are the debounced advisory close for the bar segment; `enablePins(bool)` is
the pins gate (whether pinned launchers render; the host keeps its pins
either way); `beginSort(key)`, `previewOrder(keys)`, `move(key, before)`
and `endSort()` are a drag's four moments (the flyout closes and hover
pauses at `beginSort`, `previewOrder` keeps the pointer's order across host
emits, `move` shows the drop at once and sends `bar.strip.move`, the host's
next emit confirms it or a rejection rolls it back within a second,
`endSort` is a release without a move); `setFlyoutStyle` sets the style
every open sends; `menuSubject(entry)` is the app-menu subject.
`configure(opts)` takes `previews` (`"click"`, the default, or `"hover"`),
`dwell` (ms of continuous hover before a preview opens, default 400) and
`flyoutStyle`. `hooks` is the seam the components use to raise their
cancelable events; leave it alone.
The `` / `` / `` components render from it
and hold no behavior of their own. A bar that draws its own buttons reads
and calls the same thing.
## dd.bar.strip [#ddbarstrip]
The strip (app 0.3.5+; the store sets `minAppVersion`) is the
host-owned order of the taskbar: ONE list of rows, where a row is a pinned
app or a running app nobody pinned, the same for every bar on every
display. Which rows show still follows each bar's own window list: when
the user shows taskbar apps only where the window is open, a running row
appears only on the bars that list its windows, and pinned rows appear on
every bar. It is the user's order. Pins keep their place across restarts
(they live in the app config); running rows keep theirs while they run and
append at the end when they first appear, exactly like the Windows taskbar.
Pin and unpin happen in place: a running app keeps its slot when the user
pins it, a pinned app keeps its slot when unpinned while it runs, and an
unpin with no window drops the row.
Every window in `dd.windows.list` carries its row's id as `appKey`, stamped
by the host before either list goes out, so attaching windows to rows is a
plain equality and a bar never keeps an order of its own.
### dd.bar.strip.list() [#ddbarstriplist]
```ts
dd.bar.strip.list(): Promise<{ items: StripRow[] }>
```
The rows in strip order. Seed with this, then follow `onChanged`. A row
with `pinned: false` and no window in the window list is in the host's
short grace after its last window closed (its id stays valid for a
relaunch): render nothing for it. A bar's pane may call this too.
### dd.bar.strip.move() [#ddbarstripmove]
```ts
dd.bar.strip.move(id: string, before: string | null): Promise
```
Moves row `id` in front of row `before`, or to the end of the strip when
`before` is `null`. Any row goes to any slot: a running app between two
pins, a pin after a running app. This is the one write a bar has into
host-owned state, so it is gated like the app menu: the bar document only
(never a pane), never in edit mode, and only while the cursor is over the
bar (a drop lands under it). Only host-issued ids cross; a stale `id` or
`before` rejects with `NOT_FOUND` (re-list on `onChanged`). The result comes
back through `onChanged` to every bar, and through `dd.pins.onChanged` when
the pinned order changed. The store does this for you: ``
turns a drag into `move`, with the drop shown at once and the stream
confirming it.
### dd.bar.strip.onChanged() [#ddbarstriponchanged]
```ts
dd.bar.strip.onChanged(cb: (p: { items: StripRow[] }) => void): () => void
```
Change-driven full snapshot: a row added (an app nobody pinned opened its
first window) or dropped (its grace ran out), a pin made or removed, a move
(yours or another bar's, on any display). Attaching windows to rows never
emits here; `dd.windows.onChanged` carries that. Reaches a bar's pane too.
## dd.bar.entries [#ddbarentries]
```ts
dd.bar.entries(windows: OsWindow[], pins: PinnedApp[]): BarEntry[]
```
The pure two-list merge, for a bar that reads `dd.windows` and `dd.pins`
itself: pins first in pin order, each merged with its running group when
the host stamped the pin's id onto the windows (`appKey` equality), a
launcher otherwise; then the unpinned running groups in the host's
first-seen order. Windows without an `appKey` stay their own entry. A merged
entry and its launcher share one key, so one DOM node can carry launcher,
running, launcher across a launch and a quit. It carries no user order:
the store's `entries` signal renders from the strip instead. The shapes are
in [Types](#types).
## dd.windows [#ddwindows]
The open top-level OS windows. Needs `taskbar` on a bar-kind widget; a
regular widget's call is refused before its permissions are read.
### dd.windows.list() [#ddwindowslist]
```ts
dd.windows.list(): Promise<{ windows: OsWindow[] }>
```
Every open top-level window, unstacked, in first-seen order: the order is
stable across focus changes and new windows append, so the list never
leaks z-order and buttons never jump. Each window's `appKey` is the id of
the strip row that claims it (by AppUserModelID when the window carries
one, else by exe; every UWP window shares one host process, which is why
exe alone would misgroup them). A new window is held out of the list for
up to about 300 ms while that identity resolves, so the key never changes
under a listed window. Seed with this, then follow `onChanged`. The store's
`entries` signal is this list attached to the strip.
The list is already cut to what this bar shows (app 0.3.11+). In
**Settings, Taskbar**, **Show taskbar apps on** offers the three Windows
modes: every bar lists every window (the default), each bar lists only
the windows on its own display, or the primary display's bar lists every
window and the others only their own. `windows.list` and `onChanged` both
follow that choice, so a bar needs no code for it.
### dd.windows.focus() [#ddwindowsfocus]
```ts
dd.windows.focus(id: string): Promise
```
Restores the window if it is minimized, then asks Windows for the
foreground. Fire and forget: a refused foreground attempt still resolves
and is only logged host-side (the OS foreground lock; an elevated window,
where the host falls back to the Alt-Tab switch path, which works). Drive
your focus indicator from `onChanged`, never from the click, and a refusal
can never desync it.
### dd.windows.minimize() [#ddwindowsminimize]
```ts
dd.windows.minimize(id: string): Promise
```
Minimizes the window; the indicator update arrives through `onChanged`
when focus moves. Windows refuses the request for an elevated window (Task
Manager, an elevated terminal) and the click then does nothing. That is
not a trap: such a window can only be minimized from its own caption, and
the next click on its button restores it through `focus`.
### dd.windows.icons() [#ddwindowsicons]
```ts
dd.windows.icons(keys: string[]): Promise<{ icons: Record }>
```
Icon PNG data URIs (up to 96 px) for up to 64 `iconKey`s from the current
list, extracted on demand and cached per app for the session. Keys the
host cannot resolve are simply absent: keep a glyph fallback and do not ask
again (the miss is cached too). Icons are never inlined in the list or the
stream, so cache by `iconKey` and fetch only unseen keys; the store's
`icon(iconKey)` signal does exactly that, in batches.
### dd.windows.onChanged() [#ddwindowsonchanged]
```ts
dd.windows.onChanged(cb: (p: { windows: OsWindow[] }) => void): () => void
```
Change-driven full snapshot: a window opened or closed, focus moved, a
title changed, minimize state flipped, a window changed monitors. It is
cut to this bar's windows the same way `list()` is. Nothing fires at a
fixed rate and there is nothing to poll. This is the driver for
a taskbar's focus indicator and button row.
## dd.pins [#ddpins]
DeskDash's own pinned apps: one host-owned list, kept in the app config and
shared by every bar widget, so switching bars, reloading or reinstalling a
bar never changes it. Pins are made and removed through the host's
[app menu](#ddbarappmenu), never by a widget, and moved through
[dd.bar.strip.move](#ddbarstripmove). On the first run the host imports the
Windows taskbar's own pins once, read-only. Same gate as `dd.windows`.
### dd.pins.list() [#ddpinslist]
```ts
dd.pins.list(): Promise<{ pins: PinnedApp[] }>
```
The pins in pin order: the pinned rows of the strip, in strip order. A
pin's `appKey` is its `id`, stamped onto every window it claims before the
window list goes out, so a pin and its running windows share one key from
the first frame either exists.
### dd.pins.launch() [#ddpinslaunch]
```ts
dd.pins.launch(id: string): Promise
```
Launches the pinned app through the host's own launcher for it (a packaged
app's AppsFolder entry, the app's Start menu shortcut, or its exe; nothing
crosses the bridge). The app opens on the display of the bar that called
it (app 0.3.11+): the launch carries a hint for that display, and when a
bar runs on every display, a new window of the app that opens elsewhere
within about 10 seconds moves there, keeping its size. Windows that stay
where they open: one the app already showed and raised in answer to the
launch, one on the display under the mouse (a tab the user tears off),
and one that covers its whole monitor (a fullscreen game).
The window it opens arrives already carrying this
pin's `appKey`, so it merges on the `dd.windows.onChanged` that announces
it. Always a new-instance request: correlate running windows through
`appKey` and decide yourself whether a running pin's click should focus
instead (the store does). Rejects `NOT_FOUND` for a stale id and for a pin
whose launcher and exe are both gone; a launch the OS refuses rejects
`INTERNAL`. Rate limited to 5 launches per 10 seconds.
### dd.pins.onChanged() [#ddpinsonchanged]
```ts
dd.pins.onChanged(cb: (p: { pins: PinnedApp[] }) => void): () => void
```
Change-driven full snapshot: fires only when the pin list itself changed,
a pin made or removed from the app menu, or the pinned order moved. A pin's
`appKey` is fixed, so launching or quitting an app never emits here;
`dd.windows.onChanged` carries that.
## dd.bar.flyout [#ddbarflyout]
The host-drawn preview flyout: window titles, live snapshot previews and a
close button per card, for one app group at a time. You decide when and for
which group; the host does everything else: where it goes, what it shows,
when it closes. Bar document only (a pane cannot open it). The store and
`` drive it for you (`previews="click"` or `"hover"`); the methods
below are the surface underneath.
### dd.bar.flyout.open() [#ddbarflyoutopen]
```ts
dd.bar.flyout.open(opts: {
key: string; // your group tag, up to 64 chars; echoed on onChanged
windowIds: string[]; // 1 to 32 ids from the current window list
anchor: Element | BarAnchor;
style?: BarFlyoutStyle;
}): Promise
```
Opens the flyout for a group, or retargets it while open (the instant
switch, no flicker). Stale ids are pruned silently and a fully stale group
just closes. The flyout centers on the anchor beside the strip (above a
bottom bar, to the side of a left or right bar), clamped to the display,
up to 8 cards. `style` is the curated author styling: every knob defaults
to the active theme's tokens, and colors are hex only, never a CSS
expression.
Fire and forget: the content builds host-side, so drive your hover machine
from `onChanged`, never from this promise. A click on a card focuses its
window (restores it if minimized, never minimizes) and closes the flyout;
the card's X posts a graceful close request to the app, which may prompt
to save.
What a card shows. Previews are snapshots the host takes from the window,
refreshed about once a second while the flyout is open. A card falls back
to the app's icon tile when there is nothing to capture: a minimized
window, a window that draws straight to the GPU (games, some browsers and
players), or an elevated window, which refuses capture. None of that is
yours to fix; design the icon tile to look intended.
### dd.bar.flyout.close() [#ddbarflyoutclose]
```ts
dd.bar.flyout.close(): Promise
```
Advisory close, meant for pointer-leave: the host holds a short grace
(about 300 ms, so the pointer can cross to the panel) and ignores it while
the cursor is inside the flyout itself, whose own leave then closes it. The
host also force-closes on its own: edit mode, a reload, a fullscreen app,
the app menu or a pane opening, the bar going away or crashing, an emptied
group, and a no-hover backstop of about 10 seconds. A stranded flyout is
never the author's problem.
### dd.bar.flyout.onChanged() [#ddbarflyoutonchanged]
```ts
dd.bar.flyout.onChanged(cb: (p: { open: boolean; key: string | null }) => void): () => void
```
The flyout's real state, on every open, switch and close, whoever caused
it. `key` echoes the tag from `open` and is `null` once closed. This is the
only truth for open state and the driver for switch-while-open hover
behavior; never assume the state from your own calls.
## dd.systray [#ddsystray]
The Windows notification area ("system tray"), mirrored by the host so a bar
can offer it back once DeskDash replaces the native taskbar. You get a count,
never the icons: the rows, and the clicks that reach those apps, live in a
host-drawn window that no widget can read or script.
What that list shows, so you can explain it to your users: every app's
tray icon, including the ones an app marked hidden (dimmed, because once
the native taskbar is gone this list is the only way to reach them), and
DeskDash's own icon; Windows' own volume, network and battery icons stay
with Windows and are not listed. Rows carry the app's tooltip or its
process name, sorted by name, twelve at a time with the rest scrolling.
The easiest way to use it is the [``](/docs/reference/components#dd-tray-caret)
component with the `systray` setting preset; the methods below are the surface
underneath it.
### dd.systray.subscribe() [#ddsystraysubscribe]
```ts
dd.systray.subscribe(): Promise<{ count: number }>
```
Arms the host reader (the first call only, so a bar that never shows the tray
costs nothing) and returns the count of shown icons. Seed a caret's
visibility from the count, then follow `systray.changed`.
### dd.systray.open() [#ddsystrayopen]
```ts
dd.systray.open(anchor: Element | BarAnchor): Promise
```
Opens the host-drawn tray list, anchored on your caret. Pass the element and
the SDK measures it. The host owns the list's size, position, dismissal and
every click inside it. Fire and forget: follow `systray.changed`, not this
promise.
### dd.systray.close() [#ddsystrayclose]
```ts
dd.systray.close(): Promise
```
Advisory close (your caret toggled off). The host also closes on its own: an
outside press, Escape, a left click on a row, or the bar going away. A
right-click on a row keeps the list open so the app's own menu can sit over
it, the way the Windows tray overflow does.
### dd.systray.onChanged() [#ddsystrayonchanged]
```ts
dd.systray.onChanged(cb: (p: { count: number; open: boolean }) => void): () => void
```
Fires on every tray change and every open or close of the list, whoever
caused it. This is the correct driver for a caret's pressed look: the host
closes the list on its own, so follow this, never your own guess. From app
0.4.2, `open` is true only on the bar whose caret opened the list, and the
list also closes when the bar ducks for a fullscreen app, in edit mode, and
when the bar goes away.
## dd.notificationCenter [#ddnotificationcenter]
The Windows notification center, drawn by the host the way the tray list
is, so a bar can offer it once DeskDash replaces the native taskbar. You get
a count and states, never the notifications: their text, pictures and
buttons, and every click on them, live in a host-drawn window that no
widget can read or script. That is also why it needs no permission of its
own beyond `taskbar`, and why a bar can show notifications next to anything
else it does, weather included. App 0.4.2 or newer.
What the window shows, so you can explain it to your users: other apps'
notifications, newest first, grouped by app with the app's icon and a clear
button, each with its sender picture, title, time, text and pictures, and
its buttons (reply boxes, snooze and right-click entries are left out). A
click on one does what a click in Windows does: the app opens, or jumps to
the message when it registered for that, and the window closes. Dismiss,
clear and Clear all remove notifications from Windows too. When Windows
refuses access (its own privacy switch for notifications), the window says
so and links to the settings page, with a way to open Windows' own center
instead.
The easiest way to use it is the
[``](/docs/reference/components#dd-notification-bell)
component, optionally with the `notificationCenter` setting preset; the
methods below are the surface underneath it.
### dd.notificationCenter.subscribe() [#ddnotificationcentersubscribe]
```ts
dd.notificationCenter.subscribe(): Promise<{
count: number; // notifications in Windows now
open: boolean; // the window is open from THIS bar
dnd: "off" | "priority" | "alarms" | null; // Windows' Do not disturb mode
access: "allowed" | "denied" | "unspecified" | "unavailable";
}>
```
Arms the host reader (the first call only; it lists Windows' notifications
every second from then on, so a bar without a bell reads nothing) and
returns the state, fresh. `access` is `"denied"` when the user's privacy
switch is off, `"unspecified"` when Windows has not decided, `"unavailable"`
when the Windows API failed; the window explains each, so a bell can simply
open it.
### dd.notificationCenter.open() [#ddnotificationcenteropen]
```ts
dd.notificationCenter.open(anchor: Element | BarAnchor): Promise
```
Opens the host's notification center beside your bell. The host reads
Windows first, then owns the window's size (its content, up to the room
beside the bar), position, dismissal and every click inside it. Fire and
forget: follow `notificationCenter.changed`, not this promise.
### dd.notificationCenter.close() [#ddnotificationcenterclose]
```ts
dd.notificationCenter.close(): Promise
```
Advisory close (your bell toggled off). The host also closes on its own: an
outside press, Escape, a click that opened an app, the bar ducking for a
fullscreen app, edit mode, or the bar going away.
### dd.notificationCenter.onChanged() [#ddnotificationcenteronchanged]
```ts
dd.notificationCenter.onChanged(
cb: (state: { count: number; open: boolean; dnd: string | null; access: string }) => void,
): () => void
```
Fires on every change of the count, the access or the mode, and every open
or close of the window, whoever caused it. The correct driver for a bell's
pressed look and badge.
## dd.bar.openStartMenu [#ddbaropenstartmenu]
```ts
dd.bar.openStartMenu(): Promise
```
Opens the Windows start menu (the host taps the Windows key). A second call
while it is open toggles it closed, the native behavior. There is no
documented API for the menu itself, so the tap is a no-op on the secure
desktop or while a held modifier turns it into a chord. Fire and forget:
there is no menu state to follow.
## dd.bar.openQuickSettings [#ddbaropenquicksettings]
```ts
dd.bar.openQuickSettings(): Promise
```
Opens Windows' own Quick Settings: Wi-Fi, Bluetooth, the sound output
device, Night light and every other toggle a hidden taskbar takes away (the
host sends Win+A). A second call while it is open toggles it closed.
Windows places it in the bottom right corner, not beside your button. Call
it from a click: the host refuses it in edit mode and while the cursor is
off the bar window, and logs the refusal. Fire and forget: the host cannot
see when the menu closes. 5 calls per rolling 10 seconds. App 0.4.2 or
newer.
## dd.bar.openNotifications [#ddbaropennotifications]
```ts
dd.bar.openNotifications(): Promise
```
Opens Windows' notification center with its calendar (the host sends
Win+N), with the same placement, click rule and rate limit as
`dd.bar.openQuickSettings`. App 0.4.2 or newer. For a notification center
beside your own bar, use [dd.notificationCenter](#ddnotificationcenter)
instead.
## dd.bar.appMenu [#ddbarappmenu]
```ts
dd.bar.appMenu(opts: {
appKey?: string; // exactly one of the three
windowId?: string;
pinId?: string;
anchor: Element | BarAnchor;
}): Promise
```
Opens the host-drawn per-app context menu above the bar for one subject:
a merged group by its `appKey`, a single window by its id (for a window
without an appKey), or a pin by its id (for a pin without one). The menu
shows the app's name (launches a new instance), **Pin to taskbar** or
**Unpin from taskbar**, and **Close window** (or **Close all windows** for
a group with several). Pins live in the DeskDash config, one list for
every bar widget (switching bars never resets it), and every change comes
back through `dd.bar.strip.onChanged` and `dd.pins.onChanged`. Pin and
unpin happen in place on the strip: the app keeps its slot.
A pin's `appKey` is its own id, the id of its strip row, and the host stamps
that same token onto every window the pin claims before it hands you the
window list. So a pin and its running windows always share one key, from
the first frame either exists, and a group key, a pin id and a strip row id
are the same token.
You rarely call this yourself. `` tags itself; by hand, tag each
app button with the subject and the SDK's right-click handler does it for
you:
```html
```
Re-stamp the tag on every render (ids move as windows come and go). An
element whose own `contextmenu` handler calls `preventDefault()` before the
SDK's handler keeps the right-click; untagged space raises
[the bar's own menu](#the-bars-own-menu).
Trust model: you only say which app was right-clicked. Launch, pin, unpin
and close run host-side from clicks inside the host's own menu window, so
the method grants a widget nothing beyond opening the menu, and the
`taskbar` permission stays a read grant. Honored only while the cursor is
over the bar and never in edit mode; the host closes the menu on Escape, an
outside click, an action, or when the subject disappears. Fire and forget.
## The bar's own menu [#the-bars-own-menu]
A right-click on untagged space in the bar document raises the host's
native menu for the bar itself: **Change taskbar...** (the marketplace's
Taskbars section, the one place a bar is swapped), **Taskbar settings...**
(the bar's own settings dialog, with the Placement group first),
**Settings...**, **Edit layout** and **Quit DeskDash**. Quit lives here on
purpose: while the native taskbar is replaced, the notification area is
hidden with it, so the bar's menu is the one always-reachable way out, and
a clean quit is also what brings the Windows taskbar back. The SDK forwards
the right-click and suppresses the WebView's default menu; the request
underneath (`bar.menu`) is bar-window-only and you never need to call it.
# Core runtime (/docs/reference/api/core)
Every widget document gets one global, `dd`. The SDK script creates it:
```html
```
On load the SDK connects your document to the host, applies the design tokens
to `:root`, and resolves `dd.ready` once the host has answered. Everything a
widget can do (read settings, fetch data, stream system state) goes through
`dd`; there is no other door to the system.
## dd.ready [#ddready]
The init context, resolved once per document.
```ts
dd.ready: Promise
interface DdContext {
/** Per instance; a taskbar document (and its pane) carries the
* sentinel "__bar" on every display. */
instanceId: string;
/** "main" = the widget document; "pane" = a popout pane document;
* "bar" = the taskbar surface. Same grants either way. */
role: "main" | "pane" | "bar";
widget: { id: string; version: string };
/** What the user granted: every permission key, plus http.hosts and
* links.prefixes. Mirrors the manifest after install-time consent. */
grants: DdGrants;
/** The manifest's interactive flag. Always false for panes. */
interactive: boolean;
/** Manifest defaults merged with the user's stored values. */
settings: Record;
/** The current --dd-* token map. The SDK applies it for you. */
tokens: Record;
/** Bridge API info: feature-detect against version; deprecated maps a
* method name to its deprecation note. */
api?: { version: number; minSupported: number; deprecated: Record };
/** Static for the whole app run; absent on older hosts (treat as off). */
perf?: { lowSpec: boolean };
/** Pane documents only: the applied side and the data open() passed. */
popout?: { side: "down" | "up" | "left" | "right"; data: unknown };
/** Bar documents (and a bar's pane): the screen edge the bar window
* docks to. Absent on hosts older than this field: treat as "bottom". */
bar?: { edge: "bottom" | "left" | "right" };
}
```
Notes:
* `perf.lowSpec` is true when the user enabled low performance mode. It never
changes mid-run, so read it once. Widgets that animate should cap their draw
loop around 30 fps and their canvas backing store at 1x `devicePixelRatio`;
the host already lowers its own side (spectrum frames arrive at 20 Hz
instead of 30).
* A pane document (see
[popouts](/docs/reference/api/widgets-together)) boots the SDK exactly like
the main document and carries the same instance identity and grants.
* A bar document (see [bar widgets](/docs/reference/api/bar-widgets) and
[building a taskbar](/docs/guides/taskbars)) has `role: "bar"`, real
mouse input until it reports segments, no grid-style popouts (its pane
opens beside the strip) and `bar.edge` set; `interactive` is always
false for it.
## dd.request() [#ddrequest]
The low-level escape hatch. Every namespaced method wraps it; call it directly
only for something the typed surface does not cover.
```ts
dd.request(method: string, params?: unknown, timeoutMs?: number): Promise
```
Requests reject with an `Error` carrying a `code`:
```ts
interface DdError extends Error {
code: string; // "PERMISSION_DENIED", "RATE_LIMITED", ...
}
```
The full code list is on
[Errors and versioning](/docs/reference/errors-versioning). The client rejects
with `TIMEOUT` after 15 seconds by default; `timeoutMs: 0` disables the client
timer (the dialog pickers use this, since they wait on the user).
## dd.poll() [#ddpoll]
The polling loop widgets keep re-implementing: an interval, error backoff,
staleness so a settings-driven refresh cancels the in-flight cycle, and the
settings trigger itself.
```ts
dd.poll(opts: PollOptions): PollHandle
interface PollOptions {
/** Do the work; return the data (or throw to trigger onError + backoff). */
fetch: () => Promise;
onData: (data: T) => void;
onError?: (err: unknown) => void;
/** Milliseconds until the next poll after a success: a number, or a getter
* read each cycle so it can follow a live setting. */
every: number | (() => number);
/** Exponential backoff from 1s on error, capped at every (default true). */
backoff?: boolean;
/** Setting keys whose VALUE changing should re-poll, coalesced over
* refreshDebounceMs. Keys left out never cost a request. */
refreshOn?: string[];
/** How long the watched keys must rest before the re-poll (default 400ms). */
refreshDebounceMs?: number;
}
interface PollHandle {
/** Cancel any in-flight or scheduled cycle and poll now. */
refresh: () => void;
stop: () => void;
}
```
Polling starts immediately. The usual wiring, with `refreshOn` naming the
settings the fetch actually reads:
```js
dd.settings.bind((next) => {
settings = next; // repaint on every change
});
dd.poll({
fetch: () => fetchForecast(settings),
onData: render,
every: () => Number(settings.refreshMinutes) * 60_000,
refreshOn: ["city", "units", "refreshMinutes"],
});
```
**Do not call `refresh()` from a settings callback.** The dialog live-previews
your settings as the user types, one change per keystroke, so that version
re-fetches once per CHARACTER: a nine-letter city name is nine requests, and
`dd.http.fetch` allows 30 a minute. `refreshOn` coalesces the burst into one
poll once the values rest, and a setting you leave out of the list, a panel
restyle for instance, costs nothing at all.
`refresh()` stays for the cases it suits: a manual reload button, or a retry
after the user fixes something.
## dd.log() [#ddlog]
```ts
dd.log(level: "debug" | "info" | "warn" | "error", ...args: unknown[]): void
```
Writes to the host's log, tagged with your widget and instance id. Uncaught
errors and unhandled rejections in your document are forwarded there
automatically, so the host log is the first place to look when a widget
misbehaves.
The host sanitizes forwarded text before writing it: URL query strings are
replaced with `?...`, home-directory paths collapse to `~`, and each line is
capped at 8 KB. Users share their log file for support, so nothing a widget
logs should be able to leak a token or a username. Log identifiers and state,
not raw URLs or file paths.
## dd.links.open() [#ddlinksopen]
The one way out of the widget: open something with the OS default handler.
```ts
dd.links.open(url: string): Promise
```
Needs the `links` permission, and `url` must start with one of the manifest's
`links.prefixes` entries (each a full `scheme://...` string, like
`steam://run/` or `https://github.com/`). Dangerous schemes (`file`,
`javascript`, `data`, and friends) are refused regardless of what a manifest
declares. Honored only while the real cursor is inside the widget (call it
from a click handler; for a bar, the bar window or its pane, app 0.3.7 or
newer) and never in edit mode. 5 calls per rolling 10 seconds.
A feed reader needs no `links` grant for its headlines:
[dd.feeds.open](/docs/reference/api/data-services#ddfeedsopen) opens the item
links of the user's own feed.
## How permission gating works [#how-permission-gating-works]
The host checks permissions before a method dispatches. Most methods map to
the permission named by their prefix:
| Prefix | Needs |
| ----------------------------------- | ---------------------------------------------------------- |
| `settings.*`, `theme.*`, `widget.*` | nothing, always available |
| `time.*` | `time` |
| `storage.*` | `storage` |
| `files.*` | `files` |
| `notify.*` | `notifications` |
| `http.*` | `http`, with the exact host allowlisted |
| `links.*` | `links`, with a matching prefix |
| `desktop.*` | `desktop` |
| `folders.*` | `folders` |
| `apps.*` | `systemApps` |
| `games.*` | `games` |
| `launchers.*` | `launchers` |
| `feeds.*` | `feeds` |
| `system.*` reads | `system` |
| `system.*` writes | `system` + `systemControls` |
| `media.*` reads | `media` |
| `media.*` controls | `media` + `mediaControls` |
| `audio.*` | `audio` |
| `widgets.*` | `control` |
| `peers.*` | `peers` |
| `claudeUsage.*` | `claudeUsage` |
| `power.*` | `power` |
| `dialogs.pickDesktopItems` | `desktop` |
| `dialogs.pickFolderItems` | `folders` |
| `popout.*` | a manifest `popout` block (a capability, not a permission) |
| `input.*` | the manifest `interactive` flag (SDK-managed) |
A call without its grant rejects `PERMISSION_DENIED`. See the
[permissions reference](/docs/reference/permissions) for what each grant
means to the user.
Rules that apply everywhere:
* Every `on*` subscription returns an unsubscribe function.
* Rate limits are per instance over a rolling 10 second window unless a
method says otherwise; exceeding one rejects `RATE_LIMITED`.
* Serialized request params are capped at 256 KB.
## How the connection works [#how-the-connection-works]
Widget documents run in sandboxed iframes with an opaque origin. On load the
SDK performs a small handshake with the host and receives a dedicated message
port plus the init context; all further traffic flows over that port, and the
host ties every message to the frame it physically arrived from. None of this
is your concern day to day: the `dd` namespaces are the whole surface, and
nothing a widget puts inside a message can change which widget the host
believes it is talking to.
# Data services (/docs/reference/api/data-services)
## dd.http [#ddhttp]
Needs the `http` permission with the exact hostname allowlisted in the
manifest (`permissions.http.hosts`). All traffic goes through the host's
proxy; widgets have no direct network access at all.
### dd.http.fetch() [#ddhttpfetch]
```ts
dd.http.fetch(req: {
url: string;
method?: string; // GET (default), POST, PUT, PATCH, DELETE, HEAD
headers?: Record;
/** Extra query params merged into the URL host-side after allowlist
* validation. Values may be { $secret: name } like headers. */
query?: Record;
body?: string;
/** "dataUrl" returns the raw response bytes as a base64 data: URL
* (bodyText/json omitted), for images. Default "text". */
as?: "text" | "dataUrl";
}): Promise<{
status: number;
headers: Record;
bodyText?: string;
json?: unknown; // parsed when the response is JSON
dataUrl?: string;
}>
```
The rules, all enforced host-side:
* **Hosts.** The URL's hostname must exactly match an entry in
`permissions.http.hosts`. `https` only (`http` allowed for localhost).
Redirects are followed up to 4 hops, each hop re-validated against the
allowlist.
* **Methods.** `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`. Headers that
would let a widget impersonate the browser session (`host`, `cookie`,
`origin`, `referer`, connection-control headers) are refused; the response
exposes a small safe set (`content-type`, `content-length`, `date`,
`cache-control`, `etag`, `last-modified`).
* **Secrets.** A header or query value of `{ "$secret": "settingKey" }` names
one of this widget's `secretRef` settings; the host injects the user's
stored value after validation. The resolved value (and the merged URL)
never appears in widget JS, logs, or error messages, and secret query
params are never re-appended across redirects.
* **Sizes and pacing.** Request body up to 256 KB; response up to 1 MB;
query up to 32 pairs (keys 128 bytes, values 2048 bytes, final URL 8 KB);
30 second timeout; 2 concurrent requests per instance; 30 requests per
minute by default, raised by the manifest's `http.rateLimit` up to 120.
* **Binary.** `as: "dataUrl"` returns the bytes as a base64 `data:` URL
(same 1 MB cap). The widget CSP allows `img-src data:`, so the result can
feed an `img` or `dd-icon` directly.
```js
const res = await dd.http.fetch({
url: "https://api.example.com/v1/status",
headers: { authorization: { $secret: "apiKey" } },
});
if (res.status === 200) render(res.json);
```
## dd.feeds [#ddfeeds]
Needs the `feeds` permission (app 0.3.9+, and 0.3.11+ for
`dd.feeds.open`; the store sets `minAppVersion`). Reads a news feed from the web address the user typed into
one of the widget's `url` settings, and opens its items in the browser. The
host fetches and parses the feed and hands back only the parsed items, never
the response, so the grant cannot fetch anything else.
### dd.feeds.fetch() [#ddfeedsfetch]
```ts
dd.feeds.fetch(opts: { settingKey: string }): Promise
interface FeedResult {
/** The feed's own title (at most 120 characters), or null. */
title: string | null;
/** Up to 50 items, in the order the feed lists them. */
items: FeedItem[];
/** When the host last downloaded this feed (epoch ms). */
fetchedAtMs: number;
}
interface FeedItem {
/** Plain text on one line: tags removed, entities decoded, at most 300
* characters. Items without a title never arrive. */
title: string;
/** An absolute http(s) address of at most 1024 bytes, or null. Open it
* with dd.feeds.open. */
link: string | null;
/** The published time, else the updated time, in epoch ms; or null. */
publishedMs: number | null;
}
```
`settingKey` names one of this widget's `url` settings. A `url` field never
inherits its manifest default, so the widget shows a setup state until the
user types an address; put an example in the field's `placeholder`. RSS 0.9,
1.0 and 2.0, Atom and JSON Feed all work.
The rules, all enforced host-side:
* **Address.** `https` only (`http` allowed for localhost). Redirects are
followed up to 4 hops, each held to the same rule, and a hop from a public
address into loopback or a private network is refused.
* **Cache.** One cache per address, shared by every widget that reads it. A
call within 5 minutes of a download answers from memory; a later one
revalidates with the ETag and Last-Modified the server sent.
* **Output.** Only titles, links and dates cross the bridge. Put titles on
screen with `textContent`, and open links with
[dd.feeds.open](#ddfeedsopen), which needs no `links` grant.
* **Errors.** `NOT_FOUND` while the setting is blank or when the feed is gone
(404 or 410); `INVALID_PARAMS` for an address that is not https;
`PERMISSION_DENIED` when `settingKey` is not a `url` field; `INTERNAL` when
the page is not a feed or the server fails. No error carries the address.
* **Sizes and pacing.** Response up to 1 MB, 30 second timeout; 10 calls per
rolling 10 seconds.
```js
dd.poll({
every: 15 * 60_000,
refreshOn: ["feedUrl"],
fetch: () => dd.feeds.fetch({ settingKey: "feedUrl" }),
onData: (feed) => render(feed.items),
onError: (err) => (err.code === "NOT_FOUND" ? showSetup() : showStale()),
});
```
### dd.feeds.open() [#ddfeedsopen]
```ts
dd.feeds.open(opts: { settingKey: string; link: string }): Promise
```
App 0.3.11+. Opens an item `link` from
`dd.feeds.fetch` in the default browser. The widget needs no `links` grant:
the host opens only a link it parsed out of the feed at the address the user
typed into that same `url` setting, so a widget can never pick another page.
* **Which links.** The items of the newest answer for that address, plus
those of earlier answers, up to 200 links. A headline that is still on
screen after a refresh still opens. When the host no longer holds the
address in its cache, the call reads the feed once before it decides.
* **Gesture.** Honored only while the real cursor is inside the widget, and
never in edit mode. Call it from a click handler.
* **Errors.** `NOT_FOUND` when the link is in none of those answers (the
headline left the feed); `PERMISSION_DENIED` outside a click; plus the
`dd.feeds.fetch` errors for the setting.
* **Pacing.** 5 calls per rolling 10 seconds.
```js
strip.addEventListener("click", (event) => {
const item = event.target.closest("[data-link]");
if (!item) return;
dd.feeds
.open({ settingKey: "feedUrl", link: item.dataset.link })
.catch((err) => dd.log("warn", "headline open failed", err.code));
});
```
## dd.weather [#ddweather]
The shared weather stack, built on Open-Meteo. Convenience code, not a
capability: everything routes through this widget's own grants. `geocode`
needs `geocoding-api.open-meteo.com` in `http.hosts`, `current` and
`forecast` need `api.open-meteo.com`, and the geocode cache uses your
`storage` grant.
### dd.weather.describe() [#ddweatherdescribe]
```ts
dd.weather.describe(code: number, isDay: number | boolean): {
label: string;
glyph: WeatherGlyph;
}
type WeatherGlyph =
| "clearDay" | "clearNight" | "partlyDay" | "partlyNight" | "cloudy"
| "fog" | "drizzle" | "rain" | "snow" | "thunder";
```
Maps a WMO weather code to a human label plus a glyph name for `icon()`.
### dd.weather.geocode() [#ddweathergeocode]
```ts
dd.weather.geocode(query: string, opts?: { cacheKey?: string }): Promise<{
query: string;
lat: number;
lon: number;
label: string;
}>
```
Resolves a place name, cached in the widget's own storage (one entry per
`cacheKey`; a changed query re-fetches).
### dd.weather.current() [#ddweathercurrent]
```ts
dd.weather.current(opts: {
lat: number;
lon: number;
units?: "celsius" | "fahrenheit";
}): Promise<{
temperature: number; // in the requested unit
code: number; // WMO code; feed it to describe()
isDay: boolean;
}>
```
### dd.weather.forecast() [#ddweatherforecast]
```ts
dd.weather.forecast(opts: {
lat: number;
lon: number;
units?: "celsius" | "fahrenheit";
scale: "hourly" | "daily";
count?: number; // slots to return, 1..24 (default 5)
stepHours?: number; // hourly only: hours between slots, 1..12 (default 1)
}): Promise>
```
The next slots of the forecast, hour by hour or day by day. **Slot 0 is always
the current period**, this hour or today, so you can label it "Now" or "Today"
without a second call; `stepHours` spaces the hourly slots, which lets five of
them reach a day and a half ahead.
Unlike `geocode`, this is stateless: nothing is cached for you. Keep your own
last-good snapshot in `dd.storage` if you want the widget to paint something
after a remount or while the network is down.
The array is short rather than padded when the forecast window ends, and a
malformed or empty response throws instead of returning partial slots.
### dd.weather.icon() [#ddweathericon]
```ts
dd.weather.icon(glyph: WeatherGlyph | string): string
```
A built-in line-art icon as a `data:` URI, ready for ``
(the widget CSP allows `img-src data:`). Unknown names return `""`.
## dd.claudeUsage [#ddclaudeusage]
Needs the `claudeUsage` permission.
### dd.claudeUsage.status() [#ddclaudeusagestatus]
```ts
dd.claudeUsage.status(opts: { dirKey: string }): Promise
```
Claude Code's own usage as one aggregated snapshot. `dirKey` names one of
this widget's `filePath` settings; the host resolves the `.claude` directory
the user configured there (blank = the default install), reads the limit
bars, today's tokens by model, and recently-active sessions, and refreshes
the bars from Anthropic's usage endpoint in the background. The OAuth token,
transcript contents, and raw paths never reach the widget. Poll it. 20 calls
per rolling 10 seconds.
```ts
interface ClaudeUsage {
/** False when the configured directory is not a readable Claude home:
* show a "set Claude home dir" hint. */
dirOk: boolean;
claudeVersion: string | null;
/** Where limits came from: "live" (Anthropic's usage endpoint), "cache"
* (Claude Code's own cache), or "none" (nothing available yet). */
source: "live" | "cache" | "none";
/** When limits was produced (epoch ms), for an "as of" readout. */
fetchedAtMs: number | null;
/** One bar per active limit window; percent is 0..100. */
limits: {
kind: string;
group: string;
label: string;
percent: number;
severity: string;
resetsAtMs: number | null;
isActive: boolean;
}[];
/** Today's usage summed from the transcripts (local day), by model. */
today: {
byModel: {
model: string;
input: number;
output: number;
cacheRead: number;
cacheWrite: number;
messages: number;
}[];
totals: {
input: number;
output: number;
cacheRead: number;
cacheWrite: number;
messages: number;
};
};
/** Recently-active Claude Code sessions. */
sessions: {
name: string | null;
cwd: string;
status: string;
updatedAtMs: number;
}[];
}
```
# Desktop, folders, apps, games, and launchers (/docs/reference/api/desktop-apps)
Four namespaces share one design: the host enumerates, the widget gets
opaque ids, and opening something means handing an id back. A widget never
passes a path, so it can only ever open what the host really listed.
They also share the change-ping pattern: `onChange` events carry no data,
they just tell you to list again.
## dd.desktop [#dddesktop]
Needs the `desktop` permission.
### dd.desktop.list() [#dddesktoplist]
```ts
dd.desktop.list(): Promise<{ items: DesktopItem[] }>
interface DesktopItem {
/** Opaque host-issued id: the only handle open() accepts. */
id: string;
name: string;
kind: "file" | "folder" | "shortcut" | "virtual";
/** Filesystem path; null for virtual items (Recycle Bin, This PC, ...). */
path: string | null;
/** Icon PNG data URI (up to 96 px), or null when the host couldn't extract one. */
icon: string | null;
}
```
Everything currently on the user's desktop (user and public folders plus
visible virtual items), sorted by name. Served from a host cache the desktop
watcher keeps fresh, so it is cheap to call.
### dd.desktop.open() [#dddesktopopen]
```ts
dd.desktop.open(id: string): Promise
```
Opens the item like a desktop double-click; a folder item opens in the file
manager the user chose in Settings > General, when one is set (app 0.3.7 or
newer). Accepts only ids from `list`; a
stale id (the item disappeared since your last list) rejects `NOT_FOUND`, so
re-list and retry. 5 opens per rolling 10 seconds, shared with
`folders.open`.
### dd.desktop.onChange() [#dddesktoponchange]
```ts
dd.desktop.onChange(cb: () => void): () => void
```
Data-free ping when the desktop's item set changes (add, remove, rename,
icon refresh): call `list` again. Changes are debounced around 400 ms.
## dd.folders [#ddfolders]
Needs the `folders` permission. All methods take `settingKey`, the name of
one of this widget's `filePath` settings; the host resolves the folder the
user pointed it at. A blank setting value resolves to the desktop source,
which additionally requires the `desktop` grant.
### dd.folders.list() [#ddfolderslist]
```ts
dd.folders.list(settingKey: string): Promise<{
items: DesktopItem[];
total: number;
truncated: boolean;
error?: string;
}>
```
One non-recursive listing of the granted folder. Items arrive with
`icon: null` here; fetch icons for what you actually render via `icons` (the
desktop source inlines them instead). Listings cap at 500 items
(`truncated: true`, `total` is the real count). An unreadable folder
(unplugged drive, dead share) answers the last good items plus
`error: "unavailable"` rather than rejecting. 30 calls per rolling 10
seconds.
### dd.folders.icons() [#ddfoldersicons]
```ts
dd.folders.icons(settingKey: string, ids: string[]): Promise<{
icons: Record;
}>
```
Icon PNG data URIs (up to 96 px) for up to 128 listed ids, extracted on demand and cached
host-side. Unknown or extraction-failed ids are simply absent from the
result, so keep a glyph fallback. 60 calls per rolling 10 seconds.
### dd.folders.open() [#ddfoldersopen]
```ts
dd.folders.open(settingKey: string, id: string): Promise
```
Opens a listed item like a double-click in Explorer; a folder item opens in
the file manager the user chose in Settings > General, when one is set (app
0.3.7 or newer). Stale ids reject
`NOT_FOUND` (re-list). Shares `desktop.open`'s 5 per 10 seconds launch
bucket, whichever source the id lives in.
### dd.folders.onChange() [#ddfoldersonchange]
```ts
dd.folders.onChange(cb: () => void): () => void
```
Data-free ping when a folder one of your `filePath` settings points at
changes (the desktop, for blank settings): re-list. Delivered only to the
instances whose folder actually changed. Folders that cannot be watched
(network shares generally) re-enumerate on every list instead of pretending.
## dd.apps [#ddapps]
Needs the `systemApps` permission.
### dd.apps.list() [#ddappslist]
```ts
dd.apps.list(): Promise<{ apps: SystemApp[] }>
interface SystemApp {
/** Catalog key: the only handle launch() accepts. */
id: string;
name: string;
/** Icon PNG data URI (up to 96 px), or null (render your own glyph). */
icon: string | null;
}
```
The host's fixed catalog of Windows system apps (Settings, File Explorer,
Recycle Bin, Task Manager, Terminal, Control Panel, Calculator, Notepad,
Snipping Tool), with real icons where the host could extract them. Icons are
cached host-side after the first call. 30 calls per rolling 10 seconds.
### dd.apps.launch() [#ddappslaunch]
```ts
dd.apps.launch(id: string): Promise
```
Launches a catalog app by key. There is no path, URI, or executable surface
here; ids from `list` are the whole vocabulary. A shell-folder entry (the
Recycle Bin) opens in the file manager the user chose in Settings > General,
when one is set, handed the folder's shell id; the File Explorer entry always
launches explorer.exe (app 0.3.7 or newer). Each app carries host-owned
fallback launch targets; if all fail the call rejects `INTERNAL` naming the
app, and unknown ids reject `NOT_FOUND`. 5 calls per rolling 10 seconds.
## dd.games [#ddgames]
Needs the `games` permission. App 0.3.2 and newer.
### dd.games.list() [#ddgameslist]
```ts
dd.games.list(): Promise<{ games: InstalledGame[]; total: number }>
interface InstalledGame {
/** Opaque host-issued id, the only handle launch and art accept. */
id: string;
name: string;
store: "steam" | "gog";
/** Tagged host-side, because a library is often a third demos. */
kind: "game" | "demo" | "playtest";
/** Epoch ms, or null when the store records no play history. */
lastPlayedMs: number | null;
/** Total minutes played, or null when the store records none. */
playtimeMin: number | null;
sizeBytes: number | null;
installedMs: number | null;
}
```
Every game installed on this PC that a supported launcher vouches for, most
recently played first and then alphabetical.
The sources are the launchers' own records, read off disk and the registry:
Steam's per-game manifests plus its local play-time config, and the GOG
registry keys that both Galaxy and the offline installers write. There is no
folder scan anywhere in this, by design, so nothing else the user keeps on a
games drive can ever appear here.
The appid, the registry id and the install path never cross the bridge. A
widget sees the fields above and nothing more. GOG records no play history
that the host can read, so its games always report `lastPlayedMs: null` and
sort below anything played.
The scan is cached host-side for 60 seconds, so calling this every time a
pane opens is cheap. 20 calls per rolling 10 seconds.
### dd.games.art() [#ddgamesart]
```ts
dd.games.art(
ids: string[],
kind?: "portrait" | "header",
): Promise<{ art: Record }>
```
Cover art for up to 32 listed ids, as PNG or JPEG data URIs.
It comes from the launcher's own on-disk cache, never the network. `kind`
picks the shape you lay out for: `portrait` (the default, a 2:3 library
capsule) or `header` (the wide banner). Whichever you ask for, the other
fills in when a title cached only that one, so a tile is rarely empty.
Ids with no cached art are simply absent from the result, so keep a
placeholder. A GOG entry answers its executable's icon, since GOG caches no
art. 30 calls per rolling 10 seconds.
### dd.games.launch() [#ddgameslaunch]
```ts
dd.games.launch(id: string): Promise
```
Starts a listed game through its own launcher, by the target the host holds
for that id. As with `apps.launch`, ids are the whole vocabulary: there is no
path or command-line surface. An id from a stale list rejects `NOT_FOUND`
rather than starting anything. 5 calls per rolling 10 seconds.
## dd.launchers [#ddlaunchers]
Needs the `launchers` permission. Grid widgets only. App 0.3.9 and newer.
Drop-to-launch: the user drags files, folders, shortcuts or exes from
Explorer or the desktop onto your widget, and the host turns each one into a
launch item. The drop is the consent. Nothing prompts, and nothing your
widget says can add an item.
The store is per widget id, not per instance: any instance of your widget
may open any item dropped on any instance of it. Keep your own membership
list per instance (an id list in `dd.storage`), the way the drawer keeps
`members`. Ids not in the store stay latent, never wrong.
No path ever crosses the bridge. A widget sees the fields below and nothing
more; the host resolves and opens each item itself.
### dd.launchers.list() [#ddlauncherslist]
```ts
dd.launchers.list(): Promise<{ items: LauncherItem[] }>
interface LauncherItem {
/** Opaque host-issued id, the only handle open and forget accept. */
id: string;
/** Frozen at drop time. */
name: string;
/** app = an exe or a shortcut to one; file and folder open like a double-click. */
kind: "app" | "file" | "folder";
/** Always null here: fetch via icons. */
icon: string | null;
}
```
Everything the user dropped on your widget type, in drop order. An exe or a
shortcut resolves through the same ladder a taskbar pin uses, so its id
equals the pin of the same app; a file or folder hashes its full name, so a
desktop file keeps the id `dd.desktop.list` gives it. The same target
dropped twice dedupes.
Cap 256 items per widget; further drops are refused with a log line. 30
calls per rolling 10 seconds.
### dd.launchers.icons() [#ddlaunchersicons]
```ts
dd.launchers.icons(ids: string[]): Promise<{ icons: Record }>
```
PNG data URIs (up to 96 px) for up to 128 ids of your store, extracted at
drop time and cached host-side for the session. Unknown or failed ids are
simply absent, so keep a glyph fallback. 60 calls per rolling 10 seconds.
### dd.launchers.open() [#ddlaunchersopen]
```ts
dd.launchers.open(id: string): Promise
```
Opens an item like a double-click: an app through the shortcut or exe it was
dropped as (a dropped shortcut keeps its arguments), a file by name, a folder
in the file manager the user chose in Settings, when one is set. Accepts only
ids in your widget's store. A target that is gone rejects with `NOT_FOUND`.
No gesture gate: the user consented per item by dropping it. Shares the
desktop and folders launch quota of 5 per rolling 10 seconds.
### dd.launchers.forget() [#ddlaunchersforget]
```ts
dd.launchers.forget(id: string): Promise
```
Removes the item from the store of every instance of your widget. A widget
with several instances edits its own membership list instead and never calls
this. The host drops the whole store when the widget is uninstalled. Unknown
id: `NOT_FOUND`.
### dd.launchers.onDrag() [#ddlaunchersondrag]
```ts
dd.launchers.onDrag(cb: (drag: { inside: boolean; count: number; kinds: string[] }) => void): () => void
```
An OS drag entered (`inside: true`) or left your drop rect. `count` is the
number of paths in the drag; `kinds` are extension hints only (`app` for
`.exe`, `shortcut` for `.lnk` and `.url`, `item` otherwise), since the host
never touches the filesystem during a hover. Paint your drop ring from this:
the native `dragover` never reaches the page.
### dd.launchers.onDrop() [#ddlaunchersondrop]
```ts
dd.launchers.onDrop(cb: (drop: { items: LauncherItem[] }) => void): () => void
```
The drop landed on you. The items are already in the store; an item that was
there already is announced again so this instance can adopt it. Add the ids
to your membership, re-render, and fetch icons via `icons`. Drops are refused
outright in edit mode and while widgets are peeked away.
### dd.launchers.onChange() [#ddlaunchersonchange]
```ts
dd.launchers.onChange(cb: () => void): () => void
```
The store changed: a drop on any instance of your widget, a `forget`, or an
uninstall. Call `list` again.
# Time, dates, theme, and cursor (/docs/reference/api/environment)
## dd.time [#ddtime]
Needs the `time` permission.
### dd.time.now() [#ddtimenow]
```ts
dd.time.now(): Promise<{ epochMs: number }>
```
### dd.time.onTick() [#ddtimeontick]
```ts
dd.time.onTick(cb: (tick: { epochMs: number }) => void): () => void
```
A second-aligned wall-clock tick. Prefer it over your own `setInterval` for
clock-like widgets: it stays aligned to the real second boundary.
## dd.dates [#dddates]
Always available, no permission needed: calendar arithmetic in local time,
with [date-fns](https://date-fns.org) underneath. The namespace is curated
rather than a re-export, because SDK surface is a permanent contract and the
whole library would cost every widget 73 KB. Display formatting is left out
on purpose: `Intl.DateTimeFormat` and `Intl.NumberFormat` with
`style: "unit"` already localize.
Everything reads and writes local wall-clock fields. Never
`new Date("2027-03-14")`: the date-only string form parses as UTC and lands a
day early west of Greenwich. An Invalid Date passed in comes back out as NaN
or an Invalid Date, the way JS does.
```js
const { startOfDay, breakdown, daysBetween, fromDayKey } = dd.dates;
const target = fromDayKey(settings.date); // null while unset
if (target) {
const now = new Date(tick.epochMs);
const sleeps = daysBetween(now, target); // 3, not "2 days 23 hours"
const parts = breakdown(startOfDay(now), target); // { years: 0, months: 1, days: 14, ... }
}
```
### dd.dates.startOfDay() [#dddatesstartofday]
```ts
dd.dates.startOfDay(d: Date): Date
```
Local midnight of `d`'s day.
### dd.dates.startOfMonth() [#dddatesstartofmonth]
```ts
dd.dates.startOfMonth(d: Date): Date
```
Local midnight of the first day of `d`'s month.
### dd.dates.startOfWeek() [#dddatesstartofweek]
```ts
dd.dates.startOfWeek(d: Date, weekStart?: Weekday): Date
type Weekday = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday"
```
Local midnight of the first day of `d`'s week. `weekStart` is the setting
string as stored, so `startOfWeek(d, settings.weekStart)` reads directly; a
missing or off-list value means Monday.
### dd.dates.addDays() [#dddatesadddays]
```ts
dd.dates.addDays(d: Date, n: number): Date
```
`d` moved `n` whole days at the same wall-clock time, so a daylight-saving
day is one step.
### dd.dates.addMonths() [#dddatesaddmonths]
```ts
dd.dates.addMonths(d: Date, n: number): Date
```
`d` moved `n` whole months, with the day clamped to the month it lands in:
31 January plus one is 28 or 29 February. Time of day is kept.
### dd.dates.daysBetween() [#dddatesdaysbetween]
```ts
dd.dates.daysBetween(from: Date, to: Date): number
```
Whole calendar days from `from` to `to`, midnight to midnight, so a 23-hour
daylight-saving day still counts one. Negative when `to` is the earlier
date. Use it for "3 sleeps away" and for day keys that must turn over at
midnight, not at a 24-hour mark.
### dd.dates.breakdown() [#dddatesbreakdown]
```ts
dd.dates.breakdown(
from: Date,
to: Date,
opts?: { largestUnit?: "years" | "days" },
): { years: number; months: number; days: number; hours: number; minutes: number; seconds: number }
```
The span as calendar parts, every field present (zeros included). It is
calendar arithmetic, not division: 31 January to 28 February is one month,
31 January to 1 March in a leap year is one month and one day, and 12:00 to
12:00 across a spring-forward is one day and zero hours. Sub-second
remainders truncate. When `to` is before `from`, every non-zero part is
negative, so order the pair yourself when you want a size and a direction.
`largestUnit: "days"` folds years and months into the day count, which is
the shape a live "days hours minutes seconds" readout wants.
### dd.dates.dayKey() [#dddatesdaykey]
```ts
dd.dates.dayKey(d: Date): string
```
Local `"YYYY-MM-DD"` for `d`. Fixed width, so two keys compare as dates with
`<` and `>`, and a key never passes through UTC. The right shape for storage
keys and for a `date` setting's value.
### dd.dates.fromDayKey() [#dddatesfromdaykey]
```ts
dd.dates.fromDayKey(key: string): Date | null
```
Local midnight of a `dayKey`, or `null` when the key is malformed or names a
day that does not exist (`"2027-02-31"` is refused rather than read as
3 March). A `date` setting's value goes through this; guard the `null`.
## dd.theme [#ddtheme]
Always available, no permission needed. Themes are applied by the host; the
SDK re-applies the token map to `:root` automatically, so plain CSS using
`var(--dd-*)` restyles itself. These methods are for JS that resolves colors
manually (canvas, inline styles).
### dd.theme.tokens() [#ddthemetokens]
```ts
dd.theme.tokens(): Promise>
```
The current `--dd-*` token map for this widget instance, as the host knows
it: the theme plus any per-widget style the user set on this instance. Note:
manifest
[font pins](/docs/reference/manifest#fonts) are injected as CSS on top of
this map, so `tokens()` does not see them; `dd.ui.token()` reads computed
style and does. Resolve font faces through `dd.ui.token()`.
### dd.theme.onChange() [#ddthemeonchange]
```ts
dd.theme.onChange(cb: (tokens: Record) => void): () => void
```
Fires live on every theme change (theme picker, wallpaper auto-theme, user
overrides) and on every per-widget style edit for this instance, previews
included. If you resolve token values in JS, do not cache them across this
event: re-read and redraw.
Since app 0.4.0 theme colors fade on screen, about 0.65 s at normal Animation
speed. `cb` runs once the fade has settled, so computed styles already hold
the new values when it fires. Without a fade (Animation speed Off, reduced
motion, low-spec mode, or changes less than 300 ms apart, as in every live
preview) it runs at once. Changes that arrive during one fade may coalesce
into a single call.
### dd.theme.accent() [#ddthemeaccent]
```ts
dd.theme.accent(settings: Record): string
```
Resolves the `accentColor`
[settings preset](/docs/reference/manifest#setting-presets) pair: the theme
accent while `useAccent` is on (the default), the user's custom `color`
otherwise. It reads the current token value, so re-call it inside
`dd.theme.onChange` (or use `bindAccent`) to stay theme-reactive.
### dd.theme.bindAccent() [#ddthemebindaccent]
```ts
dd.theme.bindAccent(cb: (color: string) => void): Promise<() => void>
```
`settings.bind` and `theme.onChange` in one: `cb` fires with the resolved
accent immediately and again on every settings or theme change. The returned
promise resolves (with the combined unsubscribe) after that first call.
## dd.cursor [#ddcursor]
Always available, no permission needed, and it works for non-interactive
widgets too: the window stays click-through, you get the signal without
capturing input.
### dd.cursor.onHover() [#ddcursoronhover]
```ts
dd.cursor.onHover(cb: (state: { inside: boolean }) => void): () => void
```
Fires when the real cursor enters or leaves this widget's footprint. While a
popout is open, the footprint is the bounding box of widget plus pane
(crossing the gap between them never flickers a leave), and both documents
receive the event.
### dd.cursor.onMove() [#ddcursoronmove]
```ts
dd.cursor.onMove(cb: (pos: { x: number; y: number }) => void): () => void
```
Cursor position at roughly 30 Hz while the cursor is inside this widget's (or
its pane's) rect, as fractions (0..1) of the receiving document's viewport.
For element-level hover effects without input capture. For the common case,
skip the subscription entirely: mark elements `data-dd-hover` and the SDK
toggles a `dd-hover` class on them for you.
# Media and audio (/docs/reference/api/media-audio)
## dd.media [#ddmedia]
Reads need the `media` permission; the transport verbs additionally need
`mediaControls`.
### dd.media.status() [#ddmediastatus]
```ts
dd.media.status(): Promise
```
The latest now-playing snapshot, a cheap cache read (`null` until the
watcher's first pass). Seed your UI with this, then follow the stream.
### dd.media.onNowPlaying() [#ddmediaonnowplaying]
```ts
dd.media.onNowPlaying(cb: (np: NowPlaying) => void): () => void
interface NowPlaying {
/** False = no media session anywhere (fields null, can* false). */
hasSession: boolean;
status: "playing" | "paused" | "stopped";
title: string | null;
artist: string | null;
album: string | null;
/** Source app id (e.g. "Spotify.exe"): for feature detection, not UI. */
sourceApp: string | null;
/** Album art as an image data URI, or null. */
art: string | null;
/** Null when the player reports no usable duration (live streams). */
position: {
/** Seconds from track start as of asOfEpochMs. */
seconds: number;
durationSeconds: number;
/** The player's own timeline stamp (epoch ms). Null = don't interpolate. */
asOfEpochMs: number | null;
} | null;
canPlayPause: boolean;
canSkipNext: boolean;
canSkipPrevious: boolean;
canSeek: boolean;
}
```
Two things to know:
* **Selection policy.** The host picks the actually playing session across
all Windows media sessions, not Windows' own "current session" (which
favors whoever last touched the media keys, like a paused YouTube tab). It
falls back to the most recent paused session so a play button works from
the desktop. `hasSession: false` means no session anywhere.
* **Change-driven, not fixed-rate.** Events arrive only when the reported
state changes. Seed with `status()`, and while `status === "playing"`
interpolate the displayed position locally as
`seconds + (Date.now() - asOfEpochMs) / 1000` (`asOfEpochMs` null means
don't interpolate).
`title`, `artist`, `album`, `art` and `position` are independently nullable;
render what you have.
### Transport controls [#transport-controls]
```ts
dd.media.playPause(): Promise // 20 calls / 10 s
dd.media.next(): Promise // 30 calls / 10 s
dd.media.previous(): Promise // 30 calls / 10 s
dd.media.seek(seconds: number): Promise // 60 calls / 10 s
```
All act on the selected session. A player rejecting an action (or the
session vanishing mid-call) is a silent no-op; the next snapshot corrects
your UI. Nothing to control rejects `NOT_FOUND`. `seek` takes seconds from
track start, clamped to the live track end host-side; check `canSeek` first,
and send on slider release rather than every drag tick.
## dd.audio [#ddaudio]
Needs the `audio` permission. Event-only: there are no audio methods.
### dd.audio.onSpectrum() [#ddaudioonspectrum]
```ts
dd.audio.onSpectrum(cb: (frame: SpectrumFrame) => void): () => void
interface SpectrumFrame {
bins: number[];
}
```
500 log-spaced loudness bands (roughly 35 Hz to 16 kHz), each 0..1, derived
host-side from system audio output. Never raw samples: loudness bands only,
and speech is not reconstructible from them.
Delivery contract:
* Frames arrive at roughly 30 Hz while media plays (20 Hz when the host runs
in low performance mode).
* A single all-zero frame marks each transition to silence (pause, track gap,
capture stopping), then the stream goes quiet. Let your bars decay to zero
on it and stop drawing.
* Capture is demand-driven: it runs only while some enabled, visible widget
with the `audio` grant exists (the active taskbar counts as one, since app
0.3.0) and the host's media watcher reports a playing session.
Subscribing is what turns it on. Sources without a media session
(audiobook players, most games) do not animate it.
* Since app 0.2.4 a widget may opt out of the media gate: declare a boolean
setting with the key `anyAudio` (default false). The host reads it by
name; while any visible audio widget has it on, capture runs for all
system sound instead of only media sessions. The checkbox applies on
Save, and real silence still produces the zero frame.
Performance contract: do not draw in the callback. Copy `bins` into a reused
buffer and render in your own `requestAnimationFrame` loop, interpolating
between frames (fast attack, slow decay), and stop the loop once the bars
settle at zero.
```js
const levels = new Float32Array(500);
dd.audio.onSpectrum((frame) => {
latest = frame.bins; // stash
ensureRafLoop(); // draw elsewhere, at your own pace
});
```
# Notifications and dialogs (/docs/reference/api/notifications-dialogs)
## dd.notify [#ddnotify]
Needs the `notifications` permission.
### dd.notify.sync() [#ddnotifysync]
```ts
dd.notify.sync(entries: {
id: string; // 1..64 chars, unique within the list
at: number; // epoch ms, between now and 366 days ahead
title: string; // non-empty, up to 80 chars
body?: string; // up to 200 chars
}[]): Promise<{ scheduled: number }>
```
Replaces this instance's entire schedule of future notifications. Cancelling
one means omitting it; an empty array clears them all. There is no per-entry
add or remove.
The host keeps the schedule and raises each toast itself, which is the whole
point: a hidden or disabled widget stops running, and the app may restart,
but the reminder still arrives. Re-send the list whenever it changes, and
once on boot.
Behavior and limits:
* Caps are rejected, never silently clamped: 64 entries, `at` within a year,
title up to 80 characters, body up to 200. Control characters are stripped
host-side.
* An entry more than 15 minutes past its time is dropped unfired rather than
stacking, so a machine that slept for a week does not wake to a week of
toasts.
* The toast is a host-drawn window in the corner of the primary work area.
The widget supplies text, never markup, and does not control placement,
appearance, or timing beyond `at`. At most 3 toasts are on screen at once.
* Removing or disabling the instance drops its schedule. Hiding deliberately
does not: surviving an unmount is the point.
## dd.dialogs [#dddialogs]
Host-drawn picker windows. Both pickers share the same consent gates and
lifecycle:
* Requires the real cursor inside the widget (call from a click handler;
for a bar, the bar window or its pane, app 0.3.7 or newer), and never
opens in edit mode.
* The picker is a normal OS window (taskbar, Alt-Tab, minimizable) that the
host renders and owns; the widget never draws into it, and only ever
receives ids back.
* No client timeout: the promise resolves whenever the user answers. The
host force-settles it after 1 hour unanswered, and force-cancels on edit
mode, widget reload, hide, disable, remove, or a crash.
* One picker per kind and instance. Calling again while your picker is open
surfaces the existing window, and the new call resolves `cancelled`
immediately.
* `checked` pre-checks ids (up to 1024, each up to 64 chars): pass your
current selection.
* The result is a replacement set: `cancelled: true` means change nothing;
otherwise `ids` is the user's full new checked set, and unchecking is
meaningful. Checked ids that no longer exist are carried through
untouched.
* 5 opens per rolling 10 seconds, shared between both pickers.
### dd.dialogs.pickDesktopItems() [#dddialogspickdesktopitems]
```ts
dd.dialogs.pickDesktopItems(opts?: { checked?: string[] }): Promise<{
cancelled: boolean;
ids: string[];
}>
```
Needs the `desktop` permission. Picks from the items on the user's desktop
(the same set `dd.desktop.list` returns).
### dd.dialogs.pickFolderItems() [#dddialogspickfolderitems]
```ts
dd.dialogs.pickFolderItems(settingKey: string, opts?: { checked?: string[] }): Promise<{
cancelled: boolean;
ids: string[];
}>
```
Needs the `folders` permission. The same picker aimed at the folder the
named `filePath` setting resolves to. A blank setting value falls through to
the desktop picker behind its own `desktop` grant, so a drawer widget keeps
one code path.
# Settings, storage, and files (/docs/reference/api/settings-storage)
## dd.settings [#ddsettings]
Reading settings needs no permission. Fields are declared in the manifest
(see [the manifest reference](/docs/reference/manifest#settings)); values are
edited by the user in the shell's settings dialog, never written by the
widget. A widget may however ask the host to open that dialog from a click,
with [`dd.settings.open()`](#ddsettingsopen).
### dd.settings.get() [#ddsettingsget]
```ts
dd.settings.get(): Promise>
```
The effective settings: manifest defaults merged with the user's stored
values. Always returns the persisted state, even while the settings dialog
previews something else.
### dd.settings.onChange() [#ddsettingsonchange]
```ts
dd.settings.onChange(cb: (settings: Record) => void): () => void
```
Fires on any settings edit. While the user tries values in the settings
dialog it also fires with live-previewed (unsaved) values, and fires once
more with the stored values if they dismiss. Treat every event the same and
just re-apply; do not try to distinguish preview from commit.
### dd.settings.bind() [#ddsettingsbind]
```ts
dd.settings.bind(cb: (settings: Record) => void): Promise<() => void>
```
Load-and-listen in one call: `cb` fires once with the current settings and
again on every change. The returned promise resolves (with the unsubscribe
function) after that first call, so `await dd.settings.bind(cb)` when the
code below needs settings populated.
### dd.settings.open() [#ddsettingsopen]
```ts
dd.settings.open(opts?: { highlight?: string }): Promise
```
Opens this widget's own settings dialog, the same window the edit-mode gear
opens. `highlight` names one of your manifest setting keys; the dialog
scrolls to that field and flashes it. Useful from an empty state: a "set me
up" button that lands the user on the right field.
The gates, shared with the other host-window methods:
* Requires the real cursor inside the widget (call it from a click handler;
for a bar, the bar window or its pane, app 0.3.7 or newer), and never
opens in edit mode. On a bar the call opens the Taskbar settings window
instead. A call outside those conditions rejects
`PERMISSION_DENIED`; there is no way to open the dialog without a user
interaction.
* `highlight` must name one of your setting keys (expanded preset fields
included), or the call rejects `INVALID_PARAMS`. A field that is currently
hidden (for example `panelImage` while `panel` is not `image`) still opens
the dialog, just without the scroll-and-flash.
* One window per instance: a repeat call surfaces the already-open window
and replays the flash.
* The promise resolves once the window is up. It never waits for Save; watch
`dd.settings.onChange` for the values as usual.
* Rate limited to 5 opens per rolling 10 seconds, shared with `dd.dialogs`.
* App 0.2.6 or newer; from a bar or its pane, 0.3.7 or newer.
This does not change what settings are: the dialog stays the only writer,
and there is still no `dd.settings.set`.
## dd.storage [#ddstorage]
Needs the `storage` permission. A small per-instance key-value store,
persisted by the host; two instances of the same widget do not share it.
A [taskbar](/docs/guides/taskbars#storage-without-an-instance) has no
instance, so it gets one store per bar widget instead (app 0.4.1 or newer).
```ts
dd.storage.get(key: string): Promise // stored value or null
dd.storage.set(key: string, value: unknown): Promise
dd.storage.delete(key: string): Promise
```
Limits: a value is capped at 64 KB serialized, the whole store at 512 KB per
instance. Exceeding either rejects `PAYLOAD_TOO_LARGE`. This is state
storage, not a database; keep large data out of it.
## dd.files [#ddfiles]
Needs the `files` permission.
### dd.files.read() [#ddfilesread]
```ts
dd.files.read(settingKey: string): Promise<{
text: string;
sizeBytes: number;
modifiedEpochMs?: number;
}>
```
Reads the file the user configured in the named `filePath` setting of this
widget. Widgets never handle raw paths: you name your own setting key, the
host resolves the path the user granted there. Manifest defaults for
`filePath` fields are deliberately ignored, so there is no way to ship a
widget pre-pointed at someone's file. Files are capped at 1 MB.
## dd.image [#ddimage]
Needs NO permission: it follows the same consent model as `dd.files.read`
(only a file the user actively picked in one of this widget's `filePath`
settings can ever be read), and returns bounded, content-sniffed image data
rather than file contents. App 0.2.4+.
### dd.image.load() [#ddimageload]
```ts
dd.image.load(settingKey: string): Promise<{
dataUrl: string;
mime: string;
sizeBytes: number;
modifiedEpochMs?: number;
}>
```
The image the user picked in the named `filePath` setting, as a base64
`data:` URL ready for `![]()
` or CSS `url()` (the widget CSP allows
`img-src data:`). Accepts png, jpeg, webp and gif, sniffed by magic bytes,
never by extension; capped at 8 MB; rate limit 20 per 10 s. This is what
backs the `panelStyle` preset's Background image field and the Sticker
widget.
## How secrets work [#how-secrets-work]
A `secretRef` setting names a secret stored by the host; the user picks which
one in the settings dialog, and the secret's value never reaches widget code.
The only place a widget can use one is `dd.http.fetch`: pass
`{ "$secret": "settingKey" }` as a header or query value and the host injects
the real value after validating the request. See
[dd.http.fetch](/docs/reference/api/data-services#ddhttpfetch) for the exact
rules. There is no API that returns a secret's value.
# System and power (/docs/reference/api/system)
## dd.system [#ddsystem]
Reads need the `system` permission; the write surface (`setVolume`,
`setMuted`, the microphone verbs, `setRadio`, the audio device and app
volume verbs, the Bluetooth verbs, the brightness verbs, the Wi-Fi verbs,
`openSettings`) additionally needs `systemControls`.
### dd.system.status() [#ddsystemstatus]
```ts
dd.system.status(): Promise
```
The latest vitals snapshot, a cheap cache read (`null` until the sampler's
first pass). Seed your UI with this, then follow `onVitals`.
### dd.system.onVitals() [#ddsystemonvitals]
```ts
dd.system.onVitals(cb: (vitals: SystemVitals) => void): () => void
interface SystemVitals {
/** CPU busy fraction 0..1 (null on the very first sample). */
cpu: number | null;
ram: { usedMb: number; totalMb: number; percent: number } | null;
/** GPU busy fraction 0..1: the busiest engine (3D, copy, video, compute)
* of ONE adapter, the figure Task Manager shows. The host measures the
* hardware adapter with the most dedicated video memory unless the user
* picked another in Settings > General. App 0.3.8+; earlier apps summed
* the 3D engines of every adapter. */
gpu: number | null;
/** Disk busy fraction 0..1 (physical disks total). */
disk: number | null;
/** Fixed drives (letters), resampled about every 30s inside the 1Hz
* stream. `percent` is used/total 0..1; `label` is the volume name or
* null; null when enumeration fails, empty when no fixed drives exist. */
drives:
| { mount: string; label: string | null; usedMb: number; totalMb: number; percent: number }[]
| null;
net: { rxBps: number; txBps: number } | null;
battery: { percent: number | null; charging: boolean } | null;
wifi: { ssid: string; signal: number } | null;
volume: { level: number; muted: boolean } | null;
/** The default microphone; null with no microphone. App 0.4.2+. */
mic: { level: number; muted: boolean } | null;
/** Radio state as Windows Quick Settings shows it; null while Windows
* cannot list the radios. App 0.4.2+. */
radios: { wifi: RadioState; bluetooth: RadioState; cellular: RadioState } | null;
}
/** "disabled": off by hardware switch or airplane mode. null: no such radio. */
type RadioState = "on" | "off" | "disabled" | null;
```
A 1 Hz stream. Every field fails independently: a machine with no GPU
counters, no Wi-Fi adapter, no battery, or no audio device reports `null` for
that field while the rest keep flowing. Render nulls as absent, not as zero.
`cpu`, `gpu`, `disk`, `volume.level`, `mic.level` and `ram.percent` are 0..1 fractions;
`wifi.signal` is 0..100. `drives` lists fixed volumes only and refreshes about
every 30 seconds inside the stream (app 0.2.5+); sizes are MiB, like `ram`.
`net` sums the up hardware interfaces only, so a VPN tunnel or a virtual
switch port never counts the same bytes again; a machine with no hardware
interface up (a VM guest) sums every up interface, and the first tick after
that rule flips is `null` (app 0.3.7 or newer; earlier apps summed every up
interface).
`gpu` is the busiest engine of one graphics adapter, the figure Task Manager
shows for that card: the hardware adapter with the most dedicated video
memory, or the one the user picked in Settings > General (app 0.3.8 or newer;
earlier apps summed the 3D engines of every adapter, integrated graphics
included).
### dd.system.setVolume() [#ddsystemsetvolume]
```ts
dd.system.setVolume(level: number): Promise // 0..1
```
Master volume. 120 calls per rolling 10 seconds; throttle slider drags
client-side to roughly one call per 100 ms.
### dd.system.setMuted() [#ddsystemsetmuted]
```ts
dd.system.setMuted(muted: boolean): Promise
```
20 calls per rolling 10 seconds.
### dd.system.setMicVolume() [#ddsystemsetmicvolume]
```ts
dd.system.setMicVolume(level: number): Promise // 0..1
```
The default microphone's level, the one the `mic` vitals field reads. 120
calls per rolling 10 seconds; throttle slider drags like `setVolume`. A
machine with no microphone rejects with `INTERNAL`. App 0.4.2 or newer.
### dd.system.setMicMuted() [#ddsystemsetmicmuted]
```ts
dd.system.setMicMuted(muted: boolean): Promise
```
Mutes or unmutes the default microphone. 20 calls per rolling 10 seconds.
App 0.4.2 or newer.
### dd.system.setRadio() [#ddsystemsetradio]
```ts
dd.system.setRadio(
kind: "wifi" | "bluetooth" | "cellular",
on: boolean,
): Promise
interface RadioSetResult {
access: "allowed" | "deniedByUser" | "deniedBySystem" | "unspecified";
state: RadioState;
}
```
Turns every radio of a kind on or off, like the tiles in Windows Quick
Settings. Call it from a click: the host refuses it in edit mode and unless
the cursor is inside your widget, its pane, or your bar, because Wi-Fi off
cuts the network.
Windows has its own privacy switch, "Let apps control device radios". When
it is off, the call resolves with `access: "deniedByUser"` instead of
rejecting; show that and offer `openSettings("privacy-radios")`. `state` is
the radio's state right after the switch, and the `radios` vitals field
confirms it within a second. A machine with no radio of that kind rejects
with `NOT_FOUND`. 5 calls per rolling 10 seconds. App 0.4.2 or newer.
### dd.system.audioDevices() [#ddsystemaudiodevices]
```ts
dd.system.audioDevices(): Promise
interface AudioDevices {
outputs: AudioDevice[];
inputs: AudioDevice[];
}
interface AudioDevice {
/** Opaque token for setAudioDevice, valid for this app run only. */
id: string;
/** The name Windows shows, e.g. "Speakers (Realtek Audio)". */
name: string;
/** The Windows default for its direction. */
isDefault: boolean;
}
```
The active audio outputs and inputs, each list with the default first, then
by name. The hardware id never reaches your widget: `id` is a token the host
issues per app run, so list again after a restart. 20 calls per rolling 10
seconds. App 0.4.2 or newer.
### dd.system.setAudioDevice() [#ddsystemsetaudiodevice]
```ts
dd.system.setAudioDevice(id: string): Promise
```
Makes a listed device the Windows default for its direction, in every role
(console, multimedia, communications), as the Windows sound menu does. It
resolves with the fresh list as Windows now reports it: render that, not a
guess. A stale id rejects `NOT_FOUND` (list again). The volume calls and
the audio spectrum follow the new default by themselves. 5 calls per
rolling 10 seconds. App 0.4.2 or newer.
### dd.system.onAudioDevicesChanged() [#ddsystemonaudiodeviceschanged]
```ts
dd.system.onAudioDevicesChanged(cb: () => void): () => void
```
A data-free ping when a device comes, goes, is enabled or disabled, or
becomes the default (your own `setAudioDevice` included), at most once a
second: call `audioDevices()` again. Needs `system` and `systemControls`.
App 0.4.2 or newer. For a ready-made list, use
[``](/docs/reference/components#dd-audio-devices).
### dd.system.audioApps() [#ddsystemaudioapps]
```ts
dd.system.audioApps(): Promise<{ apps: AudioApp[] }>
interface AudioApp {
/** Opaque token, valid for this app run. */
id: string;
/** "Spotify"; "System sounds" for the system session. */
name: string;
/** The app's icon as a data: URI, or null. */
icon: string | null;
/** The app's own level 0..1, a fraction of the master volume. */
level: number;
muted: boolean;
/** Playing sound right now. */
active: boolean;
/** The Windows system sounds session. */
system: boolean;
}
```
The apps with sound on the default output device, as the Windows volume
mixer shows them: one row per app, playing apps first, then by name, and the
system sounds row last. Running app names and icons say more than the vitals
do, so this read needs `systemControls` too. There is no change event: poll
while your mixer is visible, or use
[``](/docs/reference/components#dd-audio-mixer), which does.
20 calls per rolling 10 seconds. App 0.4.2 or newer.
### dd.system.setAppVolume() [#ddsystemsetappvolume]
```ts
dd.system.setAppVolume(id: string, level: number): Promise // 0..1
```
Sets one app's level, every stream it has. 120 calls per rolling 10
seconds; throttle slider drags like `setVolume`. A stale id rejects with
`NOT_FOUND` (list again). App 0.4.2 or newer.
### dd.system.setAppMuted() [#ddsystemsetappmuted]
```ts
dd.system.setAppMuted(id: string, muted: boolean): Promise
```
Mutes or unmutes one app. 20 calls per rolling 10 seconds. App 0.4.2 or
newer.
### dd.system.bluetoothDevices() [#ddsystembluetoothdevices]
```ts
dd.system.bluetoothDevices(): Promise<{ devices: BluetoothDevice[] }>
interface BluetoothDevice {
/** Opaque token, valid for this app run. */
id: string;
/** The name Windows shows. */
name: string;
connected: boolean;
/** "audio": headsets and speakers; the rest from the device class. */
kind: "audio" | "input" | "phone" | "computer" | "other";
/** bluetoothConnect / bluetoothDisconnect work on this device. */
canConnect: boolean;
}
```
The paired Bluetooth devices, classic and Low Energy (a dual-mode device is
one row), connected first. It reads what Windows already knows: no scan, and
no pairing. Send users to `openSettings("bluetooth")` to add a device. The
list stays readable while the radio is off. Paired device names say more
than the vitals do, so this read needs `systemControls` too. There is no
change event: poll while your list is visible, or use
[``](/docs/reference/components#dd-bluetooth-devices),
which does. 20 calls per rolling 10 seconds. App 0.4.2 or newer.
### dd.system.bluetoothConnect() and bluetoothDisconnect() [#ddsystembluetoothconnect-and-bluetoothdisconnect]
```ts
dd.system.bluetoothConnect(id: string): Promise
dd.system.bluetoothDisconnect(id: string): Promise
```
Connect or disconnect a paired audio device (`canConnect: true`), like the
Connect button in Windows Quick Settings; disconnecting does not unpair.
Call them from a click: the host refuses them in edit mode and unless the
cursor is inside your widget, its pane, or your bar. They resolve once
Windows has the request, and the link follows within a few seconds, so list
again. A device with no audio connection rejects with `INVALID_PARAMS`, a
stale id with `NOT_FOUND`. 5 calls per rolling 10 seconds each. App 0.4.2 or
newer.
### dd.system.brightness() [#ddsystembrightness]
```ts
dd.system.brightness(): Promise<{ displays: DisplayBrightness[] }>
interface DisplayBrightness {
/** Opaque token, valid for this app run. */
id: string;
/** "LG ULTRAGEAR"; "Built-in display" for a nameless laptop panel. */
name: string;
/** 0..1 */
level: number;
primary: boolean;
/** The display showing your widget, bar or pane. */
here: boolean;
}
```
The displays whose brightness can be set: a laptop's built-in panel, and
external monitors that answer DDC/CI over the cable. A monitor without
DDC/CI, or with it turned off in its own menu, is left out, so a desktop
often gets an empty list; render nothing then. There is no change event:
poll while visible, or use
[``](/docs/reference/components#dd-brightness), which does.
Monitor reads are cached for 15 seconds, so polling faster shows nothing
new. 20 calls per rolling 10 seconds. App 0.4.2 or newer.
### dd.system.setBrightness() [#ddsystemsetbrightness]
```ts
dd.system.setBrightness(id: string, level: number): Promise // 0..1
```
Sets one display's brightness. The host serves every display from one
queue: sets for the same display collapse to the newest, and writes to an
external monitor stay 200 ms apart, because many monitors store each write.
Throttle slider drags to roughly one call per 150 ms. A stale id rejects
with `NOT_FOUND` (list again). 120 calls per rolling 10 seconds. App 0.4.2
or newer.
### dd.system.wifiNetworks() [#ddsystemwifinetworks]
```ts
dd.system.wifiNetworks(): Promise<{ networks: WifiNetwork[] }>
interface WifiNetwork {
ssid: string;
/** Signal quality 0..100. */
signal: number;
secured: boolean;
connected: boolean;
/** Windows has a saved profile: wifiConnect only works for these. */
known: boolean;
}
```
Available networks, deduped by SSID (strongest kept), connected first. The
host triggers a background scan at most every 30 seconds. 6 calls per rolling
10 seconds.
### dd.system.wifiConnect() [#ddsystemwificonnect]
```ts
dd.system.wifiConnect(ssid: string): Promise
```
Connects only to networks with a saved Windows profile (`known: true`);
passwords never cross the bridge. No profile rejects `NOT_FOUND`; send users
to `openSettings("wifi")` for new networks. 3 calls per rolling 10 seconds.
### dd.system.wifiDisconnect() [#ddsystemwifidisconnect]
```ts
dd.system.wifiDisconnect(): Promise
```
3 calls per rolling 10 seconds.
### dd.system.openSettings() [#ddsystemopensettings]
```ts
dd.system.openSettings(panel: SettingsPanel): Promise
type SettingsPanel =
| "sound"
| "power"
| "wifi"
| "battery"
| "bluetooth" // app 0.4.2+
| "display" // app 0.4.2+
| "apps-volume" // app 0.4.2+: the per-app volume mixer page
| "privacy-radios" // app 0.4.2+: where Windows lets apps control the radios
```
Opens a Windows settings page. `panel` is a whitelist key mapped host-side;
widgets can never launch arbitrary settings targets. An app older than 0.4.2
rejects the newer keys with `INVALID_PARAMS`. 3 calls per rolling 10
seconds.
## dd.power [#ddpower]
Needs the `power` permission, which is deliberately separate from
`systemControls`: granting a volume slider is not granting the power to turn
the machine off.
### dd.power.capabilities() [#ddpowercapabilities]
```ts
dd.power.capabilities(): Promise<{ sleep: boolean; hibernate: boolean }>
```
What this machine can actually do, read from its firmware. Check it before
drawing a Sleep button: many desktops have no sleep state at all, and a
button that fails every press reads as a broken widget. An unreadable answer
reports `true` for both, so a machine that would have worked never loses its
button. No gesture gate (a widget needs this before any interaction). 30
calls per rolling 10 seconds.
### dd.power.run() [#ddpowerrun]
```ts
dd.power.run(action: "shutdown" | "restart" | "restartAdvanced" | "sleep" | "lock" | "signOut"): Promise<{ ran: boolean }>
```
Ends or suspends the Windows session. Only these six actions exist; nothing
else (no flags, no timeouts, no targets) reaches the OS. Refused unless the
real cursor is inside the widget, and refused in edit mode, so a background
timer can never trigger it. From a bar, the test is the bar window or its
pane (app 0.3.7 or newer; older apps refuse bars outright).
`restartAdvanced` restarts into the advanced startup menu (recovery,
firmware settings, safe mode), what `shutdown /r /o` does. App 0.3.7 or
newer; an older app rejects it `INVALID_PARAMS` with "unknown power action",
so catch that to feature-detect.
`shutdown`, `restart`, `restartAdvanced` and `signOut` first raise a host-drawn confirmation the
widget cannot draw, style, or auto-answer; Cancel holds the initial focus,
and Escape, closing the window, or a timeout all answer no. `ran: false`
means the user declined, which is the moment to re-enable your button:
```js
const { ran } = await dd.power.run("shutdown");
if (!ran) button.disabled = false;
```
`sleep` and `lock` skip the confirmation, being instantly reversible. Nothing
here forces applications to close: an app with unsaved work still gets
Windows' own "this app is preventing shutdown" screen. On actions that
proceed, the session usually ends before the promise settles. 6 calls per
rolling 10 seconds.
# UI toolkit (/docs/reference/api/ui)
DOM and reactive helpers. Destructure what you use at the top of `widget.js`:
```js
const { create, signal, computed, effect } = dd.ui;
```
Two design constraints run through everything here, both deliberate:
* Bindings are declared visibly at the `create()` call site: a prop or child
that is a function or Signal is reactive, everything else is applied once.
* Updates are synchronous. There is no scheduler and no batching, so nothing
hides execution order.
## dd.ui.create() [#dduicreate]
Builds a DOM element.
```ts
create(tag: string, props?: Props, ...children: Child[]): HTMLElement | SVGElement
```
Props are optional: when the second argument is a Node, string, number,
array, function, or Signal, it is treated as the first child.
| Prop | Behavior |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `class` | sets `className` (write `class`, not `className`) |
| `style` | object: merged into `el.style` (camelCase keys); string: the `style` attribute |
| `on*` (`onClick`, `onPointerDown`, ...) | `addEventListener` with the lowercased remainder; never reactive |
| `ref: (el) => void` | called after props and children are applied, for elements you keep a handle to |
| key contains `-` (`data-*`, `aria-*`, `stroke-width`), or the element is SVG | attribute: `true` becomes `""`, `false` and nullish remove it |
| anything else | element property if one exists (`hidden`, `disabled`, `value`), else attribute |
| value is a function or Signal (except `on*` and `ref`) | live binding, re-applied whenever the signals it reads change |
Children: strings and numbers become text nodes, arrays are flattened, `null`,
`undefined` and booleans are skipped (so `cond && node` works), and a function
or Signal child binds one text node (`String(value)`, nullish renders as
`""`). Reactive children are text-only by contract; for reactive structure,
write an explicit `effect(() => container.replaceChildren(...))`. SVG tags
(`svg`, `path`, `circle`, `rect`, ...) are created in the SVG namespace
automatically.
## Signals [#signals]
```ts
signal(initial: T): Signal // { value, peek() }
computed(fn: () => T): Signal
effect(fn: () => void): () => void
```
`signal(initial)` returns an object with a `value` you read and write, plus
`peek()` to read without subscribing the current effect. `computed(fn)`
derives eagerly from the signals `fn` reads. `effect(fn)` runs now and again
whenever any signal it read changes; it returns a dispose function, usually
ignored.
Semantics, all deliberate:
* **Synchronous, no batching.** A write re-runs subscribers before it
returns; an effect reading N signals may run up to N times for a
multi-signal update.
* **Writes are `Object.is` guarded.** Assigning an equal value propagates
nothing, so a `computed` that recomputes to the same result stops the chain.
* **A cascade of more than 1000 effect runs from one write throws** (and
logs). That is the circular-write guard.
* **No disposal lifecycle.** Widgets die with their iframe, so effects simply
live as long as the document. The one backstop: bindings created by
`create()` self-dispose when their element has left the DOM.
**The one rule when mixing patterns:** per subtree, pick build-once with
bindings, or wholesale re-render with plain `create()`. Never put reactive
props inside rows that a render function throws away; the auto-dispose is a
backstop, not a design.
## dd.ui.bindParts() [#dduibindparts]
Applies live props to markup that already exists: the companion to `create()`
for a subtree whose shape is fixed but whose parts react. Stateful inline SVG
is the usual case.
```ts
bindParts(root: Element, bindings: Record): void
```
Author the art in `index.html`, mark the changing nodes `data-bind="name"`,
then pass the same props `create()` takes. Reactivity, the
attribute-vs-property rules, `on*` listeners, `ref`, and element-lifetime
auto-dispose all behave identically.
```js
bindParts(batteryEl, {
level: {
width: () => (pct.value / 100 * 11.6).toFixed(1),
opacity: () => (charging.value ? "0" : "1"),
},
bolt: { opacity: () => (charging.value ? "1" : "0") },
});
```
`root` itself is eligible if it carries a `data-bind`. A name matching several
nodes binds all of them; a name matching none logs a warning (typo insurance).
Text is just a prop: `{ textContent: () => label.value }`.
## dd.ui.autofit() [#dduiautofit]
```ts
autofit(root: HTMLElement, opts?: { content?: HTMLElement; prop?: string }):
{ refit(): void; stop(): void }
```
Measure-driven autoscale for a `.dd-autoscale` readout, for a panel whose
type IS the layout. The skeleton's `cqmin` default ties the font to the
container's smaller edge whichever axis that is, so trimming slack height
shrinks a width-limited line for nothing. `autofit` instead measures the
content and writes the largest font-size at which it fits the root BOTH
ways: a shorter tile keeps its type until the text would truly overflow.
`root` is the `.dd-autoscale` element, `content` (default: the root's first
element child) is the measured block, and `prop` (default
`--dd-autoscale-size`) is the custom property written, in px, onto the
root's style. Point `prop` at your own variable to chain a multiplier:
```js
const fit = dd.ui.autofit(rootEl, { prop: "--cd-fit" });
// CSS: --dd-autoscale-size: calc(var(--cd-fit, 23cqmin) * var(--cd-scale, 1));
```
The measurement is a hidden clone of `content`, laid out for one frame at
`max-content` width inside the root, so a wrapping row measures unwrapped
and the fit is a single ratio, no iteration. Everything in the skeleton is
em of one font, so the result is exact, and multipliers riding on the
written value cancel out of the ratio: re-measures converge and go quiet.
Both elements are watched with a `ResizeObserver`, and calls coalesce to
one measurement per frame. One case needs a hand: a content change the
boxes cannot betray, such as text swapped for longer text on the same line
count. Call `refit()` there (the Countdown widget does it whenever its
readout text changes). Intended for type-shaped content: the clone is
cheap for a readout, not for a thousand-row list.
## dd.ui.token() [#dduitoken]
```ts
token(name: string, fallback?: string): string
```
Reads a design token (a `--dd-*` custom property) as a string, for JS that
cannot use CSS variables directly: canvas fills, inline-SVG strokes, computed
layout. It reads the current value off the document root, so calling it again
after a `dd.theme.onChange` picks up the new theme. While a theme color is
fading (app 0.4.0+), it answers the color the fade is heading to, never an
in-between value. `fallback` is returned when the token is unset. Unlike `dd.theme.tokens()`, this sees
[manifest font pins](/docs/reference/manifest#fonts), so canvas text should
resolve faces through it. Both see the user's per-widget style for this
instance.
```js
function readColors() {
ctx.strokeStyle = dd.ui.token("--dd-chart-1", "#888");
}
dd.theme.onChange(() => { readColors(); redraw(); });
```
## dd.ui.pressGuard() [#dduipressguard]
```ts
pressGuard(el: Element, ms?: number): boolean
```
The double-activation guard for button-ish elements: returns `false` while
`el` is still disabled from a previous press, otherwise disables it now and
re-enables it after `ms` (default 500). Works on `dd-*` component hosts too;
they reflect `disabled` onto their inner button. Use it at the top of a click
handler:
```js
btn.addEventListener("click", () => {
if (!pressGuard(btn)) return;
// ...
});
```
## dd.ui.components [#dduicomponents]
The `dd-*` custom element constructors, for subclassing: `DdElement`,
`DdPanel`, `DdText`, `DdIcon`, `DdButton`, `DdIconButton`, `DdChip`,
`DdMeter`, `DdAppTile`, `DdVolumePill`. See
[the component reference](/docs/reference/components#overriding) for the
override pattern.
# Popouts, peers, and widgets (/docs/reference/api/widgets-together)
## dd.popout [#ddpopout]
Needs a manifest `popout` declaration
(see [the manifest reference](/docs/reference/manifest#popout)): a geometry
capability, not a permission. A popout is a second document from your widget
folder (the manifest's `popout.entry`), rendered by the host in an overlay
next to your widget. Your own document never moves or resizes.
### dd.popout.open() [#ddpopoutopen]
```ts
dd.popout.open(opts: {
size: { w: number; h: number }; // your own CSS px, 8..4096 per dimension
anchor?: Element | { x: number; y: number; w: number; h: number };
prefer?: "down" | "up" | "left" | "right" | "auto";
data?: unknown; // JSON, up to 8 KB
}): Promise<{
side: "down" | "up" | "left" | "right"; // the applied side
size: { w: number; h: number }; // the granted pane size, in your px
}>
```
Opens the pane at exactly `size` (capped by the manifest's `popout.max`,
which is in base grid cells), placed next to `anchor`: an element (the SDK
measures it for you) or a pixel rect in your viewport; omitted means your
whole rect. Size and anchor are in your widget's own pixels, the ones you
measure inside your document. Below a Widget size of 100% the host lays
your document out larger than its tile and scales it down, and it converts
a popout request at that same boundary, so the pane paints at your widget's
scale and the granted size comes back in your pixels. The host tries `prefer`, flips to
the opposite side when that fits better, and nudges the pane fully
on-canvas. Size is granted exactly, position is best-effort, so the pane
may end up overlapping your widget (it paints on top).
`data` reaches the pane document as `ctx.popout.data`. Re-calling reshapes:
the pane document remounts with the new data, and its entrance animation
replays.
Gates: the real cursor must be inside the widget (popouts open only as part
of a user interaction), never in edit mode, main document only. Popouts are
transient and never persisted. 20 calls per rolling 10 seconds.
### dd.popout.close() [#ddpopoutclose]
```ts
dd.popout.close(): Promise
```
Idempotent, callable from either document. The host also force-closes the
pane on edit mode entry, widget reload, grid rescale, hide, disable, remove,
and a crash of either document.
### dd.popout.onChange() [#ddpopoutonchange]
```ts
dd.popout.onChange(cb: (state: { active: boolean; side?: string | null }) => void): () => void
```
The popout lifecycle, including host force-closes. `active: false` means the
pane is gone: un-highlight your trigger. Both documents receive it.
### dd.popout.send() and onMessage() [#ddpopoutsend-and-onmessage]
```ts
dd.popout.send(msg: unknown): void
dd.popout.onMessage(cb: (msg: unknown) => void): () => void
```
The channel between your instance's two documents (main and pane), relayed
by the shell, since sandboxed siblings cannot talk directly. JSON, up to
8 KB per message; sends are dropped silently when no pane is open.
### dd.popout.flyout() [#ddpopoutflyout]
```ts
dd.popout.flyout(opts: FlyoutOpts): {
open: (key?: string) => Promise;
close: () => void;
toggle: (key?: string) => void;
active: () => string | null;
}
interface FlyoutOpts {
panes: Record;
/** The pane em base in px. Default: the anchor's computed font-size,
* clamped to 13..22. */
font?: () => number;
/** Close when the cursor leaves the widget+pane footprint. Default true. */
retractOnLeave?: boolean;
prefer?: "down" | "up" | "left" | "right" | "auto";
/** Fires on every active-pane change: open, switch, close, host close. */
onState?: (active: string | null) => void;
}
interface FlyoutPane {
/** Pane size in CSS px for a given pane font. */
size: (font: number) => { w: number; h: number };
/** The element (or px rect) the pane anchors to, resolved at open time. */
anchor: () => Element | { x: number; y: number; w: number; h: number };
/** Extra pane data, merged over the built-in { pane, font }. */
data?: (font: number) => Record;
}
```
The transient-pane lifecycle in one helper, for the common "icon bar with
flyout panels" idiom. Give it your pane registry and it owns the whole
dance:
* mirrors host force-closes back into `onState`, so your trigger
un-highlights;
* retracts when the cursor leaves the widget-plus-pane footprint (unless
`retractOnLeave: false`);
* holds the retract while the pane reports a slider drag in flight (the pane
relays `{ dragging }` via `dd.popout.send`);
* rolls back cleanly, with a warning log, when an open is refused.
```js
const flyout = dd.popout.flyout({
panes: {
volume: {
size: (font) => ({ w: font * 16, h: font * 3.4 }),
anchor: () => volumeBtn,
},
},
onState: (active) => volumeBtn.toggleAttribute("active", active === "volume"),
});
volumeBtn.addEventListener("click", () => flyout.toggle("volume"));
```
## dd.peers [#ddpeers]
Needs the `peers` permission. Host-mediated drag and drop between instances
of the same widget type: the payload is captured host-side and delivered
only to the host-resolved drop target.
### dd.peers.dragStart() [#ddpeersdragstart]
```ts
dd.peers.dragStart(opts: {
data: unknown; // up to 8 KB
ghost?: { label?: string; icon?: string }; // label 64 chars, icon a data:image/ URI up to 64 KB
}): Promise
```
Starts a drag. Only callable while the primary button is physically held
inside this widget (start it from pointerdown plus movement); the gesture is
the consent. `ghost` feeds the cursor chip the shell draws. One drag exists
globally, with a 60 second timeout. The host resolves the drop on the real
button release: the payload goes only to the eligible instance under the
cursor (same widget type, visible, not the source). 20 calls per rolling 10
seconds.
### dd.peers.cancel() [#ddpeerscancel]
```ts
dd.peers.cancel(): Promise
```
Abandon your own active drag (Escape, for example). No-op otherwise.
### dd.peers.onDrag() [#ddpeersondrag]
```ts
dd.peers.onDrag(cb: (state: { active: boolean; self: boolean }) => void): () => void
```
Drag lifecycle for your widget type: highlight drop targets while
`active && !self`.
### dd.peers.onDrop() [#ddpeersondrop]
```ts
dd.peers.onDrop(cb: (drop: { data: unknown; x: number; y: number }) => void): () => void
```
You are the drop target. `x` and `y` are the drop point as fractions of your
viewport. Targeted: no other frame sees the payload.
### dd.peers.onEnd() [#ddpeersonend]
```ts
dd.peers.onEnd(cb: (end: { accepted: boolean; outside: boolean }) => void): () => void
```
Your drag finished. `accepted` means a peer received it (remove the item for
move semantics). `outside` means a real drop that landed on neither a peer
nor yourself: treat as "dropped into the void" (usually remove). Both false
means snap back (released over yourself, or the host cancelled the drag).
### dd.peers.draggable() [#ddpeersdraggable]
```ts
dd.peers.draggable(el: HTMLElement, opts: {
data: () => unknown;
ghost?: () => { label?: string; icon?: string };
onClick?: (e: MouseEvent) => void;
}): () => void
```
Makes an element press-draggable to peers while keeping it clickable. A
press that moves past a 6 px threshold starts the host drag (`data()` and
`ghost()` are called at that moment, and the element carries a `dd-dragging`
class until the drag ends); a plain click calls `onClick`; the phantom click
a released drag would land is swallowed for you. Returns a dispose function.
The semantic outcome still arrives via `onDrop` and `onEnd`.
### dd.peers.recentDrag() [#ddpeersrecentdrag]
```ts
dd.peers.recentDrag(): boolean
```
True briefly (350 ms) after any drag activity. Guard click handlers on
elements that are not draggable themselves; a drag released over them would
otherwise count as a click.
## dd.widgets [#ddwidgets]
Needs the `control` permission.
### dd.widgets.list() [#ddwidgetslist]
```ts
dd.widgets.list(): Promise<{ targets: WidgetTarget[] }>
interface WidgetTarget {
instanceId: string;
widgetId: string;
/** The widget type's display name. */
name: string;
/** The target's own title setting, or "". */
title: string;
enabled: boolean;
hidden: boolean;
}
```
Returns only the instances the user ticked in this widget's
`instances`-typed settings. The shell settings UI is the sole writer of
those, so a widget can never expand its own target set; manifest defaults
for `instances` fields are ignored. Self is always excluded, and stale
approvals are dropped silently. 60 calls per rolling 10 seconds.
### dd.widgets.setHidden() [#ddwidgetssethidden]
```ts
dd.widgets.setHidden(instanceId: string, hidden: boolean): Promise
```
Show or hide an approved target. Unapproved ids reject `PERMISSION_DENIED`
whether or not they exist. Hidden widgets unmount entirely: they stop
running (no timers, no listeners) until shown again, from the controlling
widget or from edit mode. 30 calls per rolling 10 seconds.
A host peek is different. The user can conceal every widget at once (a
double click on empty desktop space, or Hide widgets in the tray menu);
widgets stay mounted and running, receive no input, keep their `hidden`
flag as it was, and come back the same way. `widgets.list` does not reflect
a peek and no `widgets.changed` fires for it.
### dd.widgets.onChange() [#ddwidgetsonchange]
```ts
dd.widgets.onChange(cb: () => void): () => void
```
Data-free ping when any instance's state changes (hidden, enabled, added,
removed): re-list.