Manifest reference

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:

{
  "$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

Settings

Each settings entry is either a full field object or a preset name string; the array accepts both, mixed:

"settings": [
  { "key": "title", "type": "text", "label": "Title", "default": "Tasks" },
  "panelStyle"
]

Field objects

Field types

The three consent-bearing types (secretRef, filePath, instances) never inherit a manifest default. Their value grants access to something the user owns (a credential, a file, other widgets), so only a value the user actively picked counts; a published widget cannot ship pre-pointed at anyone's private data.

Setting presets

A preset bundles a recurring field (or field pair) with the code that applies it, declared by name:

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.

Popout

"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. It is a geometry capability like interactive, not a privacy permission: the pane is a second sandboxed document with the same grants.

Fonts

Optional, and it needs "minAppVersion": "0.2.0" (older apps do not know the key). Pins a font onto one or more of the three face tokens, in this widget's documents only:

"fonts": { "use": { "display": "audiowide" } }

use takes any of sans, display, mono. Values are bundled catalog ids (audiowide, nunito, nunito-sans; an unknown id quarantines the manifest) or a self: reference to a family the widget ships itself:

"fonts": {
  "bundle": [{ "id": "heading", "files": [{ "src": "fonts/mine.woff2", "weight": "400" }] }],
  "use": { "display": "self:heading" }
}

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(). Every bundled catalog face also exists as a convenience var (--dd-font-audiowide, --dd-font-nunito, --dd-font-nunito-sans), 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

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, minSize, popout.max) must each be 1..64 cells per dimension.
7. 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.