Manifest & result types

Every widget has a manifest — the metadata the hub stores alongside its HTML. You don’t write it directly; the hub builds it when you publish. But knowing the fields helps when you list widgets or debug versioning. This is the current hub record for a published widget, not a portable template package or a declaration of which rendering surfaces it supports.

Manifest fields

list_widgets returns an array of these plus the activeWidgetId.

The registry also carries an envelopeHash for complete envelope integrity. Current update offers compare HTML hashes, so an icon-only or sample-data-only registry revision does not by itself trigger an update offer.

Icons

A WidgetIcon has a kind and a value:

{ "kind": "sfSymbol", "value": "thermometer" }
{ "kind": "emoji",    "value": "🎵" }
{ "kind": "png",      "value": "<base64-encoded PNG bytes>" }

For a png, the hub stores the bytes, computes their SHA-256, and rewrites value to that hash (a cache key); the raw bytes are served at GET /widget/:id/icon. So a manifest you read back will show the hash, not the base64 you sent.

Set or change an icon without touching the HTML via set_widget_icon:

{ "id": "wgt_abc123", "icon": { "kind": "sfSymbol", "value": "thermometer.sun" } }

Formal shapes

The typed shapes behind the tables above and the hub’s JSON responses. MCP tool calls wrap their output in text content: some include serialized JSON, while others describe the result in prose. See MCP results.

WidgetManifest

interface WidgetManifest {
  id: string;
  name: string;
  refreshMs: number;
  htmlHash: string;        // SHA-256 (hex) of the HTML
  version: number;
  publishedAt?: number;    // Unix seconds
  icon?: WidgetIcon;
  builtInSlug?: string;    // set if installed from a shipped template
  builtInVersion?: number;
  templateHash?: string;   // SHA-256 of the pristine template last installed
  source?: "builtin" | "mcp" | "cli" | "registry";
  registryId?: string;
  registryVersion?: number;
  publishedRegistryId?: string;
}

WidgetIcon

interface WidgetIcon {
  kind: "sfSymbol" | "emoji" | "png";
  // sfSymbol: symbol name · emoji: the character ·
  // png: base64 PNG on input, rewritten to the bytes' SHA-256 once stored
  value: string;
}

WidgetVersion

One entry in a widget’s bounded code history. list_versions returns these newest-first; set_widget_version selects one as the live version (no new entry is appended — isCurrent moves to it and history stays intact).

interface WidgetVersion {
  version: number;
  htmlHash: string;        // SHA-256 (hex) of that snapshot's HTML
  updatedAt: number;       // Unix seconds
  note?: string;
  isCurrent: boolean;      // the version currently live (selection moves this)
  builtInVersion?: number; // set when this cut is a pristine copy of a shipped
                           // built-in template (labels stock cuts vs your edits)
}
interface ListVersionsResult { versions: WidgetVersion[]; }

Hub result objects

// GET /admin/pair-status (the MCP's pair_status summarizes this in text)
interface PairStatus {
  paired: boolean;
  connected: boolean;
  deviceName?: string;
  deviceKind?: string;     // e.g. "iphone" or "ipad"
}

// POST /admin/publish (the MCP returns a message containing the id)
interface PublishWidgetResult { id: string; }

// list_widgets
interface ListWidgetsResult { widgets: WidgetManifest[]; activeWidgetId?: string; }

// list_versions → ListVersionsResult (see WidgetVersion above)

// GET /admin/data-endpoint/:id (the MCP formats the URL and auth header as text)
interface DataEndpoint { url: string; token: string; }

Tool arguments at a glance

requiresConfirmation is currently stored metadata; the phone does not enforce per-invocation confirmation. Action consent is enforced separately on the Mac; see Interactive actions.