Kit Scrobbler

An Apple-first Safari extension for scrobbling music plays to Last.fm.

💁 About

Kit Scrobbler is narrowly scoped to be the best extension for scrobbling music in Safari on macOS. It is not a generic cross-platform scrobbler and it does not try to be. Everything here is tuned for Apple's webkit browser and Apple's design language.

It is built around the Web Scrobbler codebase — connectors and playback logic — which is vendored as a read-only git submodule at src/web-scrobbler/. Kit Scrobbler uses its own Bun-powered build pipeline and its own Apple-styled UI on top.

🧩 Extension Installation

1. Download the Zip from the releases page
2. Unzip the downloaded file in a location where you can easily access it
3. Open Safari
4. Enable the Show features for web developers option in Safari's Advanced settings tab
5. Navigate to Settings → Developer → Add Temporary Extension… and select the unzipped extension folder
6. Navigate to the Extensions tab in Safari to see the temporary extension loaded and active it
7. Click the extension's Settings button to login to Last.fm and configure other settings as desired
8. Visit a supported online music service, like SoundCloud
9. Click the new Kit Scrobbler toolbar button once to approve permissions
10. Enjoy scrobbling your music plays to Last.fm!

🗂 Project Layout

📁 app/                 Kit Scrobbler's own source: popup, options, design system
📁 scripts/             The Bun build pipeline
📁 src/web-scrobbler/   Upstream submodule — **never edit this**

🧑‍💻 Development

See AGENTS.md for the project constitution (the rules an automated agent — or a human — should follow).

Run this project inside a DevContainer in VS Code. After reopening the folder in the container, needed dependencies are installed automatically. NOTE: xcode build will not be possible inside the Linux-based DevContainer.

Command	Action
bun install	Install dependencies, fetch the Web Scrobbler submodule and its dependencies
bun run dev	Bun dev server with HMR: gallery at http://localhost:3000/popup/dev.html (see "Popup state gallery" below)
bun run build:ui	Bundle the popup + options into build/preview
bun run build	Build the loadable extension into build/preview (any OS)
bun run build:release	The same build without the popup state gallery — what the release workflow ships
bun run bundle	Archive + export the App Store build to dist/ (macOS + Xcode)
bun run check	Lint + format check with Biome
bun run fix	Biome autofix
bun run guard	Verify the upstream submodule has not been modified

🖼 UI Helper: Popup state gallery

bun run dev then open http://localhost:3000/popup/dev.html to see renders every popup.html state side-by-side in iframes, so you can compare them without a browser session for each.

🎨 UI principles

• Apple design tokens (spacing, corners, colours, type) live in app/shared/theme.css and are driven by color-scheme + light-dark() — no duplicated dark-mode rules.
• Modern CSS only: CSS Nesting, :has(), @starting-style, popovers. There is no preprocessor and no transpilation step for our styles.
• Native controls first: real <input type="checkbox" switch>, <select>, <input type="range"> using accent-color.

🧰 Building the Safari extension

Requirements: macOS 27 with Xcode 27, and Bun. Nothing else — the toolbar icons are rendered with the system WebKit, so no Chrome or ImageMagick is needed.

1. Build the web extension

bun install
bun run build      # → build/preview

2. Run it in Safari without Xcode

Safari → Settings → Advanced → tick Show features for web developers, then Settings → Developer → tick Allow unsigned extensions, then Add Temporary Extension… and choose the build/preview folder. Temporary extensions disappear after 24 hours or when Safari quits.

3. Run the app and the extension from Xcode

open "apple-extension/Kit Scrobbler/Kit Scrobbler.xcodeproj"

Choose the Kit Scrobbler scheme and press Run. Xcode builds the extension, embeds it in the app, and installs it in Safari; enable it under Settings → Extensions.

The project references the files in build/preview rather than copying them, so re-run step 1 after any change to the web code. Xcode does not build it for you, and if build/preview is missing the extension ships with whatever was there last.

Signing is automatic with team E3ZB7KXNN9, so no setup is needed. Both targets target macOS 27, and app sandbox plus hardened runtime are on through build settings rather than entitlement files.

4. Package for the App Store

bun run bundle     # builds without the dev gallery, archives, and exports to dist/

EXPORT_METHOD (default app-store-connect), EXPORT_DESTINATION (export writes a .pkg into dist/; upload sends it to App Store Connect) and DEVELOPMENT_TEAM override the defaults.

bun run build needs upstream's native libraries: brew install pango on macOS, or the cairo/pango development packages on Linux.

📦 Dependency Updates

• bun update --interactive to update dependencies interactively
• bun biome migrate to update Biome configuration and dependencies

📚 Resources

• KitScrobbler Toolbar icons - what the icons represent
• Biome
• Bun
• Phosphor Icons
• Apple Developer: Safari Web Extensions

☑️ TODO

See GitHub Issues.