Wireframe Maker

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)

rustup's PATH line may land somewhere zsh never reads

Verified on a Mac mini, 2026-09-22. rustc, cargo and rustup all 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/:

(registers the .bmpr and .wfm file associations)

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.sh fails if a previous dmg volume is still attached

Hit on the first universal build. The .app bundles 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.XXXXXX mount plus an rw.*.dmg beside 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 entitlements

Confirmed on the first real build: with no APPLE_SIGNING_IDENTITY set, codesign -dv reports Signature=adhoc, flags=0x20002(adhoc,linker-signed) and Info.plist=not bound, and codesign -d --entitlements - prints nothing. The hardened-runtime and entitlements settings above only take effect on a signed build. A locally built .app runs 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 exercises

the desktop work passed a build as working when only the argv route 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 | LaunchFile seeded at startup | | LaunchServices, cold | open -a "Wireframe Maker.app" file.bmpr with the app NOT running | RunEvent::Opened before the webview exists | | LaunchServices, warm | the same command with the app ALREADY running | RunEvent::Opened after the webview exists | A Finder double-click is the LaunchServices route, never argv. All three converge on one atomic take_initial_file, but they arrive by different means and each must be exercised.

  1. (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.

  1. (LaunchServices, cold) Double-click a .bmpr in 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.)

  1. (LaunchServices, warm) With the app already running, double-click a

second .bmpr → it imports without restarting the app.

  1. (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.

  1. (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.

  1. (native dialogs) Edit a screen, File ▸ Save As… to a .wfm.json,

edit again, ⌘S — the file on disk updates.

  1. (native menu bar) Undo/Redo, Export PNG, Play Prototype all work from

the menu bar, not just from in-app controls.

  1. (default browser) Click a link in exported HTML help text → opens

externally.

Verifying without a screen

Steps 2–5 can be checked headlessly, which matters because screencapture returns a black frame when the Mac is locked. The app's state lives at ~/Library/WebKit/health.redrover.wireframemaker; the wfm:projectMeta key in WebsiteData/Default/*/*/LocalStorage/localstorage.sqlite3 holds each project's name, screens, versions and lastEdited as a comma-separated UTF-16LE byte list. Re-importing the same archive reuses the same content-derived project id, so compare lastEdited, 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:

MachineWhat 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:

  1. 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).

  1. 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

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)

CapabilityRust (src-tauri/src/lib.rs)Adapter (src/platform/tauri.ts)
Native open/save dialogsopen_document, save_document_as, open_binaryopenDocument, saveDocumentAs, openBinary
Direct path IO (bindings, associations)read_document, write_document, stat_document, read_binaryreadByPath, PlatformFile
Double-click intakeargv scan + RunEvent::Opened (macOS), both landing in one Mutex-guarded LaunchFilepeekInitialFile, takeInitialFile, onOpenFile
Native menu barbuild_menu → emits wfm://menuonMenu → same store actions as in-app menus
Window statetauri-plugin-window-state—
External linksopen_externalopenExternal