You're viewing the readable version of this site. The interactive extras (search, diagrams, read-aloud) need JavaScript and a current browser. Enable JavaScript; if it is already enabled, update your browser.

Writing

Notes

Field notes on typography, tools, and the craft of building software.

A running collection of essays and working notes. The list below is generated from the posts themselves, newest first. Many articles are about me documenting what I learn from the designs and implementations of the various systems I work with.

Browse by tag 69

2026

  1. The Checkbox Is a State Machine

    The indeterminate square isn't a third value of a boolean — it's a report the tree makes about itself. Model that one distinction right and the classic stuck-parent bug becomes impossible to write.

    state-machines automata checkboxes derived-state front-end accessibility algebra-of-the-interface

  2. Can I Use This Library?

    A strict CSP quietly turns every dependency into a security decision. Here is the tree I walk to make it — per library, and across a whole app.

    security csp web architecture dependencies dissecting-systems

  3. The Header That Can't Be Cached

    Cache-Control from first principles — and why a page carrying a CSP nonce must be told never to be stored, not merely "don't cache."

    security csp http caching web dissecting-systems

  4. Trust No Script

    Why a strict Content Security Policy is one of the hardest headers to deploy — and how to read one with Google's CSP Evaluator.

    security csp web xss browsers gen-ai dissecting-systems

  5. You Don't Want Separate Repos

    Repository topology decides whether coupled code shares one content-addressed snapshot or negotiates version strings across a registry boundary.

    monorepo versioning git pnpm npm package-managers dependencies content-addressing modularity security supply-chain genkit sdk-design dissecting-systems

  6. A Language That Can't Loop Forever

    Bazel's Starlark forbids unbounded loops and recursion on purpose, and gets analyzability, caching, and parallelism in return. Buck2 quietly allows recursion back — and the split shows which restriction is load-bearing.

    build-systems starlark language-design bazel buck2 dissecting-systems

  7. A Little Uncertainty Buys a Lot of Space

    Bloom filters trade a small chance of being wrong for an enormous saving in memory — a bargain storage engines take and build systems, so far, refuse.

    probabilistic-data-structures bloom-filters build-systems content-addressing dissecting-systems

  8. node_modules Is the Heaviest Object in the Universe

    The same "the hash is the identity" idea that powers a build cache also explains why pnpm stores on disk what npm copies a hundred times over.

    package-managers pnpm npm content-addressing dissecting-systems

  9. The Build That Restarts Itself

    Inside Skyframe, Bazel's incremental engine — and the strange trick at its heart.

    build-systems bazel skyframe incremental-computation dissecting-systems

  10. The Grain of the Machine

    A processor isn't a featureless calculator — it has a shape: words, cache lines, vector lanes. Code that moves with that grain runs many times faster than code that fights it, on the very same data. Here's the shape, and a measured case where the same arithmetic runs 22× slower against it.

    hardware performance cpu cache simd dissecting-systems

  11. The Hash Is the Identity

    Content-addressing in the build cache — content-addressed storage and Merkle trees turn a build cache into a shared resource, so your build is proportional to anyone's change.

    build-systems remote-execution bazel buck2 content-addressing dissecting-systems

  12. The Widest Box Is the Bug

    A flamegraph turns thousands of stack samples into one picture where the slow code is, almost literally, the biggest thing on the screen.

    profiling performance flamegraphs observability dissecting-systems

  13. There Are No Phases

    Buck2's DICE engine collapses load, analysis, and execution into a single graph — and the decision to rebuild rather than adopt.

    build-systems buck2 dice incremental-computation dissecting-systems

  14. Utils Is Where Modularity Goes to Die

    Module boundaries should follow the dependency graph, not your folder intuitions — and "optimal" can be defined precisely.

    refactoring modularity build-systems software-design dissecting-systems

  15. With the Grain

    The original turned a big integer into bytes one byte at a time, fighting the machine. The rewrite went with its grain — whole machine words, packed in C. That structural choice is why it's still ~15× faster fifteen years on, even as CPython sped up underneath it.

    python performance cpython optimization dissecting-systems

  16. The Build Is Proportional to the Change

    What every build system is really doing — and the one decision that separates the ones that scale.

    build-systems bazel buck2 gradle dissecting-systems

  17. Kitchen Sink Series — Part One

    A fixture sibling so the kitchen sink has a real previous part to link to.

  18. Kitchen Sink Series — Part Three

    A fixture sibling so the kitchen sink has a real next part to link to.

  19. Scaffolding a Typographic Portfolio Site

    The design philosophy behind this site — why it's built from durable tools and a purposeful type system instead of a framework, and why every choice is aimed at lasting.

    typography design-system org-mode web

  20. The Patch Bram Applied

    A small contribution to Vim, the man who took it, and the editor I still open every morning.

    vim open-source tribute

  21. Designing an API That Outlives You

    I wrote watchdog in 2010. Fifteen years and three maintainers later it still ships the same public API I designed — here's what made it last.

    api-design watchdog python software-design dissecting-systems

2025

  1. Everything Is an Action

    The architecture of Firebase Genkit rests on one primitive — a self-describing, observable, callable function — and the whole SDK is layers of specializations of it.

    architecture genkit gen-ai sdk-design software-design dissecting-systems

  2. Reading a Codebase

    A method for taking real software apart at the source level — find the one type everything hangs from, extract the algebra, and learn what the designers refused to allow.

    methodology software-design reading-code dissecting-systems

2009

  1. I like the way Aquamacs looks. I don’t use it because it feels different

    Why I keep stock GNU Emacs over Aquamacs — one consistent editor across every OS.

    emacs tools archive

  2. Even faster String.prototype.trim() implementation in JavaScript

    A faster, non-regex String.prototype.trim() — later adopted into early JS frameworks.

    javascript performance archive

  3. Making the browser download scripts in parallel

    Loading multiple scripts concurrently instead of the browser’s serial default.

    javascript performance browsers archive

  4. memcache.js for Google App Engine application front-ends?

    Caching AJAX responses on the client by mapping App Engine’s datastore to JS objects.

    javascript google-app-engine caching archive

  5. Implementing a Pythonic range() function in JavaScript

    A Python-style range() helper instead of typing out a sequence by hand.

    javascript python archive

Linked from 71