DroppyKit

https://getdroppy.app/docs/droppykit
Admin
DroppyKit is a Swift SDK for developing Droplet extensions that integrate with Droppy's native macOS...
Tokens:137,566
Snippets:1,639
Trust Score:6.1
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### installConfirmationDialogProvider(_:)

Source: https://getdroppy.app/docs/droppykit/api/droppy-kit-surface-bridge

Installs the host's confirmation presenter before loading droplets. The first installation wins, and the presenter must return true only for the explicit confirm action.

```APIDOC
## [INSTALL] installConfirmationDialogProvider(_:)

### Description
Installs the host's confirmation presenter before loading droplets. The first installation wins. The presenter must return `true` only for the explicit confirm action.

### Method
INSTALL

### Endpoint
`installConfirmationDialogProvider(_:)`

### Parameters
#### Function Parameters
- **provider** (`@escaping (String, String, String, String) -> Bool`) - Required - The closure that presents the confirmation dialog and returns a Boolean indicating whether the explicit confirm action was taken.

### Returns
- **Bool** - `true` when this call installed it, `false` when one was already installed and nothing changed.

### Remarks
- Marked `@MainActor` and `@discardableResult`.
- The first installation wins; a droplet loaded after launch cannot replace it.
```

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

### installShortcutRecorderProvider(_:)

Source: https://getdroppy.app/docs/droppykit/api/droppy-kit-surface-bridge

Installs the host's shortcut recorder provider. Intended for host processes only, once, at launch, before any droplet is loaded (DroppyKit 1.14.0).

```APIDOC
## [INSTALL] installShortcutRecorderProvider(_:)

### Description
Installs the host's recorder. **Host processes only**, once, at launch, before any droplet is loaded (DroppyKit 1.14.0).

### Method
INSTALL

### Endpoint
`installShortcutRecorderProvider(_:)`

### Parameters
#### Function Parameters
- **provider** (`@escaping (DroppyShortcutRecorder.Configuration) -> AnyView`) - Required - The closure that takes a shortcut recorder configuration and returns the host's recorder view.

### Returns
- **Bool** - `true` when this call installed it, `false` when one was already installed and nothing changed.

### Remarks
- Marked `@MainActor` and `@discardableResult`.
- The first installation wins; a droplet loaded after launch cannot replace it.
```

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

### installSettingsToolbarSearchProvider(_:)

Source: https://getdroppy.app/docs/droppykit/api/droppy-kit-surface-bridge

Installs the host's Settings toolbar search provider. Intended for host processes only, once, at launch, before any droplet is loaded.

```APIDOC
## [INSTALL] installSettingsToolbarSearchProvider(_:)

### Description
Installs the host's Settings toolbar search: given the page's text and its prompt, the view that makes the host show its native search for them. **Host processes only**, once, at launch, before any droplet is loaded.

### Method
INSTALL

### Endpoint
`installSettingsToolbarSearchProvider(_:)`

### Parameters
#### Function Parameters
- **provider** (`@escaping (Binding<String>, String) -> AnyView`) - Required - The closure that takes a binding to the search text and a prompt string, and returns the host's native search view.

### Returns
- **Bool** - `true` when this call installed it, `false` when one was already installed and nothing changed.

### Remarks
- Marked `@MainActor` and `@discardableResult`.
- The first installation wins; a droplet loaded after launch cannot replace it.
```

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

### DropletSettingsSection usage with Homebrew install command

Source: https://getdroppy.app/docs/droppykit/api/droplet-settings-section

The first snippet shows a SwiftUI section with a custom header and a card, and the second is the Homebrew installation command for Droppy. These are independent examples.

```swift
DropletSettingsSection {
    VStack(alignment: .leading, spacing: 2) {
        settingsSectionHeader("Clocks")
        Text("Shown in the widget, in this order.")
            .font(.body)
            .foregroundStyle(.secondary)
    }
} content: {
    DropletSettingsCard { ... }
}
```

```bash
$brew install --cask droppy
```

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

### installHostExtensionPoints(markdownEditorFactory:contextualMarkdownEditorFactory:markdownHighlightPen:)

Source: https://getdroppy.app/docs/droppykit/api/droppy-kit-host-bridge

Installs the host's extension points. Host processes only. The first call wins and later calls are ignored, so a droplet loaded after launch cannot replace the host's editor or repoint the pen's storage. Hosts must call this once, at launch, before any droplet is loaded.

```APIDOC
## installHostExtensionPoints(markdownEditorFactory:contextualMarkdownEditorFactory:markdownHighlightPen:)

### Description
Installs the host's extension points. Host processes only. The first call wins and later calls are ignored, so a droplet loaded after launch cannot replace the host's editor or repoint the pen's storage. Hosts must call this once, at launch, before any droplet is loaded and given a chance to mount a wrapped component inside `activate(host:)`.

### Method
Static Function

### Signature
`@discardableResult @MainActor static func installHostExtensionPoints(markdownEditorFactory: ((Binding<String>) -> AnyView)? = nil, contextualMarkdownEditorFactory: ((Binding<String>, DroppyMarkdownEditorContext) -> AnyView)? = nil, markdownHighlightPen: (get: () -> DroppyMarkdownHighlightColor, set: (DroppyMarkdownHighlightColor) -> Void)? = nil) -> Bool`

### Parameters
- **markdownEditorFactory** (optional closure) - Optional - Factory for the real markdown editor surface (the 0.2.0 shape: text only). Kept so bundles and hosts built against 0.2.0/0.2.1 are unaffected; `contextualMarkdownEditorFactory` supersedes it and wins when both are installed.
- **contextualMarkdownEditorFactory** (optional closure) - Optional - Factory for the real markdown editor surface, carrying the full context (DroppyKit 0.2.2).
- **markdownHighlightPen** (optional tuple of get and set closures) - Optional - The host's global highlight pen storage. The get closure returns the current pen color, and the set closure sets it.

### Returns
- **Bool** - `true` when this call installed the extension points, `false` when they were already installed and nothing changed.

### Usage Notes
- **Host processes only.**
- The first call wins; later calls are ignored.
- Call once at launch before any droplet is loaded.

### Example
```swift
let installed = DroppyKitHostBridge.installHostExtensionPoints(
    markdownEditorFactory: { binding in
        // Return a view for the markdown editor
        return AnyView(MyMarkdownEditor(binding: binding))
    },
    contextualMarkdownEditorFactory: { binding, context in
        // Return a view for the markdown editor with context
        return AnyView(MyContextualMarkdownEditor(binding: binding, context: context))
    },
    markdownHighlightPen: (
        get: { return .yellow },
        set: { newColor in
            // Store the new pen color
        }
    )
)
```

```

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

### installPanelSurfaceProvider(_:)

Source: https://getdroppy.app/docs/droppykit/api/droppy-kit-surface-bridge

Installs the host's surface provider for panel surfaces. Intended for host processes only, once, at launch, before any droplet is loaded.

```APIDOC
## [INSTALL] installPanelSurfaceProvider(_:)

### Description
Installs the host's surface. **Host processes only**, once, at launch, before any droplet is loaded.

### Method
INSTALL

### Endpoint
`installPanelSurfaceProvider(_:)`

### Parameters
#### Function Parameters
- **provider** (`@escaping (CGFloat) -> AnyView`) - Required - The closure that provides the launcher surface for a given corner radius.

### Returns
- **Bool** - `true` when this call installed it, `false` when one was already installed and nothing changed.

### Remarks
- Marked `@MainActor` and `@discardableResult`.
- The first installation wins; a droplet loaded after launch cannot replace it.
```

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

### installHighlightColorProvider(_:)

Source: https://getdroppy.app/docs/droppykit/api/droppy-kit-theme-bridge

Installs the host's highlight-color provider. This method is intended for host processes only. The provider is called on every themed color read and must be cheap and thread-safe. The first call wins and later calls are ignored.

```APIDOC
## [INSTALL] installHighlightColorProvider(_:)

### Description
Installs the host's highlight-color provider. This method is intended for host processes only. The provider is called on every themed color read and must be cheap and thread-safe. The first call wins and later calls are ignored.

### Method
INSTALL

### Endpoint
installHighlightColorProvider(_:)

### Parameters
#### Parameters
- **provider** (`@escaping @Sendable () -> NSColor`) - Required - The provider closure that returns the highlight color.

### Returns
- **Bool** - `true` when this call installed the provider, `false` when one was already installed and nothing changed.

### Response
#### Success Response (200)
- **Bool** - `true` when this call installed the provider, `false` when one was already installed and nothing changed.

#### Response Example
```json
{
  "installed": true
}
```
```

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

### installProvider(_:)

Source: https://getdroppy.app/docs/droppykit/api/droppy-kit-motion-bridge

Installs the host's motion provider. Host processes only. The provider is called on every bridged preset read and must resolve the host's current animation fresh each time.

```APIDOC
## installProvider(_:)

### Description
Installs the host's motion provider. Host processes only. The provider is called on every bridged preset read and must resolve the host's current animation fresh each time. Caching a value here would freeze a curve the user can still change. The first call wins and later calls are ignored.

### Method
N/A (static function)

### Endpoint
N/A

### Parameters
- **provider** (`@escaping @Sendable (Preset) -> Animation`) - Required - The closure that resolves the host's current animation for a given preset.

### Request Example
N/A

### Response
- **Bool** - `true` when this call installed the provider, `false` when one was already installed and nothing changed.

### Error Handling
N/A
```

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

### installPanelActivationProvider(_:)

Source: https://getdroppy.app/docs/droppykit/api/droppy-kit-surface-bridge

Installs the host's panel activation provider. This is intended for host processes only, once, at launch, before any droplet is loaded (DroppyKit 1.15.0).

```APIDOC
## [INSTALL] installPanelActivationProvider(_:)

### Description
Installs the host's panel activation. **Host processes only**, once, at launch, before any droplet is loaded (DroppyKit 1.15.0).

### Method
INSTALL

### Endpoint
`installPanelActivationProvider(_:)`

### Parameters
#### Function Parameters
- **provider** (`@escaping (NSWindow, NSRunningApplication?) -> DroppyPanelActivation`) - Required - The closure that provides the panel activation for a given window and running application.

### Returns
- **Bool** - `true` when this call installed it, `false` when one was already installed and nothing changed.

### Remarks
- Marked `@MainActor` and `@discardableResult`.
- The first installation wins; a droplet loaded after launch cannot replace it.
```

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

### Submit droplet with droppykit submit

Source: https://getdroppy.app/docs/droppykit/submitting

Install glab, authenticate, then run droppykit submit. It forks the Store repo, copies your package, generates CODEOWNERS, commits on a branch, pushes, and opens a merge request.

```bash
brew install glab && glab auth login    # once
droppykit submit
```

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

### init(surface:availableWidth:)

Source: https://getdroppy.app/docs/droppykit/api/live-activity-context

Creates a context with the given surface and available width. This is the legacy ABI entry point that supplies the same settled presentation old hosts implicitly provided.

```APIDOC
## init(surface:availableWidth:)

### Description
Creates a context with the specified surface kind and available width. This initializer is the legacy ABI entry point and supplies the same settled presentation that old hosts implicitly provided.

### Method
Initializer

### Parameters
- **surface** (DropletSurfaceKind) - Required - The surface kind hosting the activity.
- **availableWidth** (CGFloat) - Required - The width the card's content is given, inside the host's insets.

### Notes
This initializer is constructed by hosts and read by droplets. It provides the same presentation state as the legacy ABI entry point.
```

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

### init(surface:availableWidth:presentation:)

Source: https://getdroppy.app/docs/droppykit/api/live-activity-context

Creates a context with the current host presentation state, including surface, available width, and presentation details.

```APIDOC
## init(surface:availableWidth:presentation:)

### Description
Creates a context with the specified surface kind, available width, and current host presentation state. This initializer allows the host to pass explicit presentation information.

### Method
Initializer

### Parameters
- **surface** (DropletSurfaceKind) - Required - The surface kind hosting the activity.
- **availableWidth** (CGFloat) - Required - The width the card's content is given, inside the host's insets.
- **presentation** (LiveActivityPresentationState) - Required - The current host presentation state.

### Notes
This initializer is constructed by hosts and read by droplets. It provides the current presentation state for the live activity.
```

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

### Install Droppy via Homebrew

Source: https://getdroppy.app/docs/droppykit/add-spm

Use this command in Terminal to install Droppy from the official Homebrew cask. The app keeps itself up to date after installation.

```bash
$ brew install --cask droppy
```

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

### DropletManifest JSON Example

Source: https://getdroppy.app/docs/droppykit/api/droplet-manifest

Example JSON structure for a DropletManifest, showing all fields including id, name, version, summary, category, kit, minAppVersion, capabilities, surfaces, icon, creator, and source.

```json
{
  "id": "worldclock",
  "name": "World Clock",
  "version": "1.0.0",
  "summary": "Every timezone you care about, on the shelf",
  "category": "Productivity",
  "kit": { "abi": 1, "minAPI": "1.0.0" },
  "minAppVersion": "15.3.0",
  "capabilities": ["shelf-read"],
  "surfaces": ["shelf-widget", "settings-pane"],
  "icon": "WorldClock.icon",
  "creator": {
    "name": "Jane Doe",
    "kind": "community",
    "url": "https://jane.example",
    "avatar": "Creator.png"
  },
  "source": {
    "repository": "https://github.com/jane/worldclock-droplet",
    "commit": "9f1c2ab5c0e4d3f6a7b8c9d0e1f2a3b4c5d6e7f8",
    "license": "MIT"
  }
}
```

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

### isProviderInstalled

Source: https://getdroppy.app/docs/droppykit/api/droppy-kit-motion-bridge

A static property indicating whether a host installed a motion provider.

```APIDOC
## isProviderInstalled

### Description
A static property indicating whether a host installed a motion provider. Returns `false` in normal states outside Droppy (previews, harness), where bridged presets use standalone formulas.

### Method
N/A (static property)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
- **Bool** - `true` if a provider is installed, `false` otherwise.

### Error Handling
N/A
```

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

### init(header:content:)

Source: https://getdroppy.app/docs/droppykit/api/droplet-settings-section

Creates a DropletSettingsSection with a header view and content view builder.

```APIDOC
## [INIT] init(header:content:)

### Description
Creates a section from its header and its content.

### Method
INIT

### Parameters
#### Parameters
- **header** (ViewBuilder) - Required - A view builder that produces the header view.
- **content** (ViewBuilder) - Required - A view builder that produces the content view.

### Request Example
```swift
DropletSettingsSection {
    VStack(alignment: .leading, spacing: 2) {
        settingsSectionHeader("Clocks")
        Text("Shown in the widget, in this order.")
            .font(.body)
            .foregroundStyle(.secondary)
    }
} content: {
    DropletSettingsCard { ... }
}
```

### Response
#### Success Response (200)
- **body** (some View) - The body of the section.

#### Response Example
```swift
// The view representing the section.
```
```

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

### grantedCapabilities

Source: https://getdroppy.app/docs/droppykit/api/droplet-host

Provides the set of capabilities the user granted this droplet at install time.

```APIDOC
## grantedCapabilities

### Description
The capabilities the user granted this droplet at install time.

### Property
`@MainActor let grantedCapabilities: Set<DropletPermission>`

### Access
- **Type**: Read-only property
- **Availability**: Always available

```

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

### init()

Source: https://getdroppy.app/docs/droppykit/api/droppy-markdown-editor-commands

Creates an unbound command bus.

```APIDOC
## init()

### Description
Creates an unbound command bus.

### Method
N/A (Initializer)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
#### Success Response
N/A

#### Response Example
N/A

### Error Handling
N/A
```

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

### icon(inBundleAt:pixelSize:)

Source: https://getdroppy.app/docs/droppykit/api/droplet-icon-renderer

Returns the icon of an installed `.droplet` bundle, or nil when it ships none.

```APIDOC
## [STATIC METHOD] icon(inBundleAt:pixelSize:)

### Description
Returns the icon of an installed `.droplet` bundle, or `nil` when it ships none. A bundle carries its Icon Composer document under `Contents/Resources` as `<Name>.icon`, which is a directory. `Bundle.url(forResource:)` finds it by extension without the caller having to know the name the droplet chose.

### Method
Static method

### Signature
`static func icon(inBundleAt bundleURL: URL, pixelSize: CGFloat = 512) -> NSImage?`

### Parameters
- **bundleURL** (URL) - Required - The URL of the installed `.droplet` bundle.
- **pixelSize** (CGFloat) - Optional - The desired pixel size for the icon. Defaults to `512`.

### Return Value
- **NSImage?** - The icon image, or `nil` if the bundle ships none.
```

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

### init(_:)

Source: https://getdroppy.app/docs/droppykit/api/settings-info-tip

Creates a SettingsInfoTip with the specified popover text.

```APIDOC
## init(_:)

### Description
Creates a tip with its popover text.

### Declaration
`@MainActor init(_ text: String)`

### Parameters
- **text** (String) - The text to display in the popover.

```

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

### creatorAvatar(inBundleAt:)

Source: https://getdroppy.app/docs/droppykit/api/droplet-icon-renderer

Returns the creator's avatar from an installed bundle, or nil when it ships none.

```APIDOC
## [STATIC METHOD] creatorAvatar(inBundleAt:)

### Description
Returns the creator's avatar from an installed bundle, or `nil` when it ships none. The submission rules require one, so `nil` here means a bundle that predates the rule or was assembled by hand.

### Method
Static method

### Signature
`static func creatorAvatar(inBundleAt bundleURL: URL) -> NSImage?`

### Parameters
- **bundleURL** (URL) - Required - The URL of the installed bundle.

### Return Value
- **NSImage?** - The creator's avatar image, or `nil` if the bundle ships none.
```

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

### init(size:)

Source: https://getdroppy.app/docs/droppykit/api/droppy-quiet-button-style

Creates the style with a specified size, defaulting to .medium.

```APIDOC
## init(size:)

### Description
Creates the style with a specified size, defaulting to .medium.

### Method
init

### Parameters
#### Parameters
- **size** (DroppyButtonSize) - Optional - The size of the button. Defaults to .medium.

### Request Example
```swift
DroppyQuietButtonStyle()
```

### Response
#### Success Response
- No return value.

#### Response Example
```swift
// No return value
```
```

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

### DroppyShortcutRecorder usage example

Source: https://getdroppy.app/docs/droppykit/api/droppy-shortcut-recorder

Initializes a DroppyShortcutRecorder bound to a shortcut and checks if a chord is already taken using the isTaken closure.

```swift
DroppyShortcutRecorder(
    shortcut: $model.shortcut,
    isTaken: { model.isAlreadyBound($0) }
)
```

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

### init(id:systemImage:text:detail:roundedCenterText:roundedBottomText:progress:)

Source: https://getdroppy.app/docs/droppykit/api/lock-screen-status-entry

Creates a LockScreenStatusEntry with the given parameters. Everything past `text` is optional chip payload; omitting all of it produces the plain horizontal strip entry. This is the original ABI entry point.

```APIDOC
## init(id:systemImage:text:detail:roundedCenterText:roundedBottomText:progress:)

### Description
Creates a LockScreenStatusEntry with the given parameters. Everything past `text` is optional chip payload; omitting all of it produces the plain horizontal strip entry. This is the original ABI entry point.

### Method
init

### Parameters
#### Parameters
- **id** (String) - Required - Stable identifier within the droplet.
- **systemImage** (String) - Required - SF Symbol shown in the strip.
- **text** (String) - Required - Short status text, for example a remaining time.
- **detail** (String?) - Optional - Secondary label beside `text` in the horizontal strip style, for example a mode name. `nil` shows the primary text alone.
- **roundedCenterText** (String?) - Optional - Compact value rendered inside the ring in the rounded strip style. `nil` falls back to the SF Symbol.
- **roundedBottomText** (String?) - Optional - Caption under the ring in the rounded strip style. `nil` falls back to `text`.
- **progress** (Double?) - Optional - Ring progress in `0...1` for the rounded strip style, for example a timer's remaining fraction. `nil` draws the idle arc.

### Discussion
Keep its exact symbol and infer cadence from ring progress so pre-cadence droplets retain their behavior.
```

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

### init(_:)

Source: https://getdroppy.app/docs/droppykit/api/droplet-live-activity-yield-reason

Creates a reason from a raw string.

```APIDOC
## init(_:)

### Description
Creates a reason from a raw string.

### Method
init

### Parameters
#### Parameters
- **rawValue** (String) - Required - The raw reason string.

### Request Example
```swift
let reason = DropletLiveActivityYieldReason("someRawValue")
```

### Response
#### Success Response
No response body.

#### Response Example
No response body.
```

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

### Activate launcher and index catalog in Swift

Source: https://getdroppy.app/docs/droppykit/launchers

Declare the `launcher` capability and `minAPI` 1.12.0 in `droplet.json`, then read `launcher` in `activate(host:)`. Guard `isAvailable`, index the catalog, and refresh on `catalogDidChange` to keep search results current.

```swift
func activate(host: DropletHost) throws {
    let launcher = host.launcher
    guard launcher.isAvailable else { return }
    index(launcher.catalog)
    cancellable = launcher.catalogDidChange.sink { [weak self] in
        self?.index(launcher.catalog)
    }
}
```

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

### init(stringLiteral:)

Source: https://getdroppy.app/docs/droppykit/api/droplet-live-activity-yield-reason

String-literal convenience initializer.

```APIDOC
## init(stringLiteral:)

### Description
String-literal convenience initializer.

### Method
init

### Parameters
#### Parameters
- **value** (String) - Required - The string literal value.

### Request Example
```swift
let reason: DropletLiveActivityYieldReason = "someRawValue"
```

### Response
#### Success Response
No response body.

#### Response Example
No response body.
```

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

### activate(host:)

Source: https://getdroppy.app/docs/droppykit/api/droplet

Called once per launch when the droplet is installed, enabled, and not removed. Store the host value for accessing host functionality.

```APIDOC
## [METHOD] activate(host:)

### Description
Called once per launch when the droplet is installed, enabled, and not removed, after the host's own managers are up. Store the `host` value; it is the only sanctioned way to reach host functionality.

### Method
activate

### Parameters
#### Parameters
- **host** (DropletHost) - Required - The host object providing access to host functionality.

### Throws
Throwing from `activate` marks the droplet failed for this session; the host calls `deactivate` to clean up partial activation.

### Response
No return value.
```

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

### Log with DropletLogService

Source: https://getdroppy.app/docs/droppykit/droplet-setup

Use DropletLogService instead of print, since print from inside an installed app goes nowhere a user or reviewer can find.

```swift
host.log.info("activated for \(zone)")
```

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

### installSettingsToolbarPillProvider(_:)

Source: https://getdroppy.app/docs/droppykit/api/droppy-kit-surface-bridge

Installs the host's Settings toolbar pill provider. Intended for host processes only, once, at launch, before any droplet is loaded (DroppyKit 1.18.0).

```APIDOC
## [INSTALL] installSettingsToolbarPillProvider(_:)

### Description
Installs the host's Settings toolbar pill. **Host processes only**, once, at launch, before any droplet is loaded (DroppyKit 1.18.0).

### Method
INSTALL

### Endpoint
`installSettingsToolbarPillProvider(_:)`

### Parameters
#### Function Parameters
- **provider** (`@escaping (AnyView) -> AnyView`) - Required - The closure that wraps a control with the host's toolbar pill.

### Returns
- **Bool** - `true` when this call installed it, `false` when one was already installed and nothing changed.

### Remarks
- Marked `@MainActor` and `@discardableResult`.
- The first installation wins; a droplet loaded after launch cannot replace it.
```

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

### DropletSettingsToolbarButton usage example

Source: https://getdroppy.app/docs/droppykit/api/droplet-settings-toolbar-button

Creates a toolbar button with the title "New prompt" and a plus system image, triggering the action when tapped.

```swift
DropletSettingsToolbarButton("New prompt", systemImage: "plus") {
    model.addPrompt()
}
```

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

### init(_:subtitle:page:icon:)

Source: https://getdroppy.app/docs/droppykit/api/droplet-settings-page-link

Creates a DropletSettingsPageLink whose tile is an icon image drawn at 28 points.

```APIDOC
## init(_:subtitle:page:icon:)

### Description
Creates a link whose tile is an icon image, drawn at 28 points.

### Declaration
`@MainActor init(_ title: String, subtitle: String? = nil, page id: String, icon: NSImage?)`

### Parameters
- **title** (String) - Required - The title text displayed on the row.
- **subtitle** (String?) - Optional - A secondary subtitle displayed below the title. Defaults to nil.
- **page** (String) - Required - The identifier of the settings page to open.
- **icon** (NSImage?) - Required - The icon image used for the tile. If nil, no icon is shown.

### Discussion
Use this initializer when you have an icon image (e.g., from an Icon Composer export) to display as the tile. The icon is drawn at 28 points.

### Example
```swift
DropletSettingsPageLink("Clocks", subtitle: "Which cities, in which order.", page: "clocks", icon: clocksIcon)
```
```

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

### creator.avatar manifest entry

Source: https://getdroppy.app/docs/droppykit/icons

Example creator object for the droplet manifest. The avatar field names a square PNG in Assets/ that is clipped to a circle by every surface.

```json
"creator": {
  "name": "Jane Doe",
  "kind": "community",
  "url": "https://jane.example",
  "avatar": "Creator.png"
}

```

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

### init(prominence:)

Source: https://getdroppy.app/docs/droppykit/api/droppy-live-activity-control-style

Creates an inline live-activity control style with a specified prominence level.

```APIDOC
## init(prominence:)

### Description
Creates an inline live-activity control style.

### Method
Initializer

### Signature
`@MainActor init(prominence: DroppyLiveActivityControlProminence = .quiet)`

### Parameters
- **prominence** (DroppyLiveActivityControlProminence) - Optional - The prominence level for the control style. Defaults to `.quiet`.

### Return Value
A new instance of `DroppyLiveActivityControlStyle`.

```

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

### expandedSurfaceProvider

Source: https://getdroppy.app/docs/droppykit/api/expanded-surface-hosting

The property that a droplet conforming to ExpandedSurfaceHosting must implement to provide an expanded surface. The host reads this property to get the provider, or nil if no surface is currently offered.

```APIDOC
## Property: expandedSurfaceProvider

### Description
The provider of the expanded surface, or `nil` when the droplet currently offers no expanded surface. Re-read after every state-change broadcast.

### Declaration
`@MainActor var expandedSurfaceProvider: (any ExpandedSurfaceProviding)? { get }`

### Return Value
An optional `ExpandedSurfaceProviding` instance, or `nil` if no expanded surface is currently available.

### Discussion
This property is the discovery point for the host. A droplet that would rather implement the provider on itself returns `self`.

### Example
```swift
public final class DictationDroplet: Droplet, ExpandedSurfaceHosting {
    public static let id: DropletID = "dictation"
    private var session: DictationSession?

    public func activate(host: DropletHost) throws { session = DictationSession(host: host) }
    public func deactivate() { session = nil }

    public var expandedSurfaceProvider: (any ExpandedSurfaceProviding)? { session }
}
```
```

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

### init(shape:fill:isHovering:isPressed:)

Source: https://getdroppy.app/docs/droppykit/api/droppy-glass-control-chrome

Creates the chrome with the specified shape, fill, and interaction states.

```APIDOC
## INIT(shape:fill:isHovering:isPressed:)

### Description
Creates the chrome for the Liquid Glass control with the given shape, fill, and interaction states.

### Method
Initializer

### Parameters
- **shape** (AnyShape) - Required - The shape of the control.
- **fill** (DroppyGlassControl.Fill) - Optional - The fill style, defaults to .veil.
- **isHovering** (Bool) - Optional - Whether the control is being hovered, defaults to false.
- **isPressed** (Bool) - Optional - Whether the control is being pressed, defaults to false.

### Request Example
```swift
DroppyGlassControlChrome(shape: AnyShape(Capsule()), fill: .veil, isHovering: false, isPressed: false)
```

### Response
No return value.
```

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

### init(preferredSoloWidth:preferredPairedWidth:pairWeight:minimumWidth:contentHeight:)

Source: https://getdroppy.app/docs/droppykit/api/shelf-widget-layout-traits

Creates layout traits for a shelf widget. Widths are optional for compatibility, but current hosts require explicit solo and paired widths.

```APIDOC
## init(preferredSoloWidth:preferredPairedWidth:pairWeight:minimumWidth:contentHeight:)

### Description
Creates layout traits for a shelf widget. The optional width defaults preserve existing call sites, but a current Droppy host refuses a descriptor unless both `preferredSoloWidth` and `preferredPairedWidth` are explicit.

### Signature
```swift
init(preferredSoloWidth: CGFloat? = nil, preferredPairedWidth: CGFloat? = nil, pairWeight: Double = 1, minimumWidth: CGFloat? = nil, contentHeight: ShelfWidgetContentHeight = .standard)
```

### Parameters
- **preferredSoloWidth** (CGFloat?) - Optional - Preferred width when the widget is shown alone.
- **preferredPairedWidth** (CGFloat?) - Optional - Preferred width when the widget shares a row with one to three other widgets.
- **pairWeight** (Double) - Optional - Relative weight when the shelf splits space across a grouped row. Default is 1.
- **minimumWidth** (CGFloat?) - Optional - Hard minimum width of the card in points.
- **contentHeight** (ShelfWidgetContentHeight) - Optional - Card height request. Default is `.standard`.

### Discussion
Current Droppy hosts refuse a widget descriptor unless both `preferredSoloWidth` and `preferredPairedWidth` are explicit. `minimumWidth` and `contentHeight` retain their ordinary host defaults.
```

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

### openSettings()

Source: https://getdroppy.app/docs/droppykit/api/droplet-workspace-service

Opens Droppy's Settings on this droplet's own page, where the SettingsPaneProviding pane is drawn. Returns false if the host refuses, for example for a droplet without a settings pane.

```APIDOC
## openSettings()

### Description
Opens Droppy's Settings on this droplet's own page, the one your `SettingsPaneProviding` pane is drawn on. For the "Set up" button on a widget that has nothing to show until the user configures it. The window comes forward on its own; the shelf is left to close the way it normally does once the pointer leaves it. Needs DroppyKit 1.5.0: declare `minAPI` 1.5.0. Returns `false` when the host refused, for example for a droplet without a settings pane.

### Method
`@discardableResult @MainActor func openSettings() -> Bool`

### Return Value
- **Bool** - `true` if the settings page was opened; `false` if the host refused.
```

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

### static func isValid(_:)

Source: https://getdroppy.app/docs/droppykit/api/droplet-id

Whether `rawValue` is a usable droplet id. The rule: 3 to 40 characters, ASCII letters, digits and hyphens only, starting with a letter and ending with a letter or digit.

```APIDOC
## static func isValid(_:)

### Description
Whether `rawValue` is a usable droplet id. The rule: 3 to 40 characters, ASCII letters, digits and hyphens only, starting with a letter and ending with a letter or digit.

### Signature
`static func isValid(_ rawValue: String) -> Bool`

### Parameters
- **rawValue** (String) - The string to validate.

### Returns
A Boolean indicating whether the string is a valid droplet id.

```

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

### init(size:destructive:solidFill:foregroundColorOverride:)

Source: https://getdroppy.app/docs/droppykit/api/droppy-circle-button-style

Creates the style with additional customization options for destructive actions, solid fill, and foreground color override.

```APIDOC
## init(size:destructive:solidFill:foregroundColorOverride:)

### Description
Creates the style with the host's other arms, allowing customization of size, destructive behavior, solid fill, and foreground color override.

### Method
init

### Parameters
#### Parameters
- **size** (CGFloat) - Required - Diameter in points.
- **destructive** (Bool) - Required - A delete, remove or forget: the glyph is red on the same neutral glass, so the one control on a row that takes something away reads as such. Never for a close or a reset.
- **solidFill** (Color?) - Optional - When set, the disc is this exact opaque colour instead of glass (a classic black puck, a success flash) and the glyph takes contrast ink.
- **foregroundColorOverride** (Color?) - Optional - The glyph colour, when the label must not take the ink the fill chooses (the File Tray's orange pin).

### Request Example
```swift
DroppyCircleButtonStyle(size: 20, destructive: true, solidFill: .red, foregroundColorOverride: .white)
```

### Response
#### Success Response
- **DroppyCircleButtonStyle** - The created style instance.

#### Response Example
```swift
DroppyCircleButtonStyle(size: 20, destructive: true, solidFill: .red, foregroundColorOverride: .white)
```
```

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

### init(content:)

Source: https://getdroppy.app/docs/droppykit/api/droplet-settings-page

Creates a DropletSettingsPage from its sections and cards. Use this initializer to build the page with a view builder containing DropletSettingsSection and DropletSettingsCard views.

```APIDOC
## init(content:)

### Description
Creates a page from its sections and cards.

### Method
Initializer

### Signature
`@MainActor init(@ViewBuilder content: () -> Content)`

### Parameters
- **content** (closure) - Required - A view builder that produces the sections and cards for the page.

### Example
```swift
DropletSettingsPage {
    DropletSettingsSection {
        settingsSectionHeader("Cities")
    } content: {
        DropletSettingsCard { ... }
    }
}
```
```

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

### installState

Source: https://getdroppy.app/docs/droppykit/api/droplet-host

Provides information about which of this droplet's pieces the user has switched on.

```APIDOC
## installState

### Description
Which of this droplet's pieces the user has switched on.

### Property
`@MainActor let installState: any DropletInstallStateService`

### Access
- **Type**: Read-only property
- **Availability**: Always available

```

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

### isHighlightColorProviderInstalled

Source: https://getdroppy.app/docs/droppykit/api/droppy-kit-theme-bridge

A static property that indicates whether a host installed a highlight provider. Returns `false` in the normal state outside Droppy (previews, the harness), where the tokens fall back to the system accent.

```APIDOC
## [GET] isHighlightColorProviderInstalled

### Description
A static property that indicates whether a host installed a highlight provider. Returns `false` in the normal state outside Droppy (previews, the harness), where the tokens fall back to the system accent.

### Method
GET

### Endpoint
isHighlightColorProviderInstalled

### Parameters
None

### Response
#### Success Response (200)
- **Bool** - `true` if a highlight provider is installed, `false` otherwise.

#### Response Example
```json
{
  "installed": false
}
```
```
Tokens:
Raw