Troubleshooting

This page collects the most common issues people hit when running Vesper Mosaic. If your situation isn't covered here, email support@vesperapps.com.

First-launch security prompt

The current beta is signed with Steven's Apple Developer ID but has not yet been notarized by Apple. On first launch from a fresh download, macOS Gatekeeper may block the app and show a dialog saying it cannot be opened.

Fix: in Finder, navigate to Applications, right-click Vesper Mosaic, and choose Open. macOS will now show a confirmation dialog with an Open button - click it. After this one-time confirmation, Mosaic will launch normally on every subsequent run.

This goes away with the next build.
Notarization is queued for an upcoming release. Once shipped, the right-click step will no longer be needed - the app will open from a normal double-click on any Mac.

Device pixel ratio (DPR) is not emulated

Mosaic's three viewports render at the correct CSS viewport widths (390, 768, 1920), but the device pixel ratio stays at the host Mac's native DPR (usually 2.0 on Retina displays, 1.0 on external monitors).

What this means in practice:

CSS layout is accurate. Width-based media queries fire correctly. Layout breakpoints are reliable.
DPR-dependent media queries can be wrong. A rule like @media (min-resolution: 2dppx) matches based on the host display, not on whether a real iPhone or iPad would match.
High-DPI image swaps may not match real devices. Sites that use srcset with 2x descriptors or image-set() will pick the variant the host display calls for. The Mobile pane on a Retina Mac will load 2x images even though a "real" 390-wide phone might be 3x.

Workaround: for DPR-sensitive testing, supplement Mosaic with a real device or a browser DevTools' device-mode emulation (which does emulate DPR). DPR emulation is on the roadmap for a future Mosaic release pending an Electron API change in macOS 26.

Scroll sync feels slightly off

The anchor-element scroll sync aligns the panes by the position of a shared identifiable element (heading, landmark, element with an id). On pages where the layout differs significantly between viewports - say, a desktop sidebar that becomes a hamburger menu on mobile - the anchor element may sit in different relative positions in each pane, which can look like the scroll is "off."

This is usually correct behavior. The panes are aligned by content, not by pixel. If the same element is at the top of the desktop pane and 30% down the mobile pane, that's because the mobile layout has more content above it.

If you suspect a real bug rather than a layout difference, file a report at support@vesperapps.com with the URL and a screenshot.

One pane reloaded but the others didn't

The reload button and Cmd+R always reload all three panes. If only one pane reloaded:

Did you press the keyboard shortcut while a DevTools window had focus? The shortcut is consumed by DevTools instead of Mosaic. Click back into the Mosaic main window first, then press Cmd+R.
Did one pane crash? A renderer crash leaves a single pane gray. Quit Mosaic and relaunch.

The window won't fit my screen in Fit mode

Fit mode tries to display all three panes side by side. On very narrow displays - 13" laptop screens at default resolution, or split-screen layouts - the result can feel cramped, especially for the Mobile pane.

Workaround: switch to 100% mode (Cmd+2) and scroll horizontally to focus on each pane individually, or Stack mode (Cmd+3) to stack them vertically at full width.

Auto-updates aren't installed yet

The current beta does not automatically check for updates. To upgrade, download the latest .dmg manually from the Vesper Mosaic page and install over the existing app. Auto-updates are on the roadmap for a follow-up build.

Removing Vesper Mosaic

Quit Vesper Mosaic.
Drag Vesper Mosaic from /Applications to the Trash.
Optional - to remove the shared session data (cookies, localStorage, cached pages): rm -rf ~/Library/Application\ Support/Vesper\ Mosaic in Terminal.

Still stuck?

Email support@vesperapps.com with:

Your Mosaic version (Apple menu → About Vesper Mosaic).
Your macOS version (Apple menu → About This Mac).
The URL you were viewing when the issue happened.
A description of what you expected vs. what you saw, ideally with a screenshot.