Desktop builds
The desktop app is a Tauri v2 shell (system WebView, ~10 MB) around the exact same web build. All platform access lives behind src/platform/ — the web deployment is completely unaffected by anything here.
Binding cost rule: desktop builds NEVER run on GitHub Actions. Windows builds happen on the dev machine; macOS builds happen on a maintainer Mac, with the runbook below.
Prerequisites (any OS)
- Node 20+ and
npm install - Rust via rustup (stable toolchain)
- Windows: WebView2 (preinstalled on Windows 11), Visual Studio Build Tools C++
- macOS: Xcode Command Line Tools —
xcode-select --install
rustup's PATH line may land somewhere zsh never readsVerified on a Mac mini, 2026-09-22.
rustc,cargoandrustupall reported "not found" in a fresh zsh even though a full stable toolchain and both universal targets were already installed. rustup had written its env line to~/.profile, which zsh does not read — zsh uses.zshenv/.zprofile/.zshrc. Before concluding Rust is missing: ``bash ls ~/.cargo/bin && export PATH="$HOME/.cargo/bin:$PATH" && rustc --version`Permanent fix: add. "$HOME/.cargo/env"to~/.zprofile`.
Develop
npm run tauri dev
Starts Vite and opens the native window against it (port 5173 — set PORT and --config overrides if it's taken). Hot reload works normally.
Build — Windows
npm run tauri build
Artifacts land in src-tauri/target/release/:
wireframe-maker.exe— the bare binarybundle/nsis/Wireframe Maker_<version>_x64-setup.exe— per-user installer
(registers the .bmpr and .wfm file associations)
bundle/msi/…— MSI alternative
Build — macOS
One-time setup: install the prerequisites above, plus your Developer ID Application certificate in the login keychain (Xcode ▸ Settings ▸ Accounts ▸ Manage Certificates, or download from developer.apple.com). Never commit any identity, password, or key to this repo — keychain and environment only.
# 1. Build the .app and .dmg (universal: Intel + Apple Silicon)
npm install
rustup target add aarch64-apple-darwin x86_64-apple-darwin
npm run tauri build -- --target universal-apple-darwin
Artifacts: src-tauri/target/universal-apple-darwin/release/bundle/macos/Wireframe Maker.app and .../bundle/dmg/Wireframe Maker_<version>_universal.dmg.
Measured on a Mac mini, macOS 15.7.5 / arm64 / Xcode 26.3 (first ever macOS build): release compile 1m15s per arch, .app 11 MB, .dmg 6.4 MB, lipo -archs reports x86_64 arm64, hdiutil verify passes. The executable inside the bundle is Contents/MacOS/wireframe-maker (lowercase, hyphenated) even though the bundle is Wireframe Maker.app — scripts that reach inside must use the lowercase name.
bundle_dmg.shfails if a previous dmg volume is still attachedHit on the first universal build. The
.appbundles fine, then:failed to bundle project: error running bundle_dmg.sh. The cause is a leftover attached image from an earlier run — a/Volumes/dmg.XXXXXXmount plus anrw.*.dmgbeside the app, often held open by an app process still running from that volume. Recover with: ``bash pkill -f 'Volumes/dmg\.' || true hdiutil detach /Volumes/dmg.* -force rm -f src-tauri/target/*/release/bundle/macos/rw.*.dmg`` Then re-run the build; it succeeds. Always quit a copy of the app launched from a mounted dmg before rebuilding.
The bundle is configured with hardened runtime + entitlements (src-tauri/entitlements.plist: JIT for the JS engine, user-selected file read/write) — the two things notarization checks.
An unsigned build is ad-hoc signed and carries NO entitlementsConfirmed on the first real build: with no
APPLE_SIGNING_IDENTITYset,codesign -dvreportsSignature=adhoc,flags=0x20002(adhoc,linker-signed)andInfo.plist=not bound, andcodesign -d --entitlements -prints nothing. The hardened-runtime and entitlements settings above only take effect on a signed build. A locally built.appruns fine on the build machine (no quarantine attribute, so Gatekeeper never prompts), but it is not what gets distributed. Do not read a successful unsigned build as evidence that the notarization configuration is correct — that is the desktop work.
# 2. Sign with your Developer ID (name as it appears in `security find-identity -v -p codesigning`)
export APPLE_SIGNING_IDENTITY="Developer ID Application: YOUR NAME (TEAMID)"
codesign --force --deep --options runtime \
--entitlements src-tauri/entitlements.plist \
--sign "$APPLE_SIGNING_IDENTITY" \
"src-tauri/target/universal-apple-darwin/release/bundle/macos/Wireframe Maker.app"
# (Tauri signs automatically during build when APPLE_SIGNING_IDENTITY is set —
# the manual command above is the recovery path.)
# 3. Notarize the dmg (app-specific password from appleid.apple.com,
# stored once in the keychain as "notary-profile")
xcrun notarytool store-credentials notary-profile \
--apple-id you@example.com --team-id TEAMID # one-time; prompts for the app-specific password
xcrun notarytool submit \
"src-tauri/target/universal-apple-darwin/release/bundle/dmg/Wireframe Maker_0.1.0_universal.dmg" \
--keychain-profile notary-profile --wait
# 4. Staple the ticket so Gatekeeper passes offline
xcrun stapler staple \
"src-tauri/target/universal-apple-darwin/release/bundle/dmg/Wireframe Maker_0.1.0_universal.dmg"
Smoke-test checklist (macOS)
Every step names the launch mechanism it exercisesthe desktop work passed a build as working when only the
argvroute had ever been tried; the Finder route was broken the whole time and nobody could tell, because the checklist said "double-click a.bmpr" without saying that typing a path exercises a completely different code path. A step is only done when run through the mechanism named in bold. The three are: | Mechanism | How to invoke it | What it drives | |---|---|---| | argv |"…/Wireframe Maker.app/Contents/MacOS/wireframe-maker" file.bmpr|LaunchFileseeded at startup | | LaunchServices, cold |open -a "Wireframe Maker.app" file.bmprwith the app NOT running |RunEvent::Openedbefore the webview exists | | LaunchServices, warm | the same command with the app ALREADY running |RunEvent::Openedafter the webview exists | A Finder double-click is the LaunchServices route, never argv. All three converge on one atomictake_initial_file, but they arrive by different means and each must be exercised.
- (installed app) Open the .dmg, drag the app to Applications, launch —
no Gatekeeper warning. Needs a signed + notarized build; an unsigned local build has no quarantine flag and so never prompts, which means this step cannot be proven on a dev build.
- (LaunchServices, cold) Double-click a
.bmprin Finder → the app opens
and imports it. Verified 2026-10-05 from a cleared WebKit store: 170 screens, 87 versions, exactly one project. (That 87 counts every branch including master; the importer report in MIGRATING.md prints 86, counting alternates only. Same archive, different question.)
- (LaunchServices, warm) With the app already running, double-click a
second .bmpr → it imports without restarting the app.
- (argv) Launch the inner binary with a path argument → imports. This is
also the Windows file-association route, so a regression here breaks Windows too.
- (no file) Quit and relaunch with no argument → window size/position and
your last project come back, and nothing re-imports. A file you opened an hour ago must not silently load again; that is the stale-path case the desktop shell's consuming take exists to prevent.
- (native dialogs) Edit a screen, File ▸ Save As… to a
.wfm.json,
edit again, ⌘S — the file on disk updates.
- (native menu bar) Undo/Redo, Export PNG, Play Prototype all work from
the menu bar, not just from in-app controls.
- (default browser) Click a link in exported HTML help text → opens
externally.
Verifying without a screenSteps 2–5 can be checked headlessly, which matters because
screencapturereturns a black frame when the Mac is locked. The app's state lives at~/Library/WebKit/health.redrover.wireframemaker; thewfm:projectMetakey inWebsiteData/Default/*/*/LocalStorage/localstorage.sqlite3holds each project'sname,screens,versionsandlastEditedas a comma-separated UTF-16LE byte list. Re-importing the same archive reuses the same content-derived project id, so comparelastEdited, not the project count, to tell a real import from a no-op. Quit the app before reading: WebKit flushes localStorage on exit.
Testing the desktop layer
npm run check (typecheck + vitest) is the shared gate every lane runs, and it deliberately contains no cargo: the web and pm lanes have no Rust toolchain and their gate must stay green. The Rust tests therefore run through .githooks/pre-push, which sources ~/.cargo/env and then runs cargo test only if cargo is on PATH:
| Machine | What pre-push does |
|---|---|
| Has cargo (mac lane, any desktop-build machine) | Runs npm run check and cargo test; a Rust failure blocks the push |
| No cargo (web, pm) | Runs npm run check, prints that it is skipping the desktop tests |
So nobody has to remember a second command, and nobody without Rust is blocked. To run it by hand: npm run check:mac. The full mac-lane gate is npm run check && npm run check:mac (GM decision, 2026-10-05); the hook simply runs both for you where cargo exists.
What the Rust tests cover, and what they deliberately do not. They pin LaunchFile's semantics — set, peek, take — including the property the desktop shell's fix rests on: two arrivals, one path, exactly one winner. They do not cover LaunchServices, Finder, the AppKit open panel or notarization, which cannot be driven from cargo test; the smoke checklist above is the guard for those, and it is a human procedure by necessity rather than by neglect.
Stale-build protection
Two layers found live in the desktop work verification kept an updated exe serving the PREVIOUS build's frontend:
- The PWA service worker registered inside the shell and served
its cache-first shell cache. The shell now never registers it — and unregisters workers older builds left behind (src/editor/pwa.ts).
- WebView2's HTTP cache cached tauri.localhost responses;
additionalBrowserArgs in tauri.conf.json passes --disable-http-cache. Assets are local files, so the cache bought nothing.
macOS WKWebView has no WebView2 cache layer, but layer 1 applies to any OS — the gate is platform-checked, not Windows-checked.
File associations, honestly
.bmprassociates cleanly on both OSes (single extension)..wfm.jsoncannot be exclusively associated — Windows and macOS both
key on the final extension, and claiming all of .json would be hostile. The bundle registers .wfm as a courtesy; double-clicked .wfm.json files still open correctly via Open With → Wireframe Maker (the intake handles any .json/.bmpr path), and drag-drop onto the window always works.
What the shell adds (and where it lives)
| Capability | Rust (src-tauri/src/lib.rs) | Adapter (src/platform/tauri.ts) |
|---|---|---|
| Native open/save dialogs | open_document, save_document_as, open_binary | openDocument, saveDocumentAs, openBinary |
| Direct path IO (bindings, associations) | read_document, write_document, stat_document, read_binary | readByPath, PlatformFile |
| Double-click intake | argv scan + RunEvent::Opened (macOS), both landing in one Mutex-guarded LaunchFile | peekInitialFile, takeInitialFile, onOpenFile |
| Native menu bar | build_menu → emits wfm://menu | onMenu → same store actions as in-app menus |
| Window state | tauri-plugin-window-state | — |
| External links | open_external | openExternal |