Notes from
the workshop.
Write-ups from building Ampersand — the bugs worth explaining, the decisions with a reason behind them, and the things that only broke on somebody else’s computer. Occasional rather than scheduled.
What we have
written down
Postmortems and engineering notes, in full, with the measurements that made the point.
One inline <style> tag broke our entire app
How a single anti-flash style block silently converted our Content Security Policy into one that blocked every stylesheet and inline style the app injected at runtime — and why our whole browser test suite was structurally incapable of noticing.
The bug that argued for its own dismissal
We shipped an app that could not launch on most Apple Silicon Macs, for four weeks and eight releases. Because a crashing install never reports anything, our own telemetry said nobody was affected.
A window that could not paint
Waiting for the frame after this one is the standard way to know a page has rendered. It deadlocks if the window is hidden — and hiding the window until it has rendered is the standard way to avoid a white flash.
Never put a git repo in iCloud Drive
We give every vault a full version history backed by a real git repository. It lives outside the vault, on purpose, because the folder most people keep their notes in is the one folder git cannot survive.
Encrypting notes without holding the keys
Per-note encryption with age, one passphrase per vault, Touch ID without a Secure Enclave ACL, and a recovery kit with no escrow — including the parts encryption does not cover, and the mistake that coupled a cache to a document key.
Whisper hallucinates on silence
Speech recognition does not go quiet when nobody is talking; it invents. Gating on voice activity fixes that, and the textbook threshold for doing it throws away a segment made entirely of speech.
Want to know when we publish?
Reading can wait.
Writing shouldn't.
Every post here came out of building the editor. It is free to start — download it and write something of your own.
Free to start · Mac, Windows & Linux · No account required