Development

Use Node.js 24 or newer and npm. The root lockfile installs the renderer and private documentation workspace.

npm ci
npm run dev

The renderer opens at http://127.0.0.1:5173. Add ?asset=BTC, ?asset=SOL, ?asset=ETH, or ?asset=HYPE to choose a market. Missing or unsupported symbols use the Bitcoin default.

Website and documentationCopy Anchor Link

npm run docs:dev

Open http://127.0.0.1:3907/screensaver/. This builds and serves the complete static website, including live previews; rerun the build to incorporate source changes. Individual steps are:

npm run docs:check
npm run docs:build
npm run docs:preview

The build combines the Next.js/Fumadocs export with the Vite renderer at /screensaver/preview/, using the same base path as GitHub Pages.

The homepage reads config/assets.json and config/releases.json at build time. No market stream opens on the download page. An empty release manifest keeps downloads disabled.

ChecksCopy Anchor Link

npm run build
npm test
npx playwright install chromium webkit
npm run test:browser
npm run docs:build
npm run test:site

Browser checks use the real renderer and SDK with controlled transport responses. Live-data and native installer checks provide separate evidence for the public service and operating systems.

npm run preview serves the renderer production build on port 5173. Bun can invoke the same scripts after npm installs dependencies.

Native and desktop buildsCopy Anchor Link

npm run desktop:pack -- --asset BTC
npm run desktop:dist -- --asset SOL --arch arm64

Build on the target OS. --asset accepts BTC, SOL, ETH, or HYPE. Mac supports arm64 and x64; Windows and Linux target x64. Mac builds require the Xcode Command Line Tools and target macOS 13 or newer.

On Mac, the packaging command builds a native Swift ScreenSaverView with a WKWebView that loads the bundled renderer. The example creates Solana's .saver bundle in DMG/ZIP archives. desktop:pack produces an unpacked bundle, such as release/bitcoin-macos-arm64/Bloxwap Bitcoin Screensaver.saver; install it in a Screen Savers folder and select it in macOS to test the real system host.

On Windows and Linux, packaging builds the Electron app with its edition metadata, tray, and optional idle controls. npm run desktop runs that Electron host locally for development; it is not the Mac distribution path.

Output directories are isolated by edition, OS, and architecture. All native downloads bundle the same web display and third-party notices. Docs tooling stays outside the packages. Browser tests verify the shared renderer; native macOS bundle loading and system preview need their own verification.

Native Mac smoke checkCopy Anchor Link

After building an unpacked bundle for the current Mac architecture:

node scripts/macos-smoke.mjs --asset BTC --arch arm64

Use --arch x64 on an Intel Mac. The harness loads the actual ScreenSaverView and WKWebView bundle without installing it or changing system settings. --asset all checks all four previously built editions; --require-live additionally requires fresh public market data.

This standalone harness checks bundle/runtime behavior. macOS Screen Saver settings and the system screen-saver host need separate install, preview, activation, and dismissal verification. Record the actual macOS version and outcomes before making compatibility claims.

Shared design assetsCopy Anchor Link

Canonical icons, brand geometry, fonts, tokens, and chart math are bundled with provenance hashes. A public build needs no private sibling checkout.

Maintainers with the sibling monorepo can refresh the snapshot:

npm run sync:bloxwap

Keep source hashes and licenses with the assets. See data and display and releasing for the rendering contract and release automation.