One JSON file,
a new mini app on your watch

1. Top-level fields

A plugin is a JSON object holding metadata, pages, actions, initial state, and a refresh policy:

2. Pages & headers

Every page (PluginPage) has four parts: a header, a body component array, an optional settings section, and optional bottom buttons. The page renders in a scrolling header / main / extras / bottom layout.

Header trailing controls trailing come in three kinds:

Layout model

Every plugin page runs on the app's unified watch layout system — a header, a center body, a persistent settings area, and bottom buttons. Two modes come out of the box, and both obey the app's two layout principles: the first screen always fits (nothing clipped or overflowing), and content below the fold is hinted by a breathing arrow in the bottom-right corner.

• Default scrolling page: header / body / settings / bottom all scroll as one page. When content overflows, the breathing fold arrow appears (hidden while everything fits, ↓ while there is more below, ↑ once you reach the end).
• One-screen fit page (fit: true): the center never scrolls — content adapts instead. Text auto-shrinks down to 50% to stay fully visible, and rings / QR codes / images fill the center area.
• Sub-pages, never popups: navigate switches pages full-screen and the header gains a back arrow — the app has no alert popups at all. Destructive bottom buttons use double-tap confirm (first tap turns red + shake) instead of a dialog.
• Header overflow guard: more than two trailing controls collapse the leading ones into a glass ⋯ menu — put your high-frequency actions last in the trailing array.

3. Body components

body is an array of components distinguished by type. Text comes from either value (a literal supporting {{key}} templates) or bind (reads state; an np. prefix reads the built-in player live) — pick one.

4. Settings

The settings section lives in the extras area; controls read and write state keys directly via bind, changes persist immediately, and HTTP action {{key}} templates always see the latest values.

5. Bottom buttons

6. Actions

JSONPath: extract values are dot paths with array indexes, e.g. $.rates.CNY, $.list[1].n; unresolvable paths write null for that key.

7. Runtime semantics

• Default refresh action: the first http action (otherwise the first action). Runs once when the plugin opens with loadOnStart ≠ false; repeats on a cycle when refreshInterval ≥ 5 seconds.
• Template variables: {{key}} is replaced with the current state value (numbers and booleans stringify directly); keys missing from state stay as-is, which makes step-by-step debugging easy.
• Player data source np.*: a bind starting with np. bypasses plugin state and reads the built-in player live (np.title, np.artist, np.playlist, np.cover, np.isPlaying, np.isLoading, np.index, np.total, np.currentTime, np.duration, np.progress, np.timeText); read-only — set / extract / settings / list onTap prefixes cannot write to it.
• Layout semantics: pages scroll on overflow by default (a breathing collapse arrow at the bottom hints at more content and flips once you reach the end); fit: true forces a one-screen fit with an adaptive center.
• State persistence: state is written to local UserDefaults on first change (key plugin.state.<id>) and survives app restarts; Plugin Manager can reset it to the initial values.
• Feedback: a glass loading state shows while a request is in flight; failures surface a notice under the header that clears automatically on success.

8. Install & manage

• Location: ~/Library/Application Support/MaciWatch/plugins/<id>.json; you can also drop files in manually — Plugin Manager scans the folder automatically.
• Importing: Plugin Manager → Import at the top right → pick a JSON file or paste the manifest text; the filename doesn't matter — the manifest's own id decides what lands on disk.
• Overwrite & uninstall: re-importing the same id overwrites and reinstalls; Plugin Manager supports deleting and hiding from the Honeycomb (visibility is just a hidden list).
• Built-in examples: Exchange Rates, Hitokoto, and the community-build Now Playing entry are seeded on first launch — modify or delete them freely. Every example manifest declares its permissions explicitly.
• Community shares: the community examples below import directly; share your plugin JSON as a code snippet — the best ones get collected here.

9. Security & validation

• id whitelist: must start with a letter/digit plus A-Z a-z 0-9 . _ -, ≤ 100 chars; path traversal (e.g. ../evil) and symbol-only ids are rejected.
• Web protocols only: Manifest V2 network requests, remote images, and open-url destinations require https://; local schemes such as file:// are always rejected.
• Explicit permissions: import shows every declared capability before anything runs. Network, remote-image, and open-URL scopes restrict requests to the exact host or a declared parent domain; authorization can be revoked at any time and permission changes invalidate old authorization.
• Auto-refresh gate: loading on open or refreshing on a timer requires both networkRequest and autoRefresh.
• Icon validation: every SF Symbol reference in the manifest (header, trailing, body, bottom buttons) must exist in the current system symbol set, or the import is rejected.
• Data boundary: state stays on this Mac and is never uploaded; requests time out after 15 s, and a failure never affects other plugins.