API reference

Every public type in DroppyKit, 172 of them, grouped by what they are for.

Read straight from the compiler’s symbol graph, so a type that is not on this page is not in the module.

The droplet

What every droplet is built out of.

DropletThe runtime object representing one droplet inside the host process. DropletIDStable identifier of a droplet across the whole system. DropletHostEverything the host offers a droplet. DropletURLHandlingAdopt to receive URLs opened at droppy://droplet/<your-id>/…. DropletURLRequestA URL Droppy received on a droplet's behalf.

Shelf widgets

A card on the expanded shelf, alone or sharing the row.

ShelfWidgetProvidingAdopt to contribute one or more widgets to the notch shelf. ShelfWidgetDynamicLayoutProvidingOptional live-layout refinement for a shelf widget provider. ShelfWidgetDescriptorStatic description of one shelf widget, rendered by the host without calling into the widget's views. ShelfWidgetContextContext passed to widget view factories on every mount. ShelfWidgetIDStable identifier of one shelf widget a droplet provides. ShelfWidgetLayoutTraitsDeclarative layout parameters for one shelf widget. ShelfWidgetContentHeightHow tall the widget's card should be inside the shelf. ShelfWidgetFocusPolicyWhether the widget participates in shelf keyboard focus. ShelfWidgetPlacementA widget's horizontal position within its shelf row. ShelfWidgetPrewarmPolicyWhether the shelf may mount the widget invisibly ahead of time. ShelfWidgetNotchWrapTraitsHow a widget's header row wraps around the camera, declared in notchWrap. ShelfWidgetNotchWrapThe bands beside the camera for a widget the host wrapped around the notch, handed down in notchWrap.

Live activities

A compact row beside the notch, and its detail.

LiveActivityProvidingAdopt to show a compact live activity in the notch or island: small leading and trailing accessories beside the (simulated) notch. LiveActivityStateState of a droplet's compact live activity. LiveActivityContextStructure LiveActivityPresentationStateContext passed to makeExpanded(context:). CompactLiveActivityContextContext passed to the seat-aware compact factories (DroppyKit 0.7.0). CompactLiveActivityPresentationMetadataOpaque host-facing metadata for a compact live activity's leading accessory.

Expanded surfaces

A takeover on the notch.

ExpandedSurfaceProvidingA provider of expanded surfaces: content, size, and the far end of the host's lifecycle. ExpandedSurfaceHostingAdopt to take the expanded shelf over with your own content. ExpandedSurfaceDescriptorStatic description of one expanded surface, readable by the host without mounting anything. ExpandedSurfaceContextWhat the host tells expanded-surface content about its mount. ExpandedSurfaceIDStable identifier of one expanded surface a droplet provides. ExpandedSurfacePresentationOne live presentation of an expanded surface, as the host records it. ExpandedSurfacePresentationRequestA request to take the expanded shelf over with one of your surfaces. ExpandedSurfaceSizeProposalWhat the host offers before asking a droplet how big its surface wants to be. ExpandedSurfaceHostSuppressionWhich of the host's own expanded-shelf behaviors stand down while a takeover is on screen. ExpandedSurfaceDismissalReasonWhy an expanded surface stopped being presented.

Other surfaces

Settings, the lock screen, the menu bar, HUDs.

SettingsPaneProvidingAdopt to contribute a settings pane to the Droplets shop detail page and to embedded settings surfaces. SettingsPaneContextContext passed to makeSettingsPane(context:). SettingsPanePresentationWhere a settings pane is being presented. SettingsPagesProvidingAdopt to give your droplet's Settings page pages of its own (DroppyKit 1.13.0). DropletSettingsPageLinkA row that opens one of your droplet's own Settings pages (DroppyKit 1.13.0). DropletSettingsPageIconA link row's tile from an image: the image at the tile's size, with high quality interpolation, or nothing when there is none (DroppyKit 1.13.0). DropletSettingsPageThe root of one of your droplet's own Settings pages (DroppyKit 1.13.0). DropletSettingsPageOpenerHow a DropletSettingsPageLink asks the host for a page (DroppyKit 1.13.0). HUDPresentingMarker capability for droplets that present transient HUDs. LockScreenStatusProvidingAdopt to publish a status entry on Droppy's lock screen surface. LockScreenStatusEntryOne entry in the lock screen status widget strip. MenuBarExtraProvidingAdopt to contribute a menu bar extra. MenuBarExtraDescriptorStatic description of a menu bar extra a droplet contributes. DropletSurfaceKindThe kind of surface a droplet view is currently rendered on.

Host services

Everything a droplet can ask Droppy to do.

DropletPreferencesServicePersistent, droplet-scoped settings. DropletEnvironmentServiceRead-only facts about the host and the machine it is running on. DropletHUDServicePresents transient HUDs on the notch surface. DropletHUDRequestA transient HUD to show in the notch. DropletHUDPriorityHow loudly a HUD asks for attention. DropletShelfServiceOpens and closes Droppy's shelf, and reveals this droplet's widgets in it. DropletLiveActivityServiceDrives this droplet's live activity. DropletLiveActivitySeatWhere a droplet's activity currently sits (DroppyKit 0.6.0). DropletLiveActivityYieldReasonWhy a droplet's activity is not holding the compact slot (DroppyKit 0.6.0). DropletNotchSurfaceServicePresents and dismisses expanded (takeover) surfaces on the notch. DropletShortcutsServiceRegisters global keyboard shortcuts the user can rebind in Droppy's Settings, Shortcuts page. DropletKeyboardShortcutA key equivalent, as the user recorded it. ShortcutsProvidingA droplet whose own shortcuts Droppy lists on its Shortcuts page, in a section with the droplet's name and icon. DropletShortcutEntryOne shortcut a droplet keeps itself, listed on Droppy's Shortcuts page. DropletWorkspaceServiceThings a droplet can ask the system to do on the user's behalf. DropletFeedbackServicePlays Droppy's own sound and haptic feedback, so a droplet feels like the rest of the app instead of inventing its own vocabulary. DropletFeedbackCueOne of the host's own feedback cues. DropletPermissionsServiceChecks and requests the macOS permissions behind a capability. DropletPermissionStatusWhether the host currently holds a system permission. DropletInstallStateServiceReports what the user has switched on, so a droplet can avoid doing work for a widget nobody is showing. DropletInstallStateWhich of this droplet's pieces the user currently has switched on. DropletLogServiceWrites into Droppy's own log stream, tagged with the droplet id. DropletLogLevelSeverity of a droplet log line. DropletNotchGeometryHow the notch surface is physically shaped on one display. DropletExpandedShelfStateWhat the host's expanded shelf is currently showing. DropletSurfaceAppearanceThe appearance Droppy is drawing its surfaces in. DroppyKitHostBridgeExtension points a host process installs into DroppyKit at launch.

Launchers

Droppy's commands, droplets, settings and content, for a launcher.

DropletLauncherServiceDroppy's commands, settings, droplets and content, for a droplet that draws a launcher. DropletUnavailableLauncherServiceThe service a host without a launcher bridge, or a droplet without the launcher capability, is given. DropletLauncherItemOne thing Droppy offers a launcher: a command, a settings page, a droplet, a note, a clipboard entry, a web answer. DropletLauncherIconHow a launcher draws an item's icon. DropletLauncherActionSomething that can be done with an item. DropletLauncherOutcomeWhat the launcher does after the host ran an action. DropletLauncherDetailContextWhat a detail surface is given by the launcher that shows it. DroppyPanelSurfaceDroppy's own launcher surface, for a droplet that draws a floating panel of its own: a launcher, a palette, a picker. DroppyKitSurfaceBridgeWhere DroppyPanelSurface gets the host's own surface. DroppyShortcutRecorderDroppy's own shortcut recorder, for a droplet that keeps shortcuts of its own (DroppyKit 1.14.0). DroppyPanelActivationDroppy made the active app while a droplet's own floating panel is up, and the foreground handed back when it closes (DroppyKit 1.15.0).

Tools for AI apps

Actions an AI app can run through Droppy's MCP server.

MCPToolProvidingAdopt to offer typed tools to AI apps through Droppy's MCP server (DroppyKit 1.21.0). DropletMCPToolOne action a droplet offers to AI apps through Droppy's MCP server.

Manifest and bundle

What ships, and what the host reads before it loads.

DropletManifestThe contents of a droplet's droplet.json. DropletManifestErrorWhy a droplet.json was refused. DropletCreatorWho made a droplet. DropletCreatorAvatarThe rules a creator avatar has to satisfy. DropletCategoryThe shelf of the Store a droplet sits on. DropletSourceWhere a droplet's source lives. DropletSurfaceA surface a droplet says it provides. DropletKitRequirementWhich DroppyKit a droplet was built against. DropletPermissionCapability strings a .droplet declares under DroppyPermissions in its Info.plist. DropletIconThe rules a droplet's icon has to satisfy. DropletIconRendererEnumeration DropletIconErrorWhy an Icon Composer document was refused. DropletIconValidationChecks an Icon Composer document without rendering it. DroppyIconStyleOne of the six ways macOS 26 and later draws an app icon, plus the tint. DroppyIconStyleObserverThe user's icon style, kept current. DroppySystemIconRendererDraws an icon the way the Dock does, in any DroppyIconStyle, through the system's own icon renderer. DropletBundleInfoParsed metadata of one .droplet bundle, read from its Info.plist without loading any code. DropletBundleInfoErrorErrors thrown while reading a .droplet's metadata. DropletInfoPlistKeyInfo.plist keys of a .droplet bundle.

Surface geometry

The shapes and sizes Droppy draws its surfaces at.

DroppyNotchShellShapeThe U-shaped shell Droppy's notch surface is drawn in. DroppyShellMetricsThe geometry Droppy draws its surfaces at.

Design system

Droppy's own tokens, rows and controls.

AdaptiveColorsSemantic color palette for droplet UI. DroppySpacingStandardized spacing values on a 4pt grid. DroppyRadiusStandardized corner radius values (tiered radii standard). DroppyOpacityStandardized opacity values for consistent layering. DroppyAnimationDroppy's named animation presets. DroppyKitMotionBridgeHost-installed motion hooks. DroppyTransitionThe content transitions Droppy's own notch surfaces use (DroppyKit 1.8.0). DroppyLiveActivityMetricsNative metrics for compact and interactive live-activity rows. DroppySettingsControlMetricsShared metric constants for settings rows. DroppySettingsLayoutMetricsShared layout metrics for settings rows and cards. DroppyAccentButtonStyleThe accent pill for a primary action: Liquid Glass with the accent washed over it (0.18 at rest, 0.24 under the pointer, 0.30 pressed) and the adaptive label ink, exactly the host's DroppyAccentButtonStyle. DroppyQuietButtonStyleThe quiet pill for a secondary action: plain Liquid Glass with the adaptive label ink, the host's DroppyPillButtonStyle. DroppyCircleButtonStyleThe circular icon button for an icon-only action: the Liquid Glass disc the File Tray puts on an item (remove, pin) and the shelf's floating close chip, the host's DroppyCircleButtonStyle. DroppyButtonChromeNeutral chrome fill shared by Droppy's quiet filled control family. DroppyButtonSizeSize variants of the Droppy button family. DroppyGlassControlThe Liquid Glass control recipe: the fill vocabulary, the ink, and the wash for one state. DroppyGlassControlChromeThe Liquid Glass control as a modifier, so a style with its own sizing (the pill family, the disc) and a Menu label (which cannot take a ButtonStyle) draw the identical control. DroppyGlassButtonStyleThe glass control as a button style for labels that size themselves: shape and fill in, the ink from the fill unless the label sets its own (an accent glyph, red for a destructive action). DroppyLiveActivityControlStyleA 24pt circular control matching Droppy's collapsed media interaction. DroppyLiveActivityControlProminenceVisual prominence for an inline live-activity control. DroppyWashCircleButtonStyleThe circular control of Droppy's timer widgets: a flat wash, a semibold glyph, and the 0.94 press. DroppyWashPillButtonStyleThe labelled control of Droppy's timer widgets: Pomodoro's Start Timer pill and its Focus and Break pills, a flat wash under rounded semibold type. DroppyWashToneWhat a wash control carries: nothing but the white, or a colour. DropletSettingsPaneThe root of a droplet's settings pane (DroppyKit 1.9.0). DropletSettingsSectionA titled group of rows inside a DropletSettingsPane (DroppyKit 1.9.0). DropletSettingsCardCard wrapper for grouping settings rows. DropletSettingsDividerDivider between ordinary rows inside a DropletSettingsCard. DropletControlRowBase settings row: title with optional icon and info tip on the left, any accessory control on the right. DropletToggleRowStandard toggle row: title and info tip on the left, small switch on the right. DropletMiniToggleRowCompact nested toggle row for stacked rules and reorder lists. DropletStackedRowRow whose content stacks beneath the title block instead of trailing on the right. DropletSliderRowStandard slider row: title on the left, slider and click-to-type value pill on the right, on one line like a System Settings slider. DropletGroupedPickerRowTitle and info tip above a picker, inset evenly inside the native card. DropletValuePillThe read-only value of a settings row. DropletSettingsToolbarPillDroppy's Liquid Glass pill for the Settings toolbar, drawn by the host (DroppyKit 1.18.0). DropletSettingsToolbarButtonOne action of a page, as a pill in Droppy's Settings toolbar (DroppyKit 1.18.0): "New item", "Add application". DropletSettingsToolbarMenuA pill in Droppy's Settings toolbar that opens a menu (DroppyKit 1.18.0): "Add" with what can be added, a sort order, or what can be done to the page's subject as a whole. DropletSettingsToolbarMenuItemOne row of a DropletSettingsToolbarMenu (DroppyKit 1.18.0): an action, a separator, or a small section title. DropletSettingsToolbarSearchFieldA search over the page, as a pill in Droppy's Settings toolbar (DroppyKit 1.18.0). DropletSettingsToolbarSwitchA page's own on/off switch, as a pill in Droppy's Settings toolbar (DroppyKit 1.18.0), where every feature page of Droppy keeps its own. DropletSettingsToolbarMetricsThe numbers Droppy draws its Settings toolbar pills with (DroppyKit 1.18.0). DropletConfirmationDialogA confirmation drawn by Droppy using its own glass dialog (DroppyKit 1.19.0). SettingsUnifiedSegmentedRowOne value out of a short list, as the native pop-up button a System Settings row carries: the current choice with the up/down chevrons, a checkmarked menu of every option, keyboard and VoiceOver behaviour courtesy of AppKit. SettingsPickerOptionOne option of a segmented settings picker. SettingsGroupPositionVertical position of a grouped row within its parent DropletSettingsCard. SettingsSelectionChromeOne rule for "this is the option you picked", across every selectable control DroppyKit publishes. SettingsAdaptiveColorBuilds a Color that resolves per appearance, so a token can be written as a (ColorScheme) -> Color function and still be read at a call site with no ColorScheme in scope. SettingsInfoTipLightweight info button that shows a text popover on hover. SettingsSearchEntryOne entry the host's settings search can surface for a droplet. GroupedCornersDescribes which corners of a cell round when composing grouped rows, where outer corners follow the parent card's curvature and inner edges stay flat. DroppyKitThemeBridgeEnumeration DroppyKitThemeResolutionHost-installed theme hooks. DroppyMarkdownEditorDroppy's markdown editing surface. DroppyMarkdownEditorCommandsA handle onto the host editor's command bus (DroppyKit 0.2.2). DroppyMarkdownEditorContextEverything the host editor needs beyond the text binding (DroppyKit 0.2.2). DroppyMarkdownHighlightColorMarker-pen palette for ==highlight== spans (DroppyKit 0.2.2). DroppyMarkdownToolbarActionA formatting command a droplet's toolbar can send to the host editor (DroppyKit 0.2.2). settingsSectionHeader(_:)Single source of truth for the section headers that sit above settings cards. settingsUnifiedSegmentLabel(icon:title:isSelected:isEnabled:)One option of a settings pop-up: its SF Symbol, then its title, in the menu's own font. settingsUnifiedPickerRow(title:subtitle:icon:iconColor:options:accessibilityLabel:groupPosition:isEnabled:isSelected:action:content:)The canonical picker row: a title on the left and the native pop-up on the right, one line, inside a DropletSettingsCard.

Versioning

The handshake between a droplet and its host.

DroppyKitBuildVersion constants of this DroppyKit build. SemanticVersionA three-component semantic version, compared numerically. DropletCompatibilityVerdictOutcome of evaluating one bundle against one host. DropletHostDescriptorWhat one host advertises to the handshake.