Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions Droplet/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
.build/
.swiftpm/
.DS_Store
205 changes: 205 additions & 0 deletions Droplet/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,205 @@
# Codex Usage, a Droplet for Droppy

<!-- Written by `droppykit agent`. Add your own notes below; the file is only rewritten with --force. -->

This package is a **Droplet**: an extension that runs inside Droppy, the
Dynamic Island and shelf for Mac, written in SwiftUI against **DroppyKit**.
Droppy loads the built `.droplet` bundle into its own process and draws it on
the notch, the shelf, the lock screen and the menu bar.

- Droplet id: `codexusage`. It is also `CodexusageDroplet.id` in Swift and `id` in `droplet.json`; the three must agree or the loader refuses the bundle.
- Swift product: `Codexusage`, a dynamic library. The harness target is `CodexusageHarness`.
- SDK checkout: `<your droppykit checkout>` (DroppyKit 1.20.1). Docs online: https://getdroppy.app/docs/droppykit
- Host: Droppy 15.3 or later, which runs an unsigned bundle once its user approves that build under Settings, Store, Local droplets and asks again each time it opens, or the free Droppy Playground (https://getdroppy.app/download/playground), which loads unsigned bundles without asking.

## The loop

Every change goes through all of this, in order. A droplet can compile,
validate and then draw nothing, so a green build is not the end.

1. Edit `Sources/Codexusage/`. The manifest is `droplet.json`.
2. `droppykit build` writes `.build/Codexusage.droplet`, universal, linked against the
framework Droppy ships. Never a bare `swift build` for the bundle: it folds a second
copy of DroppyKit into the droplet, and that bundle loads in the harness and dies
inside Droppy at dyld with "Symbol not found".
3. `droppykit validate` runs the exact checks the Store's intake runs.
4. `droppykit run -- --shots ./shots --report ./shots/report.json` renders every surface
to a PNG without opening a window and writes a JSON verdict. Look at the pictures.
Read `report.json`: `problems` must be empty and every surface you declared must be
`provided`.
5. Put the bundle into Droppy Playground and confirm it loaded. Copy
`.build/Codexusage.droplet` to
`~/Library/Application Support/Droppy Playground/Droplets/codexusage/Codexusage.droplet`,
relaunch the Playground, and read its Store row: the subtitle is the loader's verdict.

With the DroppyKit MCP server connected, the same steps are the tools `droppykit_build`,
`droppykit_validate`, `droppykit_shots` and `droppykit_install`, and `droppykit_shots`
returns the images inline. This package carries the server in `.mcp.json` (Claude Code)
and `.cursor/mcp.json` (Cursor). Codex: `codex mcp add droppykit -- <your droppykit checkout>/Scripts/droppykit mcp`.
The other tools are `droppykit_manifest` (a static check, no build), `droppykit_docs`
(the guides and a search over the SDK sources), `droppykit_doctor`, `droppykit_new`,
`droppykit_open_harness` and `droppykit_submit`.

`droppykit run` with no arguments opens the harness window for a person: Droppy's own
Settings panel with a page per surface. You cannot see that window. The shots are your
eyes; take them after every visual change.

`droppykit version` says which SDK checkout the scripts come from and which tag this
package pins; `droppykit update` moves both to the newest release. A build that stops with
"no compiled objects" or "DroppyKit.o not found" is an SDK older than 1.2.1: update it.

## Rules

- **Surfaces and conformances agree.** `surfaces` in `droplet.json` lists what the droplet
provides; the droplet conforms to the matching protocol for each of them and to nothing it
does not list. Disagreement is the most common reason a droplet validates and then does
nothing.
- **Every shelf widget declares both widths.** `preferredSoloWidth` and
`preferredPairedWidth` are required; Droppy refuses a descriptor that leaves either to a
host fallback. Solo and paired are different compositions, not one view at two widths:
branch on `context.isPaired`.
- **Layout traits describe the widget's rectangle.** Every number in
`ShelfWidgetLayoutTraits` is the area the widget draws in, in points at the Regular shelf
size, exactly what the harness renders; Droppy adds its own chrome around it. `.fixed(150)`
is a 150-point rectangle, alone and in a row, clamped to 48 through 480. A widget that needs
more height declares more; it never pads its way out of a clip. A solo widget is never
narrower than 352 on a notch or 370 on an island, so lay out to `context.availableSize`.
- **No card, no border around the widget.** Droppy paints nothing behind a widget and almost
every one of its own widgets lays its content directly on the shelf's black. Put no
background, fill, outline or rounded box on the widget's root view. `notchSurfaceCardFill`
is for a tile or a chip inside the widget that has to read as raised, never a frame.
- **Lay the widget out like Droppy's.** The root view fills the rectangle
(`.frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)`) with ONE
padding, `.padding(context.contentInsets)`, and nothing on top of it. It clears the host's
rounded clip: 8 on every edge under the 18pt card corner (a notch, and any row on either
shape), 0 alone on the island, where the island shell clips the card and keeps one even gap.
The shelf's chrome already inset the rectangle, so never add your own padding or corner
inset on top: it doubles the gap.
Leading text, trailing `.monospacedDigit()` numbers, rows that span the
full width, a header row of a 12pt symbol and a 12pt semibold title with the widget's control
at its trailing end, `DroppySpacing` steps between rows. Declare the height the content
needs; never leave unused space or fill it with padding.
- **The physical notch is cleared for you, except on a HUD strip.** The shelf, a takeover,
a HUD card and a live activity are inset past the camera housing by the host; never pad for
it. A HUD strip is handed the whole width across the housing: put its content at the two
outer edges and nothing in the middle (`host.environment.notchGeometry.closedWidth` is the
housing), the way the World Clock example's strip does. Never centre a strip.
- **Droppy owns every motion around your surfaces; you animate only what you swap.** A live
activity row and a HUD are mounted exactly like Droppy's own, so never put an entrance
transition on the view a factory returns (it plays twice). A live activity is compact only:
hovering or clicking it opens the shelf, `makeExpanded` is not mounted, and Stop / Start
belong in the shelf widget. A glyph, label or control you swap while a surface is up takes
`DroppyTransition.compactContent` in a wing or strip and `DroppyTransition.element` in a
card, never a transition or spring of your own (`minAPI` 1.8.0).
- **Buttons are Liquid Glass, Droppy's own.** `DroppyCircleButtonStyle` (20pt on an item,
24pt in a row) for an icon action, `DroppyQuietButtonStyle` and `DroppyAccentButtonStyle`
(`.small`) for labelled ones, `DroppyGlassButtonStyle` for a label with its own sizing.
Never a flat wash, a bordered chip or a white button of your own. A list with a control per
row wraps in `droppyFlatGlassControls()`. Only a live activity row's controls keep
`DroppyLiveActivityControlStyle`.
- **Everything `activate(host:)` starts, `deactivate()` stops.** Timers, observers, tasks,
connections. Swift cannot unload code, so anything left running runs until Droppy
relaunches.
- **A widget the user watches holds the shelf open while it runs.** The shelf closes when the
pointer leaves it; a teleprompter, countdown or live transcript calls
`host.shelf.setHoldsOpen(true)` when its work starts and `false` the moment it ends
(`shelf-write`, `minAPI` 1.5.0). A widget with nothing to show until it is configured sends
the user to its settings pane with `host.workspace.openSettings()`, and asks for permissions
there through `host.permissions`, never from the shelf.
- **Host calls are gated by `capabilities`.** A service call without its capability in
`droplet.json` is refused: it returns `false` or `nil` and logs one line. Declare what you
use and only that; the user sees the list.
- **The principal class does nothing.** `CodexusagePrincipal` is `@objc`, is named in the
bundle's `NSPrincipalClass`, and only creates the droplet. It runs before the host is ready.
- **No `main.swift`.** The harness entry is `@main` in
`Sources/CodexusageHarness/CodexusageHarness.swift`, and a file named `main.swift` cannot
coexist with `@main`.
- **Look like Droppy, not like a guest.** Surfaces are dark. Foreground colours come from
`AdaptiveColors`, spacing from `DroppySpacing`, radii from `DroppyRadius` with
`style: .continuous`. No borders or outlines, no gradients, no ALL-CAPS labels, sentence
case everywhere, and never paint your own background on a widget. Never repeat the page
header in a settings pane: Droppy already shows the droplet's icon, name, summary and maker
above it, so the pane starts with its first setting (the Store refuses a pane that shows the
droplet's own icon or its name as a title). Settings panes are rooted
in `DropletSettingsPane` (`minAPI` 1.9.0) and built from `DropletSettingsCard`,
`DropletSettingsSection`, `DropletControlRow`, `DropletToggleRow`, `DropletStackedRow` and
`DropletSliderRow`; the host mounts the pane in its native grouped form, so the pane's
content is a list of sections, never a `VStack`, and it places no dividers.
- **`droplet.json` is the truth for the build.** `Info.plist` is generated from it.
`version` is numeric `major.minor.patch`; `summary` is at most 60 characters;
`minAppVersion` stays `15.3.0` unless the droplet needs something newer; `kit.minAPI` is
the oldest DroppyKit API the droplet actually calls. `droppykit build` fails when it is
older than that and names the calls and the version to set; set that version, never
lower it to get a droplet loaded.
- **Do not edit anything under `<your droppykit checkout>`.** That is the SDK checkout; fixes there go
upstream. This package is where the work is.

## Where the truth is

Read these before guessing at an API. They are on disk, in the SDK checkout.

- Guides, as Markdown: `<your droppykit checkout>/Sources/DroppyKit/Documentation.docc/`
`CreateYourFirstDroplet.md`, `DropletSetup.md`, `DesignGuidelines.md`, `ShelfWidgets.md`,
`LiveActivities.md`, `ExpandedSurfaces.md`, `SettingsPanes.md`, `Icons.md`, `Harness.md`,
`HostSupport.md`, `Playground.md`, `Submitting.md`, and `BuildWithCodingAgents.md` for this
workflow in full.
- The surface protocols, one file each: `<your droppykit checkout>/Sources/DroppyKit/Capabilities/`
- The host services a droplet calls: `<your droppykit checkout>/Sources/DroppyKit/Services/DropletServices.swift`
and `<your droppykit checkout>/Sources/DroppyKit/Core/DropletHost.swift`
- The manifest type, with every field documented: `<your droppykit checkout>/Sources/DroppyKit/Bundle/DropletManifest.swift`
- Design tokens and the settings components: `<your droppykit checkout>/Sources/DroppyKit/DesignSystem/`
- A complete droplet that uses every surface: `<your droppykit checkout>/Examples/WorldClock/`
- The compatibility promise and the version ledger: `<your droppykit checkout>/COMPATIBILITY.md`

## Surfaces

| `surfaces` value in droplet.json | Conform to | Shot |
| --- | --- | --- |
| `shelf-widget` | `ShelfWidgetProviding` | `shelf-widget.png` |
| `live-activity` | `LiveActivityProviding` | `live-activity.png` |
| `expanded-surface` | `ExpandedSurfaceProviding` | `expanded-surface.png` |
| `settings-pane` | `SettingsPaneProviding` | `settings-pane.png` |
| `hud` | `HUDPresenting` | `hud.png` |
| `lock-screen-status` | `LockScreenStatusProviding` | `lock-screen.png` |
| `menu-bar-extra` | `MenuBarExtraProviding` | `menu-bar.png` |

`overview.png` shows the identity card with a verdict pill per surface, `capabilities.png`
the capability switches, `preferences.png` every stored value, and `activity.png` every host
call in order, refused ones marked.

## Done means

- `droppykit build` and `droppykit validate` both pass.
- The report's `problems` is empty and `activation.error` is null.
- You have looked at the shot of every surface you touched.
- The bundle loaded in Droppy Playground: `droppykit_install` says loaded, or the Store row
shows it switched on.
- `droplet.json` still describes what the code does: surfaces, capabilities, summary.

## Package layout

```
Package.swift product Codexusage (dynamic) and CodexusageHarness
droplet.json the manifest; Info.plist is generated from it
Sources/Codexusage/ the droplet
Sources/CodexusageHarness/ the @main harness entry; never main.swift
Codexusage.icon/ Icon Composer document, required
Assets/Creator.png square creator avatar, at least 256px, required
.build/Codexusage.droplet what droppykit build writes
AGENTS.md, CLAUDE.md, .cursor/ this brief and the agent wiring
.mcp.json, .cursor/mcp.json the DroppyKit MCP server; absolute paths for this Mac
```

## Submitting

Your own build runs in Droppy only after you approve it under Settings, Store, Local
droplets, and Droppy asks again each time it opens; everyone else gets the droplet from
the Store, signed by Droppy after review.
When the droplet is done: replace the placeholder icon and creator avatar, fill in
`creator` and `source` in `droplet.json`, write `CHANGELOG.md`, and run `droppykit submit`.
The Store is a repository (gitlab.com/droppyformac1/droplets, one folder per droplet):
`submit` forks it, copies this package into `droplets/<id>/`, pushes a branch and opens
the merge request; when a maintainer merges it, the pipeline builds, signs and publishes
it. `droppykit submit --print` shows the plan without doing it (needs `glab`, signed in).
Opening the merge request means accepting the Droplet developer terms at
https://getdroppy.app/droplet-developer-terms.
Binary file added Droplet/Assets/Creator.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
17 changes: 17 additions & 0 deletions Droplet/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Changelog

## [1.1.0] - 2026-11-15

- Rename to Runway and open the Runway app.
- Show remaining 5-hour and weekly allowance.
- Match all six Runway themes.
- Dim stale data and say when it was last updated; allow ten quiet minutes before calling it stale.

## [1.0.2] - 2026-09-29

- Smooth the session graph with native monotone interpolation.
- Remove the bottom text rows and reduce widget height.

## [1.0.0] - 2026-09-29

- First release.
Binary file added Droplet/Codexusage.icon/Assets/mark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
42 changes: 42 additions & 0 deletions Droplet/Codexusage.icon/icon.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
{
"fill-specializations" : [
{
"value" : {
"linear-gradient" : [
"display-p3:0.56863,0.76863,1.00000,1.00000",
"srgb:0.14510,0.50196,1.00000,1.00000"
]
}
},
{
"appearance" : "dark",
"value" : {
"linear-gradient" : [
"display-p3:0.20870,0.20870,0.20870,1.00000",
"display-p3:0.08561,0.08561,0.08561,1.00000"
]
}
}
],
"groups" : [
{
"layers" : [
{
"hidden" : false,
"image-name" : "mark.png",
"name" : "mark",
"position" : {
"scale" : 0.8,
"translation-in-points" : [ 0, 0 ]
}
}
],
"shadow" : { "kind" : "neutral", "opacity" : 0.5 },
"translucency" : { "enabled" : true, "value" : 0.5 }
}
],
"supported-platforms" : {
"circles" : [ "watchOS" ],
"squares" : "shared"
}
}
15 changes: 15 additions & 0 deletions Droplet/Package.resolved

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

30 changes: 30 additions & 0 deletions Droplet/Package.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
// swift-tools-version: 6.2
import PackageDescription

let package = Package(
name: "Codexusage",
platforms: [.macOS(.v14)],
products: [
// A droplet is a loadable bundle, so its product is a dynamic library.
// Do not make it static: the app already carries DroppyKit, and a
// second copy inside the droplet gives the same type two metadata
// records, which fails every cast between them.
.library(name: "Codexusage", type: .dynamic, targets: ["Codexusage"])
],
dependencies: [
.package(url: "https://gitlab.com/droppyformac1/droppykit.git", from: "1.6.0")
],
targets: [
.target(
name: "Codexusage",
dependencies: [.product(name: "DroppyKit", package: "droppykit")]
),
.executableTarget(
name: "CodexusageHarness",
dependencies: [
"Codexusage",
.product(name: "DroppyKitHarness", package: "droppykit")
]
)
]
)
32 changes: 32 additions & 0 deletions Droplet/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Codex Usage

A Droplet for [Droppy](https://getdroppy.app), built with
[DroppyKit](https://getdroppy.app/docs/droppykit).

## Developing

```bash
droppykit run # open it in Droppy's Settings panel
droppykit build # produce Codexusage.droplet
droppykit validate # the checks the Store repository runs
droppykit submit # open the merge request that puts it in the Store
```

## With a coding agent

Open this folder in Claude Code, Codex or Cursor. `AGENTS.md` is the brief
they read first, and `.mcp.json` / `.cursor/mcp.json` connect the DroppyKit
MCP server, which gives them the build, the checks, pictures of every surface
and an install into Droppy Playground as tools. Codex registers the server
once per Mac: `codex mcp add droppykit -- path/to/droppykit/Scripts/droppykit mcp`.
Run `droppykit agent` again after moving this folder or the SDK checkout.

## Before submitting

- Replace `Codexusage.icon` with real artwork, in Icon Composer.
- Replace `Assets/Creator.png` with your own square, unrounded mark.
- Fill in `summary`, `description` and `creator` in `droplet.json`, and
write `CHANGELOG.md`.
- `droppykit submit`: the Store is a repository, one folder per droplet, and
this opens the merge request that adds yours. See
[Submitting](https://getdroppy.app/docs/droppykit/submitting).
Loading