Dan Cătălin Burzo: Articles

HTTP caching, a refresher

2025-12-22T14:01:58Z

This is a fresh reading of RFC 9111 (2022), the latest iteration of the HTTP Caching standard.

The standard defines the Cache-Control HTTP header as a way to prescribe how caches should store and reuse HTTP responses, with regard to not just the browser cache, but to any other intermediary caches, such as proxies and content delivery networks, that may exist between the client and the origin server.

The Cache-Control header accepts a set of comma-separated directives, some of which are meant to be added to HTTP requests, and others to HTTP responses. A typical response header:

HTTP/2 200
Cache-Control: max-age=0, must-revalidate

Some of these directives specifically target shared caches, that is intermediary caches that serve the same cached responses to many users, while others also apply to private caches such as the browser cache.

The RFC is written from the perspective that HTTP caching is desirable and widely on by default. It saves the strongest prescriptions — MUST and MUST NOT — for mechanisms meant to keep things out of conforming caches, or to prevent these caches from reusing their stored responses inappropriately, rather than to force caches to store certain responses.

Before HTTPS-everywhere became the norm, a client’s communication to the server could be mediated by various proxies, deployed by your internet service provider or your workplace, that could automagically cache and optimize content on the fly. Some Cache-Control directives were originally meant to rein in some of these proxy behaviors that were otherwise out of the control of clients or origin servers.

These days, a much more relevant form of shared cache is the service provided by CDNs, which act as gateways to ease the load on an origin server. CDNs act as ‘conformant-with-footnotes’ HTTP shared caches, meaning that they’ve adopted, to the extent they are able or willing, the HTTP Caching rules as a vendor-agnostic way to configure their behavior. But unlike the ‘web accelerators’ of yore, they don’t need to rely on HTTP headers alone, as server owners can often supplement them with ‘out-of-band’ configuration that enhances, or overrides, HTTP semantics. Other shared caches, such as Vinyl HTTP Cache (formerly known as Varnish), are typically installed closer to an origin server and have similar configuration affordances.

So HTTP caching remains as relevant as ever.

No cache no chill. Besides browsers, other types of web clients we don’t usually think of as incorporating a private cache — think artisanal RSS feed readers, web scrapers, URL unfurlers — could, and should, become fluent in cache-talk.

What’s fresh?

Whenever the cache receives a request, it must figure out if the cached response is still fresh and can therefore be reused without incurring the performance tax of an HTTP request, or whether it has gone stale and should be validated with the server.

To decide on freshness, the cache compares the age of the response to the response’s so-called freshness timeline.

The age of a cached response is the time elapsed since it was last generated or revalidated by the origin server. To the time spent in its own cache, the browser will add any Age: <seconds> header received from intermediary caches.

The freshness timeline is a duration beyond which the cached response is to be considered stale. It’s usually signaled by the server via the appropriate response headers, but may also be guesstimated by the cache in the absence of explicit, valid cues. In order of precedence:

the server establishes a freshness timeline, in seconds, with the Cache-Control: max-age=<number> directive on the response; otherwise,
the cache falls back to computing the interval between the Expires: <date> and Date: <date> response headers, if available; otherwise,
if there’s no Expires header, the response lacks an explicit expiration, and a heuristic freshness based on the Last-Modified response header might be applicable.

For shared caches, the special s-maxage=<number> directive takes precedence over all others.

Going past expiration

Just because a response has gone stale, it doesn’t mean it needs to be thrown out.

When it receives a request for a stale cached response, the cache should validate it with its upstream server. Although validation always generates an HTTP request, it avoids a data transfer when there’s no newer version of the cached response on the server, so it can still be faster than a regular request.

Validation uses a mechanism known as a conditional HTTP request, which includes one or more special headers called preconditions:

if the precondition with the highest precedence is met, the server responds with HTTP 200 OK and an updated response body; otherwise,
it responds with HTTP 304 Not Modified and an empty body, confirming the existing response can be reused.

To generate the preconditions needed for these conditional requests, which the server uses to compare the cached response to the freshest version available, responses must be tagged in a way that’s unique to each version:

historically, this was done with the Last-Modified: <date> header, corresponding to the latest update to the content;
a more flexible and robust alternative is the ETag: "<value>" header, which stores an arbitrary ASCII string that uniquely identifies the response. This string is usually a hash incorporating one or more aspects: the modification time, the file size, and the file content.

When performing the validation, the cached response headers are mirrored as preconditions for the conditional request:

Last-Modified: <date> becomes If-Modified-Since: <date>;
ETag: "<value>" becomes If-None-Match: "<value>".

When both preconditions are present, only If-None-Match is evaluated.

Regardless of the result of the validation request, the cached response headers are updated with the new values received from the server, and the fresh-o-meter on the cached response is reset.

Certain caches may be set up to serve stale responses in some circumstances, such as when losing the connection to the server or in the event of an HTTP 5xx server error. There are also Cache-Control directives that influence how stale responses are handled, covered in the next section.

How caches store responses

An HTTP cache stores previous responses under cache keys, and uses those keys when looking for suitable cached responses to satisfy new requests. At a minimum, the cache key is composed of the URL and HTTP method used to retrieve the response.

Browsers further partition cached responses by where the URL is requested from. This is called double-keying, and helps protect user privacy. With an eye out for how <iframe> elements can be abused to track users across websites, this additional key may include, depending on the browser, the top-level site, the frame site, and other boolean flags.

Variable responses and the `Vary` response header

For the same requested URL, the server may return different representations depending on preferences expressed by the client through dedicated request headers — Accept, Accept-Charset, Accept-Encoding, Accept-Language, and the experimental Client Hints — in a process known as content negotiation.

Likewise, for responses meant for individual users, the server may return different representations of a URL depending on the value of the Authorization header, and in some cases the responses are cacheable.

Storing the different representations of a URL under a single cache key would be inadvisable, since the representations are not equivalent and shouldn’t be reused. This is addressed with the Vary response header, which the server can use to list the request headers whose value may have played a role in selecting the response content.

HTTP/2 200
Vary: accept-language

Bonjour!

The Vary header in this response states that the Accept-Language request header influenced the response message.

When a response contains a Vary header, the cache must factor into its cache key the values of the nominated request headers, so that the response is generally only ever reused for requests whose values for these headers match. ☞ RFC 9111 § 4.1

Why ‘generally’? Because the RFC discourages, but technically allows, caches to essentially repurpose stored responses for the same URL, even with mismatching Vary values, if they are successfully revalidated for the new conditions. It was a decision meant to maintain compatibility with the previous iteration of HTTP core standards, and avoid flagging as non-conformant cache behavior in Chrome and Firefox: both browsers include Etags from mismatched responses as validation request preconditions.

Wildcards are also allowed. A Vary: * response header indicates that factors outside of the request message were taken into consideration for producing the response, so the cache must always validate a stored response with the server before reusing it.

Your mileage may vary

As defined, Vary is not without its problems. When it nominates request headers with high variability, the Vary header can generate very inefficient cache usage, with bucketloads of non-reusable variants in storage.

Some CDNs, such as Fastly, automatically normalize problematic headers to a more manageable set. Other services may ignore the Vary header or deem such responses uncacheable.

A number of solutions to complement or replace Vary were explored, among which:

the Key response header, letting the origin server declare how secondary cache keys for variants are to be generated;
HTTP Response Variants, laying the groundwork for clients and intermediary caches to negociate content without necessarily checking in with the origin server.

Both approaches were ultimately shelved for reasons of complexity, developer-friendliness, or limitated applicability. The latest proposal, HTTP Availability Hints — a new class of HTTP responses headers that augment the information in the Vary header field — aims to address some of these shortcomings.

Deduplicating responses with the `No-Vary-Search` response header

If Vary is about storing separately distinct representations that would otherwise be grouped under the same cache key, the No-Vary-Search HTTP Response Header Field proposal addresses the opposite problem: essentially identical content that’s cached several times over due to inconsequential variations in its URL.

With the No-Vary-Seach header, the server can declare that some or all of the URL query parameters don’t affect the response, meaning they can be ignored when generating the cache key to improve cache performance.

At this time, the No-Vary-Search header is only implemented in Chromium-based browsers.

Cache-Control response directives

`max-age=<number>`

The max-age response directive defines the response’s freshness timeline in seconds, after which the response should be considered stale. ☞ RFC 9111 § 5.2.2.1

`must-revalidate`

The must-revalidate response directive indicates that the cache must not reuse a stale response until it’s been successfully validated by the origin server. ☞ RFC 9111 § 5.2.2.2

If the server throws an error, the cache must surface that instead of reusing a stale response. If the cache is disconnected, it must produce an error with the HTTP 504 Gateway Timeout status code, or another more applicable error code.

Side effects: must-revalidate is one of the directives, along with s-maxage and public, that allow shared caches to store and reuse a response to a request containing an Authorization header, which they are generally prohibited from doing.

`no-cache`

The no-cache response directive indicates that the cache must not reuse any response until it’s successfully validated by the origin server. ☞ RFC 9111 § 5.2.2.4

This is similar to must-revalidate but refers to all cached responses, not just stale ones. In effect, no-cache is a sort of max-age=0, must-revalidate.

`no-store`

The no-store response directive indicates that private and shared caches must not store any part of the request or the response, and to never reuse the response.

“MUST NOT store in this context means that the cache MUST NOT intentionally store the information in non-volatile storage and MUST make a best-effort attempt to remove the information from volatile storage as promptly as possible after forwarding it. This directive is not a reliable or sufficient mechanism for ensuring privacy. In particular, malicious or compromised caches might not recognize or obey this directive, and communications networks might be vulnerable to eavesdropping.” ☞ RFC 9111 § 5.2.2.4

Side effects: The directive can also influence non-HTTP caches. Most browsers will exclude from the back/forward cache pages having the no-store response directive. Chrome, however, has recently started to make some of these pages eligible for bfcache when the browser deems it safe.

`must-understand`

The must-understand response directive indicates that the cache shouldn’t store or reuse responses with HTTP status codes whose semantics the cache doesn’t understand and conform to. The directive is meant to future-proof existing implementations from status codes that might have special requirements in regards to caching. ☞ RFC 9111 § 5.2.2.3

It’s recommended to use must-understand, no-store together as a fallback, and caches are encouraged to ignore the no-store directive if they do understand the semantics of the HTTP status code. This ensures older caches that don’t recognize the must-understand directive don’t cache the response at all, although by 2025 this should be an exceedingly rare sight.

`private`

The private response directive indicates that the response is meant for a single user. ☞ RFC 9111 § 5.2.2.7.

Therefore:

a shared cache must not store the response; and
a private cache may store the response even if the response wouldn’t otherwise be heuristically cacheable.

The private directive can be used to guard against other directives that might inadvertently make authenticated responses available to shared caches.

`public`

The public response directive indicates two things:

a shared cache may store and reuse a response to a request containing an Authorization header, which it’s generally prohibited from doing; and
a private cache may store the response even if the response wouldn’t otherwise be heuristically cacheable.

☞ RFC 9111 § 5.2.2.9

`s-maxage=<number>`

The s-maxage=<number> response directive is analogous to max-age, but only affects shared caches. ☞ RFC 9111 § 5.2.2.10.

The directive also incorporates the semantics of the proxy‑revalidate response directive, in that a shared cache must not use a stale response until it has been successfully validated with the origin server.

Side effects: s-maxage is one of the directives, along with must-revalidate and public, that allow shared caches to store and reuse a response to a request containing an Authorization header, which they are generally prohibited from doing.

`proxy-revalidate`

The proxy-revalidate response directive is analogous to must-revalidate, but only affects shared caches. ☞ RFC 9111 § 5.2.2.8.

`no-transform`

The no-transform response directive indicates that intermediaries, regardless of whether they implement a cache or not, must not transform the response content, such as optimizing images or compressing stylesheets and scripts. ☞ RFC 9111 § 5.2.2.6.

`stale-while-revalidate=<number>`

The stale-while-revalidate response directive was defined in RFC 5861: HTTP Cache-Control Extensions for Stale Content (2010). It indicates that the cache may use a cached response if it hasn’t exceeded its freshness lifetime by more than the specified number of seconds.

Whenever the presence of this directive causes a stale response to be served, the cache should trigger a background revalidation of the response.

Mark Nottingham, the author of RFC 5861, has written a rationale for this directive.

`stale-if-error=<number>`

Also defined in the RFC 5861 extension, the stale-if-error response directive indicates that the cache may use a cached response if it hasn’t exceeded its freshness lifetime by more than the specified number of seconds, if the attempt to validate the stale response results in an error.

HTTP Caching Tests suggests this directive is not well supported.

Cache-Control request directives

As web developers, we most often deal with Cache-Control in HTTP responses, but this header can also be included on HTTP requests. Browsers, for example, use them when the user refreshes the page.

When used in HTTP requests, Cache-Control directives express the client’s preference in regards to the freshness or age of the response. Caches reconcile these requests with the Cache-Control response directives of its cached responses.

Note: the cache option for fetch() has a separate set of values that map to Cache-Control request directives, but the mappings are not always intuitive. For example, cache: 'no-cache' maps to Cache-Control: max-age=0. For the curious, the mappings are defined here. You can always set your Cache-Control headers directly with the headers option.

`max-age=<number>`

The max-age request directive indicates that the client wants a fresh response whose age is less than or equal to the specified number of seconds. When combined with max-stale, the client will accept some stale responses. ☞ RFC 9111 § 5.2.1.1.

`max-stale=<number>`

The max-stale request directive indicates that the client will accept a stale response that has exceeded its freshness lifetime by no more than the specified number of seconds. When used without an argument, max-stale indicates that the client will accept any stale response, no matter how old. ☞ RFC 9111 § 5.2.1.2

`min-fresh=<number>`

The min-fresh request directive indicates that the client prefers a response that still has at least the specified number of seconds of freshness left. ☞ RFC 9111 § 5.2.1.3

`no-cache`

The no-cache request directive indicates that the client prefers caches not to use a stored response without successfully validating it with the origin server. ☞ RFC 9111 § 5.2.1.4

`no-store`

The no-store request directive indicates that a cache must not store any part of either this request or any response to it. The same caveats as to its response counterpart apply. ☞ RFC 9111 § 5.2.1.5

If a cache serves this request with a response that was previously stored, the no-store request directive doesn’t cause the cache to remove the response after serving it.

`no-transform`

The no-transform request directive indicates that the client is asking for intermediaries to avoid transforming the content. ☞ RFC 9111 § 5.2.1.6

`only-if-cached`

The only-if-cached request directive indicates that the client only wants a stored response. Caches should respond with either a stored response that satisfies all the other constraints, or an HTTP 504 Gateway Timeout status code. ☞ RFC 9111 § 5.2.1.7

`stale-if-error=<number>`

Similarly to its response counterpart, the stale-if-error request directive indicates that the client will accept a stale response that has exceeded its freshness lifetime by no more than the specified number of seconds, if an attempt to validate it resulted in a server error.

Browser refresh mechanisms

Browsers typically offer two refresh mechanisms:

soft reloads, triggered by the reload button, a corresponding menu item and keyboard shortcut, and the pull-to-refresh gesture in mobile browsers, are meant to get an updated representation of the page, for example getting the latest posts on a social media timeline.
hard reloads, enabled with a modifier key, skip the cache altogether and are meant to fix interrupted loads, outdated cached responses, and other broken states.

Here’s how some browsers on macOS implement these behaviors.

Soft reloads

Triggered by Ctrl + R on Windows/Linux and Command + R on macOS.

Firefox triggers a conditional request to revalidate the cached response for the main resource (the HTML file). Sub-resources such as stylesheets, scripts, and images are reloaded as usual, according to their cache directives.

Chrome behaves similarly, with the difference that the validation request for the main resource also includes a Cache-Control: max-age=0 directive (which can’t hurt).

Instead of revalidating its cached response, Safari performs a non-conditional request for the main resource, then loads sub-resources as usual.

Hard reloads

Triggered by Ctrl + Shift + R on Windows/Linux and Command + Shift + R on macOS except Safari, which uses Command + Option + R. (If you’ve applied your muscle memory to Safari before, you know all too well that the common shortcut opens Reader Mode instead…)

On a hard reload, all three browsers trigger non-conditional requests with the Cache-Control: no-cache directive on the HTML page and its sub-resources.

Curiously, once you perform a hard reload in Safari, subsequent soft reloads will still use the Cache-Control: no-cache request directive to fetch the main resource, which is probably an unintended, but otherwise benign behavior.

The `immutable` response directive

Reloading a web page didn’t always work like this. Historically, when performing a soft reload, all the sub-resources would be revalidated along with the main resource, in effect freshening up the cache for the current page.

Circa 2015, Facebook was seeing several HTTP 304 Not Modified responses on long-lived resources like scripts and stylesheets whenever a user would refresh their feed page with the browser’s reload button.

To address this issue, Patrick McManus from Mozilla proposed the immutable response directive, which later became RFC 8246: HTTP Immutable Responses.

The directive indicates that the origin server won’t update a resource during the freshness lifetime of the cached response, so a cache shouldn’t issue conditional requests for responses that are still fresh when the user reloads the page, unless the user really, really wants an updated response (e.g. a hard reload).

Around the time that support for immutable landed in Firefox 49 and Facebook began to use it to great effect, Chrome introduced a new way to perform reloads that solved the problem without introducing additional directives: instead of revalidating everything on a soft reload, just revalidate the main resource and load sub-resources as usual. Safari switched over to the new reload policy soon after [Webkit#169756], and Firefox eventually did with Firefox 100.

That leaves the immutable directive in an awkward place. Safari added support [Webkit#167497] but Chrome representatives remain unconvinced that it offers a significant benefit on top of the current reload behavior [Chromium#41253661].

Caching responses to authenticated requests

One of the more confusing aspects of HTTP caching is how various Cache-Control response directives affect the way shared caches treat responses to requests that contain an Authorization header, which are understood as specific to a single user.

As per RFC 9111 § 3.5, shared caches are not allowed to store these responses unless the response contains a Cache-Control field with a response directive that allows it to be stored by a shared cache, and the cache conforms to the requirements of that directive for that response.

The three directives that enable shared caches to store authenticated responses, and which must therefore be carefully evaluated before deploying, are:

Conversely, a private directive prevents any other directive from making authenticated responses eligible to shared caches.

Conclusion

I wrote this article to clarify for myself what the various cache directives stand for and how they overlap and interact. It only covers the main ideas, without delving into the more obscure corners of HTTP semantics. I approached the subject with a “clear cache”, and mainly used the normative references (RFC 9111 and its extensions), aided by various guides from different eras:

Caching Tutorial for Web Authors and Webmasters (1998—) by Mark Nottingham;
Caching best practices & max-age gotchas (2016) by Jake Archibald;
Prevent unnecessary network requests with the HTTP Cache (2018) by Ilya Grigorik and Jeff Posnik;
Cache control for civilians (2019–2025) and Why Do We Have a Cache-Control Request Header? (2025) by Harry Roberts;
Cache-Control Recommendations (2021) by April King;
Web Caching on MDN.

What’s interesting about these guides is that the recommendations don’t just encode an interpretation of the specs, but also incorporate safeguards against non-conformant or outdated browser caches and intermediares.

In light of developments as recent as 2022, it would be cool to figure out to what extent things have improved, and which of these safeguards can be discarded. HTTP Caching Tests seems to be a good resource for assessing the situation.

My favorite records from 2025

2025-12-20T00:00:00Z

This year I’ve listened to music for around 65,000 minutes, or about three hours daily. Here are 30 records I’ve played a lot, listed in alphabetical order.

Anna von Hausswolff Iconoclasts YEAR0001
Baxter Dury Allbarone Heavenly / PIAS
Big Thief Double Infinity 4AD
Bon Iver SABLE, fABLE Jagjaguwar
Burial Comafields / Imaginary Festival Hyperdub
Daniel Avery Tremor Domino
Die Wilde Jagd, Metropole Orkest Lux Tenera: A Rite to Joy Bureau B
Deafheaven Lonely People With Power Roadrunner
Disiniblud (Rachika Nayar, Nina Keith) Disiniblud Smugglers Way
Doves Constellations For The Lonely EMI North
Dustin O’Halloran The Chromatic Sessions Splinter
Erland Cooper Asleep On The Wing Mercury KX
Ethel Cain Willoughby Tucker, I'll Always Love You Daughters of Cain
Flock of Dimes The Life You Save
Fred again.. USB Warner
F.S.Blumm, Nils Frahm Handling Leiter
Jenny Hval Iris Silver Mist 4AD
Kangding Ray Superfluid ara
The Limiñanas Faded Because Music
Matt Berninger Get Sunk Book Records
Max Cooper On Being Mesh
Mogwai The Bad Fire Rock Action / Temporary Residence
Nils Frahm Night Leiter
Rival Consoles Landscape from Memory Erased Tapes
Roger Eno Without Wind, Without Air Deutsche Grammophon
Rone Le Mohican OST InFiné
Sharon Van Etten Sharon Van Etten & The Attachment Theory Jagjaguwar
Sofia Kourtesis Volver Ninja Tune
Vanessa Wagner Philip Glass: The Complete Piano Etudes InFiné
Yoshika Colwell On The Wing PIAS

I’ve also enjoyed:

Abul Mogard, Rafael Anton Irisarri — Live at Le Guess Who? [Black Knoll Editions]
Abul Mogard — Quiet Pieces [Soft Echoes]
Adrian Crowley — Measure Of Joy [Valley of Eyes]
Alexandre Tharaud — Satie: Discoveries [Warner Classics]
All Seeing Dolls (Anton Newcombe, Dot Allison) — Parallel [A Records]
Anika — Abyss [Sacred Bones]
Anouar Brahem — After the Last Sky [ECM]
Babx — Amour Colosse [La Familia]
Bacao Rhythm & Steel Band — Big Crown Vaults Vol. 4 [Big Crown]
Balmorhea — The Trap OST [Deutsche Grammophon]
BJ Nilsen — True than Nature [Ideologic Organ]
Bicep — Chroma 000 / Takkuuk OST [Ninja Tune]
Biosphere — The Way of Time [AD 93]
Blanck Mass — She Rides Shotgun OST [Invada]
Blawan — SickElixir [XL]
Blonde Redhead — The Shadow Of The Guest [section1]
Brian Eno, Beatie Wolfe — Lateral / Liminal / Luminal [Verve]
Caroline — Caroline 2 [Rough Trade]
Cherrystones, Demdike Stare — Who Owns The Dark? [DDS]
Christopher Willits — New Moon [Ghostly]
Clipping. — Dead Channel Sky Plus [Sub Pop]
Darkside — Nothing [Matador]
Demdike Stare, Kristen Pilon — To Cut and Shoot [DDS]
Destroyer — Dan’s Boogie [Merge]
DJ Koze — Music Can Hear Us [Pampa]
DJ Python — I was put on this earth [XL]
Djrum — Under Tangled Silence [Houndstooth]
Donato Dozzy, Sabla — Morpho [Gang of Ducks]
Dustin O’Halloran — Eleanor The Great OST [Milan]
Echolalia — Echolalia [Full Time Hobby]
El Michels Affair — 24 Hr Sports [Big Crown]
Emma Ruth Rundle — Music from the Bella Vista [s/r]
Erland Cooper — Berriedale [Mercury Classics]
Ethel Cain — Perverts [Daughters of Cain]
Fabrizio Paterlini — Layers [Believe]
Greet Death — Die In Love [Deathwish]
HAAi — Humanise [Mute]
Hilary Woods — Night Criú [Sacred Bones]
Hildur Guðnadóttir — Where to From [Deutsche Grammophon]
James Holden, Wacław Zimpel — The Universe Will Take Care Of You [Border Community]
Jay-Jay Johanson — Backstage [29 Music]
Jefre Cantu–Ledesma — Gift Songs [Mexican Summer]
John Maus — Later Than You Think [Young]
Kali Malone, Drew McDowall — Magnetism [Ideologic Organ]
Kara–Lis Coverdale — Changes in Air [Smalltown Supersound]
Keaton Henson — Parader [PIAS]
Keeley Forsyth, Matthew Bourne — Hand To Mouth [s/r]
Lawrence English — Even The Horizon Knows Its Bounds [Room40]
Lido Pimienta — La Belleza [Anti]
Loscil — Lake Fire [Kranky]
Maria Somerville — Luster [4AD]
Marissa Nadler — New Radiations [Sacred Bones / Bella Union]
Max Richter — Hamnet OST [Deutsche Grammophon]
Meitei / 冥丁 — Sen'nyū / 泉涌 [Kitchen Label]
Melaine Dalibert, David Sylvian — Vermilion Hours [Ici d’ailleurs]
Melody’s Echo Chamber — Unclouded [Domino]
Milkweed — Remscéla [Broadside Hacks]
Murcof — Twin Color (Extended Play No. 2) [InFiné]
Múm — History of Silence [Morr Music]
Nilüfer Yanya — Dancing Shoes [Ninja Tunes]
Olof Dreijer — Iris [Rabid]
Oren Ambarchi, Eric Thielemans — Kind Regards [AD 93]
Oren Ambarchi, Fredrik Rasten — Dragon’s Return [Viernullvier]
Oren Ambarchi, Johan Berthling, Andreas Werliin — Ghosted III [Drag City]
Pelican — Flickering Resonance [Run For Cover]
Perfume Genius — Glory [Matador]
Peter Chilvers — Dust 4 [Curious Music]
Rival Consoles — MindsEye OST [Erased Tapes]
Rosalía — Lux [Columbia]
S. Carey — Watercress [Jagjaguwar]
Sandwell District — End Beginnings [Point of Departure]
Sarah Davachi — Basse Brevis [Potraits GRM]
Stephen O’Malley — But remember what you have had [Potraits GRM]
Stereolab — Instant Holograms On Metal Film [Duophonic UHF Disks / Warp]
Steve Gunn — Daylight Daylight [No Quarter]
Sunn O))) — Eternity’s Pillars b/w Raise the Chalice & Reverential [Sub Pop]
Sławomir Zubrzycki — Viola Organista: Monologues & Dialogues [Leiter]
The Antlers — Blight [Transgressive]
The Black Dog — My Brutal Life EP / My Brutal Life 2 [Dust Science]
The Black Heart Procession — Hearts and Tanks [Solid Brass]
The Black Keys — No Rain, No Flowers [Easy Eye Sound, Warner]
The Weather Station — Humanhood [Fat Possum]
Thylacine — Roads Vol. 3 [Intuitive Records]
Tortoise — Touch [Intl Anthem]
U.S. Girls — Scratch It [4AD]
Vanishing Twin — In Piscina! [Fire Records]
Verses GT (Jacques Greene, Nosaj Thing) — Verses GT [Luckyme]
William Basinski, Richard Chartier — Aurora Terminalis [LINE]
Yasmine Hamdan — I remember I forget بنسى وبتذكر [Crammed Discs, PIAS]
Ólafur Arnalds, Talos — A Dawning [OPIA, Mercury KX]

From previous years. Played a lot of Living Circle (Fat Cat, 2023) and Shifts (Fat Cat, 2019) from Shida Shahabi, whom I’d seen in 2023 opening for AWVFTS at the Barbican but forgot to follow up on, only to go all wow, what is this heavenly music?? and why does it feel so eerily familiar? when my friend Alex recommended it a few months ago. Also big on MONO’s Oath (2024), which I discovered too late to include in last year’s list.

Live shows. Sharon van Etten in Berlin; Matt Berninger in Glasgow; Fred again.. in Rome.

This has been the 12th edition of my favorite records. Timeline: 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025.

Other 2025 lists: Boomkat, Bleep, Rough Trade, The Quietus, The Wire, Jon Hicks, Simon Collison, Scott Boms.

My favorite records from 2024

2024-12-22T00:00:00Z

This year I’ve listened to music for almost 100,000 minutes, or about four hours daily. Here are 47 albums I’ve played a lot, listed in alphabetical order.

Adrianne Lenker Bright Future 4AD
Alva Noto HYbr:ID III Noton
Bacao Rhythm & Steel Band BRSB Big Crown
Ben Lukas Boysen Alta Ripa Erased Tapes
Beth Gibbons Lives Outgrown Domino
Bon Iver Sable, Jagjaguwar
Caribou Honey City Slang
Coco 2 Self released
Daniel Herskedal & Mattia Vlad Morleo Echoes of Solitude E2
Daniel Herskedal A Single Sunbeam E2
Daniel Herskedal Call For Winter II: Resonance Edition Records
Dustin O’Halloran 1001 Deutsche Grammophon
Efterklang Things We Have in Common City Slang
Erland Cooper Carve the Runes Then Be Content With Silence Mercury KX
Fred again.. ten days Atlantic
Godspeed You! Black Emperor “NO TITLE AS OF 13 FEBRUARY 2024 28,340 DEAD” Constellation
Hermanos Gutiérrez Sonido Cósmico Easy Eye Sound
Jamie xx In Waves Young
Jon Hopkins Ritual Domino
Kali Malone All Life Long Ideologic Organ
Keaton Henson Somnambulant Cycles Mercury KX
Kessoncoda Outerstate Gondwana Records
Khruangbin A La Sala Dead Oceans
Kiasmos II Erased Tapes
Laurel Halo Octavia Portraits GRM / Shelter Press
Loma How Will I Live Without a Body? Sub Pop
Loscil & Lawrence English Chroma Self-released
Masayoshi Fujita Migratory Erased Tapes
Max Richter In A Landscape Decca
Michael A. Muller Mirror Music Deutsche Grammophon
Molly Lewis On The Lips Jagjaguwar
Nada Surf Moon Mirror New West
Nick Cave & The Bad Seeds Wild God PIAS
Nils Frahm Day Leiter
Nonkeen All good? Leiter
Otto A. Totland Exin Leiter
Phosphorescent Revelator Verve
Roger Eno The Skies: Rarities Deutsche Grammophon
The Black Dog Other, Like Me Dust Science
The Black Keys Ohio Players Easy Eye Sound
The Cure Songs Of A Lost World Polydor
The Decemberists As It Ever Was, So It Will Be Again YABB
The Smile Wall of Eyes XL
Tindersticks Soft Tissue City Slang
Tristwch Y Fenywod Tristwch Y Fenywod Night School
Waxahatchee Tigers Blood Anti–
WhoMadeWho Kiss & Forget The Moment

Other albums I’ve enjoyed this year:

Adam Wiltzie — Eleven Fugues For Sodium Pentothal [Kranky]
Alessandra Novaga — The Artistic Image Is Always a Miracle [Die Schachtel]
Alison Cotton — Engelchen [Rocket Recordings]
Alva Noto — Xerrox, Vol.5 [Noton]
Angel Olsen — Cosmic Waves Volume 1 [Jagjaguwaar]
Antonina Nowacka — Sylphine Soporifera [Mondoj]
Aphex Twin — Music From The Merch Desk (2016–2023) [Warp]
Ben Lukas Boysen — Falling into Place OST [Erased Tapes]
Blanck Mass — Bloodhound / You [Weirding Way]
Bobby Oroza — Goddess / Queen of the Barrio [Big Crown]
Bolis Pupul — Letter To Yu [Deewee]
Bruce Brubaker — Eno Piano 2 [InFiné]
Burial & Kode9 — Phoneglow / Eyes Go Blank [Hyperdub]
Burial — Dreamfear / Boy Sent From Above [XL]
Chastity Belt — Live Laugh Love [Suicide Squeeze]
Christian Löffler — A Life [Ki Records]
Chuck Johnson — Sun Glories [Western Vinyl]
Cigarettes After Sex — X’s [Partisan]
Cowboy Sadness — Selected Jambient Works vol. I [People Teeth]
Craven Faults — Bounds [The Leaf Label]
Donato Dozzy — Magda [Spazio Disponibile]
Four Tet — Three [Text]
Ganavya — Draw Something Beautiful [Leiter]
Hamish Hawk — A Firmer Hand [So Recordings]
Helado Negro — Phasor [4AD]
Idles — Tangk [Partisan]
Joep Beving & Maarten Vos — Vision of Contentment [Leiter]
Keeley Forsyth — The Hollow [Fat Cat]
Kelly Lee Owens — Dreamstate [dh2]
King Hannah — Big Swimmer [City Slang]
Lionel Limiñana, David Menke — Heureux Gagnants OST [Berreto Music]
Loscil — Umbel [Self-released]
Marika Hackman — Big Sigh [Chrysalis]
Max Cooper — Seme [Mesh]
Max Richter — Sleep (Piano Edition) [Deutsche Grammophon]
Michelle Gurevich — It Was the Moment [Self-released]
Milkweed — Folklore 1979 [Broadside Hacks]
Murcof — Twin Color, Vol. 1 [InFiné]
Nils Frahm — Paris [Leiter]
Oren Ambarchi, Johan Berthling & Andreas Werliin — Ghosted II [Drag City]
Pelican — Adrift / Tending the Embers [Pelicansong]
Philip Glass — Philip Glass Solo [Orange Mountain Music]
Phosphorescent — Oh, Canada OST [Verve]
Ryuichi Sakamoto — Opus [Milan Records]
Saint Etienne — The Night [PIAS]
Sarah Davachi — The Head as Form’d in the Crier’s Choir [Late Music]
The Black Dog — Isolation EP / Seclusion EP [Dust Science]
The National — Rome [4AD]
The Smile — Cutouts [XL]
Timber Timbre — Interview [Hot Dreams]
Tindersticks — Mayday ’22 [Lucky Dog]
Tycho — Infinite Health [Ninja Tune]
Valerinne — Ver Sacrum [Self-released]
Woods — Five More Flowers [Woodsist]

Finally, a few earworms:

Acid Arab — Atlas (feat. Cem Yıldız)
Arca & Tokischa — Chama
Beirut — Caspian Tiger
Björk & Rosalía — Oral
Brian Eno — All I Remember (from the Eno OST)
Childish Gambino — Lithonia
Erika Isac — Macarena
Jamie XX — It’s So Good
Jon Hopkins & Ólafur Arnalds — Forever Held
Keaton Henson & Daniel Herskedal — Try
Ladaniva — Saraiman
Sevdaliza — Alibi (feat. Pabllo Vittar & Yseult)
Sevdaliza — Ride Or Die, pt. 2 (feat. Villano Antillano & Tokischa)
The Dare — Girls

Live shows. Khruangbin, Massive Attack, and Tigran Hamasyan in Cluj. Tindersticks in Barcelona.

This has been the 11th edition of my favorite records. Timeline: 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025.

Other 2024 lists: Boomkat, Bleep, Rough Trade, The Quietus, The Wire, Jon Hicks, Simon Collison.

My “Skip to content” markup was breaking the back button on iOS

2024-04-13T00:00:00Z

One of the great joys of having your own website is being able to publish all sorts of random pages, such as this listing of DOM events, because why not.

Perusing these sort of reference pages I built for myself, it became increasingly grating that the basic feature of maintaining the scroll position during navigation seemed to be broken on iOS Safari.

I checked: the issue didn’t affect all websites, just my three-HTML-files-in-a-trenchoat website. Whenever I followed an external link and tapped the Back button, Safari frustratingly scrolled to the top of my original page, instead of keeping my place on the page.

Video: I open an article on my website about my favorite albums from last year. I scroll down to Altın Gün and tap the link, which takes me to the album’s Bandcamp page. When I tap the Back button, the article is scrolled back to the h1 heading.

The problem: `<main tabindex=-1>` loses your scroll position

A key detail in the video is that Safari doesn’t scroll the page all the way back to the top, but to the <h1> heading. This suggests it has some sort of heuristic that leads it to believe that’s where the focus/scroll should be.

I started by looking at how desktop browsers place the focus when returning to the page, by inspecting document.activeElement:

Firefox returns the focus to the <a> element that produced the navigation;
Chrome returns the focus to the <body> element;
Safari returns the focus to the <main> element.

That Safari focuses the <main> element was a clue to what might be going on with the mobile version.

Turns out my Skip to content markup — more specifically, the tabindex=-1 on the <main> element — is what makes Safari scroll the <main> element’s top edge into view when you return from a navigation.

<a href="#main">Skip to content</a>
…
<main id="main" tabindex="-1">…</main>

Removing the tabindex from the <main> element made iOS Safari behave.

Is the attribute needed in the first place? To include tabindex has long been recommended to ensure that a variety of browsers and assistive technology move the focus properly to the destination element. A host of issues that <main tabindex=-1> is supposed to solve have been fixed in the meantime, but not all of them.

It seems some sort of manual focus management is still in order, and without any obvious documented downsides, the pattern remains popular. But breaking the scroll position is a pretty significant drawback, one that warrants a re-evaluation of this approach, at least until Safari fixes the issue.

The solution: to be discussed

For now, I have removed the tabindex attribute, and will be looking for an alternate solution. Ultimately, it might involve JavaScript, as for the pattern used on gov.uk, or changing the anchor to point to an element inside <main>, such as the <h1>.

I have also made a test case and submitted WebKit#272624 about it. Testing in Browserstack reveals that the issue was introduced somewhere around iOS/Safari 14 back in 2020.

Update March 2026: Manuel Matuzović tests whether tabindex is still required and concludes we may be able to omit the attribute.

How to think about HTML responsive images

2024-04-06T00:00:00Z

The days with an immobilized knee are long and I’ve just read through the Images section of the HTML Standard, as one does, hoping to better understand how responsive images work.

What’s a responsive image?

The term responsive image encompasses two complementary approaches.

In the context of responsive web design, a responsive image is one that’s made fluid with the width, height, aspect-ratio, and object-* properties, as part of CSS layouts that change with the viewport size and other media conditions.

But what the HTML Standard is concerned with, and what this article talks about, are the so-called “adaptive images” enabled by the srcset and sizes attributes on <img>, and the dedicated <picture> and <source> elements. These HTML features help the browser pick the most appropriate image content for the current environment.

Here’s how I made sense of responsive image content, progressing from simpler to more complicated — and then back to simple.

Level 1: one image, one resolution

Let’s start with the simplest image markup:

<img src="puppy.jpg" alt="A black and white pupper, glancing inquisitively">

In the absence of any attributes or styles to dictate otherwise, puppy.jpg renders at its natural width and height, 120px by 150px in CSS pixels.

A CSS pixel is defined as the visual angle of one pixel on a device with a device pixel density of 96dpi and a distance from the reader of an arm’s length or about 0.0213 degrees.

Modern phones are used at a much smaller distance than arm’s length. Their screens need to have a greater density to look good: the visual angle of 0.0213° at a distance of 50 centimeters computes to a pixel on a 137ppi (pixels per inch) display.

The 2556×1179px physical resolution of an iPhone 15, packed in a display that measures 6.1 inches diagonally, gives it a pixel density of 460 ppi. That’s more than three times denser than our nominal CSS display. The iPhone can therefore comfortably use three device pixels to draw each CSS pixel, and web content will have more or less the same size as when viewed on a regular monitor placed further away.

This ratio between a device pixel and a CSS pixel is called the device pixel ratio and is available on window.devicePixelRatio. The device pixel ratio is not a fixed measure of the capabilities of the physical display. The display resolution chosen by the user, or zooming in and out of the web page, can also influence the ratio. Zooming into the page makes for fewer, larger CSS pixels, so the device pixel ratio increases.

Back to our image. On devices that have a device pixel ratio of 2 or 3 (usually called retina displays regardless of brand), the image looks blurry at its natural size: the display can potentially use two or three separate device pixels in the space of a CSS pixel, but we only give it one image pixel to draw. On these denser displays, the image looks better when scaled down to increase its density to match that of the display. When one image pixel becomes one device pixel, instead of two or three, the image is as crisp as it gets.

<img src="puppy.jpg" width="120" alt="…"> <!-- 1x -->
<img src="puppy.jpg"  width="60" alt="…"> <!-- 2x -->
<img src="puppy.jpg"  width="40" alt="…"> <!-- 3x -->

The same 120px by 150px image is rendered at its natural size, then scaled down in half, and finally to 1/3 of its natural width.

The rendered size of an <img> element can be adjusted with the width and height HTML attributes, or with equivalent CSS properties.

It’s best to include explicit width and height attributes on the <img>. That way the browser can leave room for the image beforehand and prevent layout shifts as the image loads. It also helps presentation in contexts that don’t ship the author’s CSS, such as RSS feeds. (I can count at least three feeds in my reader with huge, distracting icons that are, no doubt, stray images without sizing attributes.)

Level 2: one image, many resolutions

For a sharp image on displays of various densities, shrinking the same image file to various degrees to increase its density is insufficient. We need commensurately larger images that pack more detail.

Images with progressively larger resolutions, representing the same content.

<img src="puppy.jpg" width="120" alt="…"> <!-- 1x -->
<img src="puppy-hd.jpg" width="120" alt="…"> <!-- 2x -->
<img src="puppy-ultra-hd.jpg" width="120" alt="…"> <!-- 3x -->

When shrunk to their ideal density, all three images render at the same size.

The srcset attribute lets you pack all the images on a single <img> tag, and let the browser choose the most appropriate for each situation.

<img 
	srcset="puppy-ultra-hd.jpg 3x, puppy-hd.jpg 2x" 
	src="puppy.jpg"
	alt="…"
>

Each entry in srcset has a pixel density descriptor: a floating-point number followed by the unit x. The descriptor next to each image source declares the image density at which that source is meant to be rendered. If omitted for a source, a 1x descriptor is assumed.

The src attribute on the <img> is both a fallback for browsers that don’t support srcset (a vanishingly small lot) and a contribution to the set of image source candidates with an implicit 1x pixel density descriptor.

The browser will select the most appropriate image source out of the set of candidates, based not only on the display density, but possibly other factors such as network speed and mobile data preferences. This choice is made in an implementation-defined manner, meaning the browser is free to choose whatever it thinks works best.

In the absence of width and height HTML attributes to dictate otherwise, whatever image source is selected will be rendered at its density-corrected natural dimensions, which are the image’s natural dimensions divided by its declared density. The density-corrected natural dimensions can be accessed on the DOM object’s naturalWidth and naturalHeight properties:

img.naturalWidth === intrinsicWidth / density;
img.naturalHeight === intrinsicHeight / density;

At 1x density, the element’s density-corrected natural dimensions correspond to the file’s natural (intrinsic) dimensions. At 2x density, the image is rendered at half the number of CSS pixels as the file’s natural dimensions.

Because of the way we’ve generated our three images and declared their intended densities, they all render at a width of 120px, regardless of which image source the browser chooses. So there’s no issue with adding the recommended explicit width and height attributes:

<img 
	srcset="puppy-ultra-hd.jpg 3x, puppy-hd.jpg 2x" 
	src="puppy.jpg"
	width="120"
	height="150"
	alt="…"
>

To tell which image source the browser has chosen at any given point, look at the currentSrc property on the image element.

Level 3: dynamic image density

The srcset attribute with pixel density descriptors works well for images that are meant to be displayed at their (density-corrected) natural size.

But images often participate in responsive layouts and are made fluid with CSS, so an image renders at various densities depending on the layout. On a large screen, the image may be part of a three-column layout. On a smaller screen, the layout may collapse to a single column with full-width images.

This is a case where the image density changes but the display density doesn’t, so srcset with density descriptors won’t cut it.

There’s a second way we can use srcset. To help the browser choose an image source of appropriate density when media conditions change, we can swap our density descriptors for a combination of width descriptors and a separate sizes attribute.

Instead of describing the intended image densities, width descriptors (using the w suffix) declare the natural (intrinsic) width of each of the image sources.

This information, by itself, is not enough for the browser to make a meaningful choice. It needs to know how the image is going to be laid out. This is accomplished with the sizes attribute, which declares the layout width of the image in one or more media conditions.

<img
	 srcset="
		 puppy-ultra-hd.jpg 360w,
		 puppy-hd.jpg 240w,
		 puppy.jpg 120w
	 "
	 sizes="(min-width: 400px) 10em, 80vw"
	 alt="…"
>

The srcset attribute declares three image sources using width (w) descriptors: one 360px wide, one 240px wide, and a final one 120px wide. The sizes attribute describes how the image is laid out: on devices wider than 400px, they are rendered at a width of 10em, otherwise they occupy 80% of the viewport width.

We’re free to declare the layout width with any CSS unit for <length>, and use calc() and other math functions, to try to roughly match the image’s actual layout width.

Percentages aren’t allowed in the sizes attribute, as they wouldn’t match the usual understanding of percentage of the parent’s width. Remember that choosing image sources for eagerly-loaded images happens before layout, so we can only refer to things known beforehand, such as the viewport’s dimensions.

As we’ll see later on, lazily-loaded images, which are fetched after layout, don’t need to juggle any of this sizes stuff.

The purpose of the sizes attribute is to help convert width descriptors to density descriptors. Width descriptors are turned into density descriptors by:

identifying the size that matches the current media conditions among the values in sizes;
resolving the size value to CSS pixels;
dividing the declared width by that amount of pixels.

The density computed from a source’s width descriptor and a layout size is called the source’s effective density.

In a larger viewport that’s, say, 1920 pixels wide, our image is intended to be displayed at a width of 10em, which computes to 10 * 16px = 160px in CSS pixels. The large image source, having a declared width of 360px, when rendered 160px wide, will have an effective density of 360/160 = 2.25. The medium and small images will have effective densities of 1.5 and 0.75 respectively. On this viewport width, the equivalent srcset with density descriptors is:

<img
	 srcset="
		 puppy-ultra-hd.jpg 2.25x,
		 puppy-hd.jpg 1.5x,
		 puppy.jpg 0.75x
	 "
	 style="width: 10em"
	 alt="…"
>

In a smaller viewport that is 300 pixels wide, our images are meant to be displayed at 80vw, which computes to 300px * 80/100 = 240px CSS pixels. In these media conditions, our three image sources will have effective densities of 1.5, 1, and 0.5 respectively. On this smaller viewport width, the equivalent srcset with density descriptors is:

<img
	 srcset="
		 puppy-ultra-hd.jpg 1.5x,
		 puppy-hd.jpg 1x,
		 puppy.jpg 0.5x
	 "
	 style="width: 80vw"
	 alt="…"
>

Therefore, srcset with width descriptors, combined with sizes, is a way to assign a dynamic density to image sources, roughly based on how the image is laid out in various media conditions.

When srcset uses width descriptors, the image’s src is purely a fallback for browsers that don’t support it. The attribute can’t contribute an image source, because there’s no way to attach a width descriptor to its value.

The two srcset flavors are both ultimately resolved to a set of image sources with density descriptors, but they don’t mix well. You can’t use width descriptors for some sources and density descriptors for others in a single srcset. Either use width descriptors with the sizes attribute, or density descriptors without the sizes attribute. In the former case, sizes is necessary; in the latter, it serves no purpose and is ignored.

Don’t rely on the default. When we say sizes is necessary for width descriptors, it means a HTML document omitting it won’t validate and it won’t be canon. But HTML is tolerant of author errors and defaults to a value of 100vw. As Eric Portis explains, you don’t want to rely on that default, as it potentially nudges the browser to fetch images much larger than needed, defeating the whole purpose of the feature.

An exception to the requirement are lazy-loaded, auto-sized images, for which omitting the sizes attribute on any <source> element is equivalent to sizes="auto" rather than sizes="100vw".

Level 4: the `<picture>` element

The srcset attribute on the <img> merely provides a set of candidate sources to the browser, along with enough information about them to allow for an informed choice. As Mat Marquis writes in the Learn Images course, it makes srcset a descriptive syntax. It says to the browser: here’s what I have, now you pick!

There’s another HTML feature with which we can be more prescriptive and say only consider these image sources if these conditions are met. This is done with one or more <source> elements associated with the <img> by virtue of being wrapped together in a <picture> element:

<picture>
	<source …>
	<source …>
	<img …>
</picture>

The <picture> element is a container that augments its inner <img> by providing more sets of image sources to choose from, declared with <source> elements. If the browser doesn’t support these elements, no harm is done: they’re ignored and the <img> works as if it were alone.

(You might say <picture> is the original HTML web component, but that’s an angle for another day.)

Like image elements, <source>s use the srcset and sizes attributes to declare their set of image sources. In addition, <source> elements accept two attributes that condition their contribution:

the type attribute declares the media type of the image set, so that the browser can skip image formats it doesn’t understand;
the media attribute declares the media conditions where the image set makes sense, which the browser skips if they don’t apply.

The first source that matches the current media conditions and media type capabilities defines the set of image candidates that’s supplied to the <img> element. The browser chooses the most appropriate image from that set, just as if the source’s srcset and sizes attributes had been declared on the <img> itself.

If no sources apply to the current circumstances, the image’s own srcset or src is used as a fallback.

The `type` attribute

The type attribute enables us to serve newer, more efficient image formats to supporting browsers without ruining it for the others. If a browser can’t use image/avif, or image/webp it can just ignore the respective <source> elements.

<picture>
	<source srcset='puppy.avif' type='image/avif'>
	<source srcset='puppy.webp' type='image/webp'>
	<img src='puppy.jpg' alt='…'>
</picture>

Serving newer image formats safely with <source> elements with a type attribute. If we omitted the type attribute, or used puppy.avif and puppy.webp directly in the image’s srcset attribute, unsuspecting older browsers would fetch formats they don’t understand, resulting in a broken image.

The `media` attribute

The media attribute can contain any media condition. We could, for example, serve an alternative image for dark mode, and a higher-contrast version appropriate for printing.

Three styles for illustrating a portion of the macOS display settings: light mode, dark mode, and high-contrast mode.

<picture>
	<source media='(prefers-color-scheme: dark)' srcset='macos-dark.png'>
	<source media='print' srcset='macos-contrast.png'>
	<img src='macos-light.png' alt='…'>
</picture>

A <picture> element uses the three styles in <source> elements, with the appropriate media queries. Above the code: Live picture, as chosen by the browser. Try switching to dark mode, or print-previewing the page to see the effect.

The same rules for srcset and sizes apply to <source> elements: you can’t mix density descriptors and width descriptors in a single srcset, and you must use the sizes attribute with, and only with, width descriptors.

<source> elements also have rules of their own:

each <source> must generally have some sort of type or media condition, or both, attached to it. Only if the image itself doesn’t have a srcset already, one bare, conditionless <source> is allowed.
there’s no src attribute on <source> because it would be confusing and besides, any valid src can be plopped into srcset instead.

Level 5: art direction

While a srcset is meant to represent the same image content at different scales, multiple <source> elements can represent different content altogether. In the previous example, we used the media attribute to serve images styled according to user preferences.

The different images don’t need to have the same aspect ratio. In fact, there’s nothing stopping us from serving radically different images in various scenarios. On a large screen, a photograph could be a wide shot of the subject, while on smaller screens that can be cropped closer to the action.

The technique is often called art-directing responsive images.

Art directing an image: a close-up crop of 200px by 200px is chosen for smaller screens.

Since setting the width and height on the <img> element is important, it seemed like a great idea to add support for width and height attributes on <source> elements. The dimensions can then be imparted to the image element when the source is selected. (The case for sources also getting their own alt attribute is still being made.)

<picture>
	<source srcset="puppy-closeup.jpg" width="200" height="200" media="(max-width: 40em)">
	<img src="puppy-ultra-hd.jpg" width="450" height="600">
</picture>

An art-directed responsive image displays a close-up of the subject when the viewport is less than 40em (640px) wide. Notice the width and height attributes on the <source> element.

Cropping after image load: Images can also be art-directed with CSS using the object-fit, object-position, and object-view-box properties. However, to the extent that is practical, using <picture> to serve the pre-cropped images saves some bandwidth and compute energy.

Extra credit: lazy images with `sizes=auto`

As promised in the introduction, we end with a bit of respite from the complexity of responsive image markup.

A recent addition to the HTML Standard allows lazily-loaded images to ditch the arduous, hand-coded, approximated values in the sizes attribute. Instead, with the auto value, the browser uses the image’s actual layout width to compute more accurate densities for the image candidates.

Eric Portis covers the feature and its caveats in admirable detail, so I won’t repeat the points here. But below is the markup for an image that’s sized at a height of 20vh whose appropriate source is selected without us specifying the layout widths manually.

We noted earlier that the sizes attribute is generally mandatory on any <img> or <source> element that uses width descriptors in the srcset attribute. For lazy-loaded, auto-sized images, however, we can also omit the sizes attribute on preceding <source> elements, and it will be interpreted as equivalent to sizes="auto".

<img
	 srcset="
		 puppy-ultra-hd.jpg 360w,
		 puppy-hd.jpg 240w,
		 puppy.jpg 120w
	 "
	 width="240"
	 height="300"
	 style="height: 20vh; width: auto"
	 loading="lazy"
	 sizes="auto"
	 alt="…"
>

Using sizes=auto is only possible when the image is lazy-loaded via the loading=lazy attribute. The way auto-sizing is implemented in the HTML specification, some way to restore the underlying image’s aspect ratio is required. The width and height attributes work well and are also recommended to prevent layout shifts.

How browsers choose one image

Now that we’ve covered the theory of providing image source candidates, let’s find out how browsers actually pick the most appropriate one.

I’ve run a couple of quick tests on MacBook Pro and iPhone, and dipped into browser source code to confirm the behavior (insofar as I am looking at the right code to begin with).

Density descriptors in `srcset`

The image above uses several image sources of 300×200px constant size, but labeled and declared with density descriptors ranging from 0.1x to 4x in the srcset attribute. This shows us which source the browser picks. Test: image density selection.

Firefox. At 100% zoom, the device pixel ratio is 2. Zooming in and out of the page updates the DPR and re-fetches the image with the smallest density that’s higher than the current DPR, or the highest density available when all densities are too small. Relevant code in ResponsiveImageSelector.cpp#L331.

Chrome. The browser selects the image with the density closest to the DPR when loading the page. Zooming in and out of the page updates the DPR, but the browser will only fetch another, more appropriate image on page refresh. It will also prefer the densest image source it has in its cache, even if its density is much higher than needed. Relevant code in html_srcset_parser.cc#L424.

Safari. The DPR is fixed to a value of 2 on the MacBook and 3 on the iPhone. Zooming in and out of the page doesn’t update the DPR or fetch another image. Like in Firefox, you get the image with the smallest density that’s higher than this fixed DPR. Relevant code in HTMLSrcsetParser.cpp#L266.

All in all, given the browser algorithms, every image source is evaluated, and the order in srcset doesn’t affect the choice. Do keep in mind that only the first item for each particular density (be it declared density or effective density) is kept, and any duplicates are pruned.

As far as I can tell, browsers aren’t currently applying any of the sophisticated decision-making envisioned by the HTML Standard. An image density close to the current DPR is always favored.

With the exception of Firefox, which responds to zooming, browsers stick to their choice of image source throughout the page session. Pinch-zooming does not affect DPR in any browser, so raster images don’t get magically enhanced if you pinch into them (this is by design).

Width descriptors in `srcset`

The image above uses several image sources with the same aspect ratio but different scales, labeled and declared with width descriptors ranging from 300w to 3000w in the srcset. The declared layout width of the image is sizes="100vw". This shows us which image source the browser picks.

(Note: To make it fit in the article’s layout, the image is made responsive with max-width: 100%; height: auto. Open the test in a separate tab to evaluate more accurately: Test: image width selection)

When using width descriptors in srcset, we expect the browser to factor in the sizes attribute (here having a value of 100vw) to compute density descriptors that update along with the viewport. It’s no surprise then that browsers behave more or less like with density descriptors, with the added benefit that the image sources get re-evaluated more often.

Firefox. Resizing the browser window causes the browser to choose the image with the appropriate effective density at any given moment. Zooming in and out of the page re-evaluates things but generally doesn’t produce any effect: while the size of the CSS pixel increases (and with it, the DPR), 100vw evaluates to fewer CSS pixels, which results in more or less constant image density throughout.

Chrome. Like in Firefox, resizing the browser window causes the browser to re-evaluate the image sources based on their effective density. As seen with the density descriptor test, Chrome caches the images it fetches and always uses the densest available. Once fetched for a large viewport, a dense image will be used even as you shrink the viewport.

Safari is the most conservative about fetching other images. With sizes="100vw", the image source is evaluated once on page load, and resizing the browser window has no effect. With an attribute that contains media conditions, such as sizes="(max-width: 400px) 25vw, (max-width: 800px) 50vw, 100vw", it re-evaluates the image sources once a different size applies.

Safari’s approach means sizes="100vw" does not make an image fluid like in the other browsers, which update the density-corrected natural dimensions after each resize. The dimensions are only computed once, when the source is first rendered.

Conclusion

I haven’t included more elaborate browser tests because they make my brain hurt, but we’ve hopefully made sense of how HTML responsive images are specified to work and got a glimpse of how current browsers choose image sources.

Responsive images have been available in HTML for a decade. They have been written about extensively, often covering the same ground and angle. Here are some pointers:

Learn images by Mat Marquis
Srcset and sizes (2014) by Eric Portis
Responsive Images 101 (2015), a ten-part series (and book) by Jason Grigsby
Eric Portis’s Observable notebook w descriptors and sizes: Under the hood explains these concepts and behaviors with nice-looking, interactive browser tests.

Changelog

August 2025. Added some sample markup for sizes="auto" and clarified that an omitted sizes attribute on <source> elements for an lazy-loaded, auto-sized image is equivalent to sizes="auto" rather than sizes="100vw".

My favorite records from 2023

2023-12-23T00:00:00Z

Note: I will be updating this list beyond 2023. The additions are marked with the manicule (☞).

Heavy rotation

Some of the albums I’ve listened to a lot this year, in alphabetical order.

Alternativ Quartet — Deocamdată suntem [s/r]
Alternativ Quartet — Departe de solstițiu [s/r]
Arvo Pärt — Tractus [ECM]
Balmorhea — Pendant World [Deutsche Grammophon]
Baxter Dury — I Thought I was Better than You [Heavenly]
Beirut — Hadsel [Pompeii]
Ben Howard — Is it? [Island]
The Blaze — Jungle [Animal63]
Blonde Redhead — Sit Down for Dinner [Section1]
Brian Eno & Fred again.. — Secret Life [Text]
Bruce Brubaker — Eno Piano [InFiné]
Constant Smiles — Kenneth Anger [Sacred Bones]
Devendra Banhart — Flying Wig [Mexican Summer]
El Michels Affair & Black Thought — Glorious Game [Big Crown]
Eluvium — (Whirring Marvels In) Consensus Reality [Temporary Residence]
Erland Cooper & Scottish Ensemble — Folded Landscapes [Mercury KX]
Fever Ray — Radical Romantics [Rabid]
Gregory Alan Isakov — Appaloosa Bones [s/r]
☞ Iuliad — Mă așteptam la alt sfârșit [s/r]
James Blake — Playing Robots Into Heaven [Republic/Polydor]
☞ James Holden — Imagine This Is A High Dimensional Space Of All Possibilities [Border Community]
Jay-Jay Johanson — Fetish [ART/29 Music]
Jonathan Bree — Pre-Code Hollywood [Lil’ Chief]
Kelela — Raven [Warp]
King Creosote — I DES [Domino]
Laurel Halo — Atlas [Awe]
Lubomyr Melnyk — The Sacred Thousand [Jersika]
The National — First Two Pages of Frankenstein [4AD]
The National — Laugh Track [4AD]
Philip Selway — Strange Dance [Bella Union]
Roger Eno — The Skies, they shift like chords… [Deutsche Grammophon]
Romy — Mid Air [Young]
Sigur Rós — Átta [Von Dur]
Sofia Kourtesis — Madres [Ninja Tune]
Yara Asmar — Synth Waltzes and Accordion Laments [Hive Mind]

Quite into Daniel Lanois’s Player, Piano (from 2022) and Enzo Favata The Crossing (from 2021) as well, both of which I learned about just this year.

On the radar

These ones I enjoyed but didn’t get to dig into as much as I’d hoped.

All Hands_Make Light — “Darling The Dawn” [Constellation]
Altın Gün — Aşk [Glitterbeat]
Alva Noto — HYbr:ID II [Noton]
Alva Noto — Kinder der Sonne [Noton]
Alva Noto — This Stolen Country of Mine [Noton]
Angel Olsen — Forever Means [Jagjaguwar]
ANOHNI — My Back Was a Bridge For You To Cross [Rough Trade]
Anoushka Shankar — Chapter I: Forever, for Now [Leiter]
Aphex Twin — Blackbox Life Recorder 21f / In a Room7 F760 [Warp]
bdrmm — I Don't Know [Rock Action]
boygenius — the record [Interscope]
Carlos Cipa — Ourselves, as we are [Warner Classics]
Chris Abrahams, Oren Ambarchi, Robbie Avenaim — Placelessness [Ideologic Organ]
Colleen — Le Jour Et La Nuit Du Réel [Thrill Jockey]
Daniel Avery — More Truth [PIAS]
David Toop & Lawrence English — The Shell that Speaks the Sea [Room40]
Donato Dozzy & Sabla — Crono [Gang of Ducks]
Eiko Ishibashi & Jim O’Rourke — Lifetime of a Flower [Week-End]
☞ Explosions in the Sky — End [Temporary Residence]
Föllakzoid — V [Sacred Bones]
Forest Swords — Bolted [Ninja Tunes]
Greta Van Fleet — Starcatcher [Republic]
Hania Rani — Ghosts [Gondwana]
Hilary Woods — Acts of Light [Sacred Bones]
James Ellis Ford — The Hum [Warp]
Jana Horn — The Window Is the Dream [No Quarter]
Jim O’Rourke — Hands that Bind OST [Drag City]
Julie Byrne — The Greater Wings [Ghostly]
Julie Byrne — Julie Byrne with Laugh Cry Laugh [Ghostly]
Kali Malone ft. Stephen O’Malley & Lucy Railton — Does Spring Hide Its Joy [Ideologic Organ]
Kevin Morby — More Photographs (A Continuum) [Dead Oceans]
Lawrence English & Lea Bertucci — Chthonic [American Dreams]
Lawrence English & Werner Dafeldecker — Tropic of Capricorn [Hallow Ground]
Loscil & Lawrence English — Colours of Air [Kranky]
Luke Schneider — It Is Solved By Walking [Third Man]
Natalia Beylis — Mermaids [Touch Sensitive]
Noriko Tujiko — Crépuscule I & II [Editions Mego]
Oneohtrix Point Never — Again [Warp]
Oren Ambarchi & Eric Thielemans — Double Consciousness [Matière Mémoire]
Ozmotic & Fennesz — Senzatempo [Touch]
Philip Jeck & Chris Watson — Oxmardyke [Touch]
PJ Harvey — I Inside the Old Year Dying [Partisan]
Rone, Orchestre National de Lyon & Dirk Brossé — L(oo)ping [InFiné]
Ryuichi Sakamoto — 12 [Milan/Commmons]
Róisín Murphy — Hit Parade [Ninja Tune]
Sarah Davachi — Long Gradus [Late Music]
Slowdive — everything is alive [Dead Oceans]
Sufjan Stevens — Javelin [Asthmatic Kitty]
Tim Hecker — No Highs [Kranky]
Timber Timbre — Lovage [Hot Dreams]
Vanessa Wagner — Les heures immobiles [InFiné]
Will Butler + Sister Squares — Will Butler + Sister Squares [Merge]
Yann Novak — The Voice of Theseus [Touch/Fairwood]
Young Fathers — Heavy Heavy [Ninja Tunes]

Other things

Reissues, expansions, archival material, remixes, live albums, et cetera:

Iceland Symphony Orchestra, Daniel Bjarnason — Jóhannsson: A Prayer To The Dynamo and Suites from “Sicario” & “The Theory of Everything” [Deutsche Grammophon]
Joanna Brouk — Sounds of the Sea (1981) [Numero]
Laraaji — Segue To Infinity [Numero]
Roger Eno — The Turning Year: Rarities [Deutsche Grammophon]
Sarah Davachi — Selected Works I + II [Late Music/Disciples]
Sparklehorse — Bird Machine [Anti]
William Basinski — The Clocktower at the Beach (1979) [Line]

Plus some individual tracks:

The Antlers — Need Nothing
Björk ft. Rosalía — Oral
Depeche Mode — Ghosts Again (from Memento Mori)
☞ Four Tet — Three Drums
Oneohtrix Point Never — A Barely Lit Path (from Again)
Roger Eno, Cecily Eno, Lotti Eno — Bells (With Voices) (from The Turning Year: Rarities)

Live shows I went to this year: Shida Shahabi and A Winged Victory for the Sullen at the Barbican in London; Jay-Jay Johanson, Sigur Rós, Jamie XX, and Mulatu Astatke in Cluj; Florence and the Machine in Bucharest; Brian Eno and the Baltic Sea Orchestra in Utrecht.

Ryuichi’s Last Playlist. We would like to share the playlist that Ryuichi had been privately compiling to be played at his own funeral to accompany his own passing. He truly was with music until the very end. — RIP Ryuichi Sakamoto.

Timeline of favorite records: 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025.

Other 2023 lists: Boomkat, Bleep, Rough Trade UK, Rough Trade US, The Quietus, The Wire. Simon Collison, Jon Hicks.

So you want to add a web feed

2023-10-07T00:00:00Z

You’ve decided you want a web feed for your website’s content.

Some popular CMSes have you covered with built-in feeds. For WordPress, an RSS feed is available by default at your-website.com/feed, so it’s just a matter of making the feed visible in your HTML templates and you’re good to go.

But if you have to implement one from scratch, this guide goes through the basics. To keep it short, it has opinions without much space offered to alternatives and nuance.

Use the Atom format

The two most popular web feed formats are RSS and Atom, both XML-based. The best format for new feeds is Atom. Here’s a minimal feed with one entry to illustrate the elements you need to use:

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
	<title>Dan Burzo: Posts</title>
	<link href="https://danburzo.ro/posts.xml" rel="self" />
	<link href="https://danburzo.ro/" />
	<updated>2023-10-07T00:00:00Z</updated>
	<id>https://danburzo.ro/</id>
	<author>
		<name>Dan Burzo</name>
	</author>
	<entry>
		<id>https://danburzo.ro/add-a-web-feed/</id>
		<title>So you want to add a web feed for your website</title>
		<link href="https://danburzo.ro/add-a-web-feed/" />
		<updated>2023-10-07T00:00:00Z</updated>
		<content type="html">
			<!-- entry content goes here -->
		</content>
	</entry>
</feed>

The feed has a set of fields at the top level, and another set of fields for each <entry>. The guidelines below apply to both.

Good IDs

IDs are used to identify the feed and the entries. Feed readers use the entry ID to remember when you’ve read or starred a post. Use the post’s URL as the ID for the corresponding entry, and the website’s URL as the feed ID, and then try to never change them.

Date format

There’s a dizzying array of standard date/time formats, as shown in this diagram that illustrates RFC 3339 vs. ISO 8601 vs. W3C formats. Atom narrows it down significantly: all dates in the feed must be in RFC 3339 date-time format with uppercase delimiters. That means we need all these stringed together:

The date in YYYY-MM-DD format, eg. 2023-10-07
The uppercase T separator
The time in HH:MM:SS format, eg. 21:30:00
Either the timezone offset, eg. +03:00, or uppercase Z for UTC time.

For example: October 7th, 2023 at 21:30, UTC time is expressed as 2023-10-07T21:30:00Z.

The one date element that’s required for an entry is <updated>. You can distinguish the initial publish date from the last update date by mixing in a <published> element. On the top-level feed, <updated> is the date of the latest change to any of the entries.

HTML content

Since XML and HTML share the syntax to some extent, adding raw HTML to the <content> element will trip up the XML parser. To prevent it, you can escape the XML-sensitive characters <, >, and & to their named entities <, >, and & respectively.

Or, skip the text processing and wrap the HTML content as-is in a character data (CDATA) section:

<content type="html"><![CDATA[ html content goes here ]]></content>

Careful: even ‘plain-text’ fields such as <title> can break XML parsing if an unaccounted-for ampersand or < ends up in it, so it’s a good idea to handle it similarly to <content>.

Absolute links

All links to resources must use absolute URLs, or the feed must contain attributes that help feed readers resolve any relative URLs they encounter.

Technically, the Atom specification allows the xml:base attribute on any feed element to define the base URL against which to resolve relative URLs within the scope of that element:

<content type="html" xml:base="https://danburzo.ro/add-a-web-feed/">
<![CDATA[ 
	html content goes here 
]]>
</content>

How well xml:base works in practice depends on the feed reader. For best compatibility, put absolute URLs everywhere, to the extent that your setup permits: the links to entries and the feed itself, and for all resources in the HTML content.

Replacing relative URLs with absolute counterparts in HTML content is not straightforward: it’s not just the hrefs and the srcs, but things like srcset that have their own little syntax going on. So it’s worth noting that feed readers are free to look at the entry’s <link>, along with the xml:base attribute, to resolve relative URLs. As long as everything higher level uses absolute URLs, you’re probably fine to ship relative URL inside the <content>.

Check that the feed is valid

You can paste your Atom feed content into the W3C Feed Validator to check that everything has been generated correctly, or get very good guidance on fixing any error it runs into.

After you’ve published your feed, add it to your feed reader to keep an eye. I use NetNewsWire on Mac and iOS because it aligns with my idea of good software, but also because it’s relatively free of heuristics and hand-holding, so it tends to surface the quirks of an artisanal feed pretty quickly.

Put the feed on your server

Depending on your setup, the feed may be generated on the fly on a dedicated URL as with WordPress’s /feed/, or stored as a physical file such as posts.xml.

The correct media type for Atom feeds is application/atom+xml, and you may have your server set the appropriate Content-Type response header. Doing so provokes both useful and somewhat annoying behaviors for visitors depending on their browser, so it’s not a wholehearted recommendation.

In the case of a physical XML file such as posts.xml, I find it works fine to serve it as a regular application/xml file. Feed readers will figure it out.

Link to the feed in HTML

Now that the feed exists, all that’s left is to link to it. You can add a <link rel=alternate> element in <head>, with the appropriate media type. This enables feed readers to extract the feed URL from the web page, making it easiers for visitors to subscribe.

<!doctype html>
<html>
<head>
  <title>Dan Burzo</title>
	<link rel='alternate' type='application/atom+xml' href='https://danburzo.ro/posts.xml'>
</head>
</html>

Although you can use more than one feed <link>, some readers will only pick the first they find and silently ignore the rest, so make sure the most important feed is first in line.

For better discoverability, even if the feed refers to the /blog section of your website, put the <link> on all pages of your website, most importantly your homepage, which is how most users will try to add your website to their feed readers.

Also include visible links to feeds in your site’s footer, labeled as such to make it findable with the browser’s search function:

<a href='https://danburzo.ro/posts.xml'>Feed (Atom)</a>

With these in place, man and machine alike can find your feeds.

Next steps

More things you can configure:

Enable CORS for your feed, so web-based feed readers can fetch it directly (h/t DB)

Slotted content in Eleventy

2023-02-28T00:00:00Z

Some types of template data are awkward to maintain in any of the many places from where Eleventy can read it. Markdown's front-matter data can hold simple pieces of information just fine, but becomes unwieldy for rich content.

If you've ever wanted to art-direct individual pages with custom styles defined inline, I'm sure you're not exactly thrilled with front-loading a wall of CSS-in-YAML:

---
title: I wrote this on my portable typewriter
custom_style: |
  <style type='text/css'>
    body { font-family: monospace; }
  </style>
---

The front-matter approach is workable, but has some drawbacks:

you have to abide by weird YAML whitespace rules
there's no syntax highlighting
it places implementation details before the actual content

One solution to these annoyances, of which I'll try to convince you in this article, is to embed pieces of data in the content part of the Markdown file, that can then be referenced by name from the HTML layout, just like any other template data.

Adding slotted content to Eleventy

Say you're making a recipe website, and you want to put the ingredients and the instructions in different places in the HTML layout, without cluttering each Markdown file with presentational markup.

Let's create a {% slot %} shortcode to define the recipe parts:

---
title: 'Best pesto of your life'
layout: layouts/recipe.njk
---

{% slot 'ingredients' %}

* fresh basil
* pine nuts
* olive oil
* pecorino
* garlic clove
* salt

{% endslot %}

{% slot 'instructions' %}

1. Wash the basil leaves
2. Grate the pecorino
3. ...

{% endslot %}

...that we can then place in the appropriate spots in the HTML layout:


<article>
	<h1>{{ title }}</h1>
	<div class='layout'>
		<div class='ingredients'>
			<h2>Ingredients</h2>
			{{ slots.ingredients | safe }}
		</div>
		<div class='instructions'>
			<h2>Instructions</h2> 
			{{ slots.instructions | safe }}
		</div>
	</div>
</article>

Step 1: Add `slots` data to each page

We're going to store all slots for all pages in the slots object, which acts as a map-of-maps keyed by the page's inputPath. Each page has access to its own slots via Eleventy's Computed Data feature:

/* .eleventy.js */
module.exports = function(config) {
	const slots = {};
	config.addGlobalData('eleventyComputed.slots', function() {
		return data => {
			const key = data.page.inputPath;
			slots[key] = slots[key] || {};
			return slots[key];
		}
	});
};

Step 2: Register the `slot` shortcode

To pick up slot values from the Markdown files, we register the slot paired shortcode.

/* .eleventy.js */
module.exports = function(config) {
	config.addPairedShortcode('slot', function (content, name) {
		if (!name) throw new Error('Missing name for {% slot %} block!');
		slots[this.page.inputPath][name] = content;
		return '';
	});
}

After storing the content in the appropriate slot for the page, the shortcode returns an empty string so that the content is not also rendered inline in the Markdown file.

The content of {% slot 'ingredients' %} can then be used as {{ slots.ingredients }} anywhere in the HTML layout.

The throw clause at the beginning guards against a common error. You may expect {% slot ingredients %} to define a slot named 'ingredients', but ingredients in the context of an Eleventy shortcode is an identifier, and what the shortcode gets as the name argument is the value bound to that identifier. The slot name needs to be quoted as {% slot 'ingredients' %}. Checking for an empty name doesn't make the shortcode error-proof, but it will cover this frequent typo.

Step 3: Use the Eleventy Render plugin

The implementation so far assigns pieces of content to their respective slots as plain text. Any Markdown style in slot content will be used literally in the HTML output. To render slots the same way as the rest of the content, we need to use Eleventy's Render plugin, which registers a helpful renderTemplate shortcode.

/* .eleventy.js */
const { EleventyRenderPlugin } = require('@11ty/eleventy');

module.exports = function(config) {
  config.addPlugin(EleventyRenderPlugin);
};

Change the HTML layout to render slot content as Nunjucks + Markdown and you're good to go:

<!-- Before: --> 
<div class='ingredients'>
	<h2>Ingredients</h2>
	{{ slots.ingredients }}
</div>

<!-- After: -->
<div class='ingredients'>
	<h2>Ingredients</h2>
	{% renderTemplate 'njk,md', slots %}
		{{ ingredients | safe }} 
	{% endrenderTemplate %}
</div>

Note that by default content inside the renderTemplate shortcode only has access to the page and eleventy objects, so slots needs to be passed in as additional data.

Conclusion

Nunjucks, like other templating languages of Jinja lineage, technically comes with template inheritance via the block tag. It would make a lot of sense to define slotted content with named blocks. However, Nunjuck's template inheritance only applies to templates that extend other templates, and a Markdown file rendered with Nunjucks does not extend its layout file.

In the absence of the built-in template inheritance, this is the most concise implementation for Markdown slotted content in Eleventy I could ~~come up with~~ lift wholesale from eleventy-plugin-bundle. If it can be further simplified, I'd love to know.

Sass in Eleventy, with versioning

2023-02-02T00:00:00Z

There are many approaches to adding Sass support in Eleventy, and several plugins to abstract away these approaches. The docs page alone features four separate Sass plugins. When it comes to asset versioning, how you integrate Sass and Eleventy makes all the difference to the development experience.

I've spent the day tweaking the setup for Eleventy 2.0 to work with content-hashed .scss files for a new project. Let me walk you through it.

Producing content hashes

Content hashes are useful as a cache-busting mechanism: whenever the content of the file changes, its corresponding content hash changes as well. For caching purposes, having CSS, JS, images, and other assets include a hash of their content as part of the URL is an excellent idea, and files like style.fc3ff98e.css are not an uncommon sight across the web.

Here's how to produce an 8-character hash for a given string in Node.js:

const { createHash } = require('node:crypto');

function getHash(content, length = 8) {
	return createHash('md5')
		.update(content)
		.digest('hex')
		.substr(0, length);
}

getHash("Hello world!")
// => '86fb269d'

getHash('Hello back!')
// => '7f4b5e8b'

Different string, different hash. Ship it!

Adding support for Sass with content hashing in Eleventy

The official docs include sample code for adding support for Sass to Eleventy, paraphrased below:

module.exports = function(config) {
	config.addTemplateFormats("scss");
	config.addExtension("scss", {
		outputFileExtension: "css",
		compile: content => {
			let { css } = sass.compileString(content);
			return data => css;
	});
};

This short snippet sets up a basic workflow to transform all .scss files from the input directory to .css, but there's a gotcha. Permalinks for the resulting .css files are generated before the compile() function has chance to run, so we can't extend it to produce permalinks based on file contents.

Instead, Sass processing needs to happen earlier in the build process, in the getData() method. Based on its inputPath, sass can read the file directly and populate the template's data object. The compile() and compileOptions.permalink() methods then simply pick up the bits they're interested in.

const sass = require('sass');
const path = require('node:path');

module.exports = function(config) {
	/*
		Watch for changes in .scss files.
	 */
	config.addTemplateFormats('scss');

	/*
		Define how to process .scss files.
	 */
	config.addExtension('scss', {
		/*
			We're feeding the `inputPath` to Sass directly, so we don't need Eleventy to read the content of `.scss` files.
		 */
		read: false,

		/*
			Produce the data for each `.scss` file, including its processed CSS content and its MD5 content hash.
		 */
		getData: async function (inputPath) {
			const data = {
				/*
					Exclude .scss files from `collections.all` so they don't show up in sitemaps, RSS feeds, etc.
				 */
				eleventyExcludeFromCollections: true
			};
			/*
				Don't process .scss files that start with an underscore as standalone.
			 */
			if (path.basename(inputPath).startsWith('_')) {
				return data;
			}
			const { css } = sass.compile(inputPath);
			data._content = css;
			data._hash = getHash(css);
			return data;
		},
		compileOptions: {
			/* 
				Disable caching of `.scss` files, for good measure.
			*/
			cache: false,
			permalink: function (permalink, inputPath) {
				/*
					Don't output .scss files that start with an underscore, as per Sass conventions…
				 */
				if (path.basename(inputPath).startsWith('_')) {
					return false;
				}

				/*
					…and for other .scss files include the MD5 content hash produced in the `.getData()` method in the output file path.
				 */
				return data => `${data.page.filePathStem}.${data._hash}.css`;
			}
		},
		/*
			Read the processed CSS content from the data object produced with `.getData()`.
		 */
		compile: () => data => data._content
	});
}

So we've placed the content hashes in the permalinks of generated .css files. To retrieve these hashed permalinks inside HTML templates, we prepare an input/output map using a transform, which helpfully runs through each input file. As a small convenience, we strip the input directory (src in the snippet below) from the beginning of input paths.

const outputMap = {};
config.addTransform('outputMap', function (content) {
	const filepath = path.relative('src', this.page.inputPath);
	outputMap[filepath] = this.page.url;
	return content;
});

Put outputMap in a filter to look up versioned URLs for your input files and you're good to go.

config.addFilter('hashed', function (filepath) {
	if (!outputMap[filepath]) {
		throw new Error(`hashed: ${filepath} not found in map.`);
	}
	return outputMap[filepath];
});

Here's how to use the hashed filter in a template to obtain the versioned URL for src/_assets/style.scss:

<!-- This… -->
<link 
	rel='stylesheet' 
	type='text/css' 
	href='{{ '_assets/style.scss' | hashed }}'
>

<!-- …turns to this -->
<link 
	rel='stylesheet' 
	type='text/css' 
	href='_assets/style.c8ad33ff.css'
>

Conclusion

This article has discussed one way of adding Sass support to Eleventy 2.0 that lets you include content hashes into the resulting CSS file paths. It's short enough to plop it straight into your .eleventy.js config:

Full listing: add support for Sass with content hashing in Eleventy

Here's the full .eleventy.js configuration file:

const sass = require('sass');
const path = require('node:path');
const { createHash } = require('node:crypto');

/*
	For the given `content` string, 
	generate an MD5 hash of `length` chars.
 */
function getHash(content, length = 8) {
	return createHash('md5')
		.update(content)
		.digest('hex')
		.substr(0, length);
}

module.exports = function(config) {

	/*
		Watch for changes in .scss files.
	 */
	config.addTemplateFormats('scss');

	/*
		Define how to process .scss files.
	 */
	config.addExtension('scss', {
		/*
			We're feeding the `inputPath` to Sass directly, so we don't need Eleventy to read the content of `.scss` files.
		 */
		read: false,

		/*
			Produce the data for each `.scss` file, including its processed CSS content and its MD5 content hash.
		 */
		getData: async function (inputPath) {
			/*
				Don't process .scss files that start with an underscore as standalone.
			 */
			if (path.basename(inputPath).startsWith('_')) {
				return false;
			}
			const { css } = sass.compile(inputPath);
			return {
				/*
					Exclude .scss files from `collections.all` so they don't show up in sitemaps, RSS feeds, etc.
				 */
				eleventyExcludeFromCollections: true,
				_content: css,
				_hash: getHash(css)
			};
		},
		compileOptions: {
			/* 
				Disable caching of `.scss` files, for good measure.
			*/
			cache: false,
			permalink: function (permalink, inputPath) {
				/*
					Don't output .scss files that start with an underscore, as per Sass conventions…
				 */
				if (path.basename(inputPath).startsWith('_')) {
					return false;
				}

				/*
					…and for other .scss files include the MD5 content hash produced in the `.getData()` method in the output file path.
				 */
				return data => `${data.page.filePathStem}.${data._hash}.css`;
			}
		},
		/*
			Read the processed CSS content from the data object produced with `.getData()`.
		 */
		compile: () => data => data._content
	});

	const outputMap = {};
	config.addTransform('outputMap', function (content) {
		const filepath = path.relative('src', this.page.inputPath);
		outputMap[filepath] = this.page.url;
		return content;
	});

	config.addFilter('hashed', function (filepath) {
		if (!outputMap[filepath]) {
			throw new Error(`hashed: ${filepath} not found in map.`);
		}
		return outputMap[filepath];
	});

	return {
		markdownTemplateEngine: 'njk',
		dataTemplateEngine: 'njk',
		htmlTemplateEngine: 'njk',
		dir: {
			input: 'src',
			output: 'dist'
		}
	};
};

If you prefer the plugin route, it looks like eleventy-sass and its companion eleventy-plugin-rev do a similar job.

Addenda

A few hours after first publishing this article, @11ty/eleventy-plugin-bundle was released to help you create minimal per-page or app-level bundles of CSS, JavaScript, or HTML to be included in your Eleventy project.

Update March 1, 2023: .scss partials (i.e. files starting with an underscore) should not be processed at all in getData(). They'll be processed when they're included in regular .scss files.

Update August 9, 2023: .scss partials should likewise not be included in collections, so they don’t show up in RSS, sitemaps, etc.

Line-height tricks made simpler with the ‘lh’ CSS unit

2023-01-13T00:00:00Z

With Safari Technology Preview having supported it for a while, and Chromium 109 enabling user-facing support in a first batch of browsers, it's time to see a few ways in which the lh CSS unit is a useful addition.

The lh unit is formally described as follows:

Equal to the computed value of the line-height property of the element on which it is used, converting normal to an absolute length by using only the metrics of the first available font.

When used in the value of the font-size property on the element they refer to, the local font-relative lengths resolve against the computed metrics of the parent element — or against the computed metrics corresponding to the initial values of the font and line-height properties, if the element has no parent. Likewise, when lh or rlh units are used in the value of the line-height property on the element they refer to, they resolve against the computed line-height and font metrics of the parent element — or the computed metrics corresponding to the initial values of the font and line-height properties, if the element has no parent.

Description of the lh unit in the 6.1.1. Font-relative Lengths section of CSS Values and Units Module Level 4 (Editor's Draft).

More concisely, 1lh is the computed line height of:

the parent when used in font-size or line-height declarations, or
of the element itself in any other declaration.

Uses for the `lh` unit

Note: The CSS examples below rely on support for the lh unit, which your current browser does not provide. To keep the snippets clearer, I have not included any style fallbacks, so the examples won't look great. Load this article in Safari TP, Chrome 109+, or Edge 109+ to see the effects in action.

Ruled paper effect

The lh unit makes it easy to produce CSS images that are in step with the lines of text. A straightforward example of that is drawing horizontal rules each 1lh, which we achieve here with repeating-linear-gradient().

.index-card {
	border: 1px solid;
	background-color: gold;
	background-image: repeating-linear-gradient(
		transparent 0 calc(1lh - 1px), 
		midnightblue calc(1lh - 1px) 1lh
	);
	/*
		Aligning the background image to the content-box
		lets us use any padding on the element.
	 */
	background-origin: content-box;
	padding: 1lh;
}

Emanuel urcă scara întunecoasă. Mirosea în aer a produse farmaceutice și a cauciuc ars. În fundul coridorului îngust, recunoscu ușa albă care îi fusese indicată. Intră fără să mai bată.

This was not impossible to do before. When line-height is a unitless multiplier of the font's size, we can produce a custom CSS property var(--lh) with the same 1lh:

--line-height: 1.5;
--lh: calc(1em * var(--line-height));
line-height: var(--line-height);

This basic technique can be used for a variety of effects, such as Adam Argyle's text of a different color on each line. It's also a good addition to the debugging toolbox. Throughout the article, I'll use the .index-card CSS class on examples to make the line boxes visible.

Note: In Safari TP, zooming in and out of the page affects the computed value of 1lh inside CSS gradients, causing the ruled paper to shift out of alignment with the text [WebKit#252075].

Nicely sized inline icons

The lh unit is useful for harmonizing sizes with the surrounding text and, in particular, latching onto the line box in a predictable way. This usage is described by Šime Vidas in 2020 (via CSS Tricks):

.with-icon:before {
	content: '';
	width: 1lh;
	height: 1lh;
	background: midnightblue;
	display: inline-block;
	vertical-align: bottom;
	margin-inline-end: 0.25em;
}

O ușă se deschise

Here, a pseudo-element of height: 1lh is anchored to either end of the line box using vertical-align: top or bottom to ensure perfect alignment.

Speaking of perfect, I should note that 1lh refers to the ideal line height of an element, but the actual line-height can get bumped by things like inline blocks or <sup> elements:

O ușă¹ se deschise

Baseline grid one-liner

Disclaimer / note to future self: A line-height: <length>; declaration already inherits just fine without any additional work. Having re-read it, this section needs to be rethought to make a better point, best to ignore it before I have the chance to do that.

I saved the best for last.

Beyond a simple abstraction over calc(1em * var(--line-height)), elements can be made to inherit their parent's line-height. Maintaining vertical rhythm for the entire document is reduced to an elegant declaration:

html {
	line-height: 1.6;
}

html * {
	line-height: 1lh;
}

How cool is that? I mean sure, there's more to vertical rhythm than an uniform line height. It involves block sizes, along with properties that affect the box model (border, padding, margin). These are currently brewing in the CSS Rhythmic Sizing specification, including a line-height-step property that's already available in Chromium under a run-time feature flag.

The implications of going document-wide for this need to be explored before we can declare we have another * { box-sizing: border-box }-style gold nugget on our hands. In the meantime, it works pretty well applied locally:

.baseline-grid {
	line-height: 1.3;
}

.baseline-grid * {
	line-height: 1lh;
	margin-block: 1lh;
	text-indent: 1lh;
}

.baseline-grid .smaller {
	font-size: 0.8em;
}

Încăperea în care se găsi părea mai veche încă și mai mucegăită decât coridorul. Lumina venea printr’un singur geam și răspândea o claritate albastră și nesigură peste desordinea din salonaș, unde revistele zăceau răvășite pretutindeni, acoperind masa de marmură și scaunele solemne, învelite în halate albe ca în niște haine comode de voiaj, înainte de mutare.

Emanuel mai mult căzu decât se așeză într’un fotoliu. Observă cu surprindere umbre parcurgând odaia și descoperi subit că geamul din fund era în realitate un aquarium în care pluteau lent pești negri, bulbucați și grași. Câteva secunde rămase cu ochii mari deschiși urmărindu-le alunecarea leneșă, uitând aproape pentru ce venise.

Într’adevăr pentru ce venise aici? Aha! Își aduse aminte și tuși încetișor pentru a-și anunța prezența, dar nimeni nu răspunse.

In this setup, 1lh becomes a fixed measure, like 1rem, that can be used to keep in sync margins, indents, and others.

Note: In Safari TP, imposing a minimum font size via the browser setting affects line-height: 1lh [WebKit#252108].

Conclusion

These have been the three examples I could come up with, or find, in an evening. I hope these can serve as a starting point for finding new, more interesting uses for the lh unit.

The text fragments are from M. Blecher's Inimi cicatrizate (Scarred hearts), available in the public domain.

Why do mobile browsers share canonical URLs?

2023-01-10T00:00:00Z

It did it again the other day.

I had tucked some research leads from Google Books — a website that lets you perform searches in the content of digitized books, many very old — into Safari's Reading List on my phone, for later reference. A while later, when it came to following the breadcrumbs I had left for myself back to the insight they were meant to help germinate, lo and behold — all links to Google Books were missing my search queries. What had I found in these now unfamiliar books?

Since it was not the first occurrence of the sort, I've had a low-key suspicion for a while that when you share or bookmark a URL in iOS Safari, it takes into account the page's canonical URL whenever it finds one. I've been content to just shrug off the occasional mishap and move on, but this time I took the opportunity to dig into the subject.

Some background on canonical URLs

The canonical URL is meant to convey, as per the HTML spec, the preferred URL for the current document. The introductory paragraphs from RFC6596: The Canonical Link Relation tell us most of what we need to know about its intent:

The canonical link relation specifies the preferred IRI from resources with duplicative content. Common implementations of the canonical link relation are to specify the preferred version of an IRI from duplicate pages created with the addition of IRI parameters (e.g., session IDs) or to specify the single-page version as preferred over the same content separated on multiple component pages.

In regard to the link relation type, "canonical" can be described informally as the author's preferred version of a resource. More formally, the canonical link relation specifies the preferred IRI from a set of resources that return the context IRI's content in duplicated form. Once specified, applications such as search engines can focus processing on the canonical, and references to the context (referring) IRI can be updated to reference the target (canonical) IRI.

A canonical URL can be defined either through a Link HTTP header or, more commonly, via a <link> HTML element:

<!doctype html>
<html lang='en'>
<head>
	<title>Welcome to my website</title>
	<link rel='canonical' href='https://danburzo.ro/'>
</head>
</html>

How did browsers end up using canonical URLs?

As described in the introduction to RFC6596, one major use case for canonical URLs is to help search engines make sense of several URLs that point to the same underlying content. This is also the angle Google uses to present the benefits of canonical URLs.

Sometime around 2017, this mechanism meant for machines was co-opted by browsers to address a very different problem: nudging users away from Google's AMP Viewer, and towards the original web pages it was caching. Safari 11 for iOS was soon followed by Chrome 64 for Android in favoring a page's canonical URL for certain interactions, such as sharing and bookmarking.

This change worked pretty well for that singular purpose: most article page proxied by the AMP Viewer could be unambiguously traced back to their original URL.

However, this was released as a general mechanism that affects any page that uses <link rel=canonical>. That's a lot of pages, more than half of the pages analyzed by HTTP Archive for this year's Web Almanac, including crowd favorite Wikipedia.org.

In the general case, the results are more of a mixed bag.

The pros and cons of sharing canonical URLs

Some effects are decidedly positive: various pieces of user tracking gunk are stripped from URLs before they're passed to friends, as these are generally not featured in the page's canonical URL. By design or chance, among the things removed from URLs is the odd personally-identifying piece of information, so you could build the case that the feature helps protect the user's privacy.

But things that are beneficial to a search engine don't always match user needs. In fact, they can even clash.

Take filters on an e-commerce website as an example. For search engines, it's useful to know that various filtering criteria and sorting options, most often reflected as query parameters in the URL, reflect the same underlying content. It makes sense, from an SEO perspective, to lump all combinations together under a single canonical URL.

For a user, on the other hand, the specific filtering criteria and sorting options are kind of the whole point, aren't they? When I browse my favorite bookstore's website for foreign books, in English, available in stock, sorted by most recent first and I commit that URL to my bookmarks for quick access, my intent is for the URL to be preserved at that exact level of specificity.

Even if you do manage to devise a pattern that fulfills both user needs and SEO goals, you're not yet out of the woods. When using canonical URLs in any form on your website, you're implicitly signing up for:

remaining vigilant about updating the <link rel=canonical> element in response to all operations that may alter the URL, such as with the History API via pushState() or replaceState();
depending on the browser implementation, waving goodbye to using fragment identifiers. Since it's exclusive to the client, the URL fragment can't be reflected by the server in the canonical URL. It will, therefore, be stripped when sharing or bookmarking the page — unless the browser is proactive in keeping it, or the fragment is kept in sync on the canonical link with client-side JavaScript.

Speaking of browser implementations, let's see how they stack up at the moment of writing.

Current browser behavior

Note: I'm using this demo page to test browser behavior, where the original URL is, depending on the things you click on, of the form https://danburzo.ro/demos/canonical-link.html?hello=world#a. Its canonical URL is defined as https://danburzo.ro/demos/canonical-link-canonical.html via the <link rel=canonical> element. Notice the different HTML file name and lack of query string and fragment.

Desktop browsers seem to be doing a good job of using the original URL when sharing and bookmarking a web page. Across the major mobile platforms and browsers, the situation is more diverse.

On Android:

Samsung Internet 19 and Firefox Android 108 share and bookmark the original, intact URL.
Chrome Android 108 bookmarks the original URL. When sharing the web page, it uses the canonical URL, but picks up the fragment identifier from the original URL. This is an enhancement introduced around 2021 [Chromium#1038187] that makes sharing canonical URLs a little less problematic.
Edge Android 108: no data, as I couldn't find an .apk to load on the device (test data appreciated!)

On iOS:

Firefox iOS 108 shares and bookmarks the original URL.
Safari iOS 16.2 uses the canonical URL for both sharing and bookmarking but loses the fragment identifier from the original URL [WebKit#250317], including the text fragment links for which Safari 16.1 has recently added support.
Chrome iOS 108, in an effort to match Safari [Chromium#1323782], works a bit worse than its Android counterpart: it shares the canonical URL, but without copying over the fragment identifier from the original URL. When bookmarking, the original URL is used. (Add to Reading List is weird: it's made to match Safari's bookmarking behavior since it's accessed from the same sharing panel, even though the page gets added to Chrome's own Reading List.)
Edge iOS 108, like Safari and Chrome, shares the canonical URL without copying over the fragment identifier from the original URL. When bookmarking, the original URL is used.

A summary of mobile browser behavior in regards to sharing and bookmarking URLs in the presence of a canonical link, January 2023.
Browser		Shared URL	Bookmarked URL
Android	Firefox	Original	Original
	Samsung Internet	Original	Original
	Chrome	Canonical, fragment kept	Original
	Edge	Missing data	Missing data
iOS	Firefox	Original	Original
	Safari	Canonical, fragment lost	Canonical, fragment lost
	Chrome	Canonical, fragment lost	Depends, see notes
	Edge	Canonical, fragment lost	Original

How do browser vendors feel about the status quo?

Chrome seems to get a steady stream of issue reports about the "wrong URL" being shared or copied to the clipboard — see, for example, Chromium#799955, Chromium#924309 — to which the resolution is invariably works as intended along with a note that the team is reconsidering its approach to using canonical URLs in light of its tradeoffs. The conversation is framed more around erroneous usage of <link rel=canonical> by authors — see conversations in Chromium#988497, Chromium#1202789, Chromium#1306663 — than on any fundamental flaw or limitation with the approach itself, but it's a start.

Over at Mozilla arguments for, or against, using the canonical URL for sharing [Mozilla#1794879] and bookmarking [Mozilla#502418] have not yet truly taken off.

Possible solutions

I don't have much in the way of alternative solutions, but I tend to err on the side of user agency.

For each browser on each mobile platform, the sharing UI is flexible enough to accommodate a persistent user preference. Pictured below, Safari 16.2's sharing panel already has an Options section that could very well let you tweak how a link gets shared or bookmarked.

The sharing panel in Safari 16.2.

Finally, an invitation: I've tried to find and link all browser issues relevant to the topic of user-facing canonical URLs. If you have an opinion or a piece of anecdata, either in support or against their usage, please share it with browser vendors.

Thanks to Šime for the useful feedback.

Miscellaneous bits and bobs

In the process of testing browser behaviors, I also logged issues for a couple of things I noticed in macOS Safari: that a page whose defined canonical URL differs from its actual URL will never be marked as visited [WebKit#250319], and that clicking an in-page link to a text fragment does not update the URL fragment [WebKit#250320].

Get useful input values with formDataMap()

2023-01-08T00:00:00Z

Chris Ferdinandi's recent article for 12 Days of Web called FormData API reminded me about a helper function I wrote to quickly wire up plain HTML form controls in interactive demos of the move slider make thing happen type, without needing to reach for dat.gui or a similar library.

When your set of controls is organized as a plain HTML form, the FormData DOM interface is a useful way to read the values. It also interacts nicely with other APIs, such as fetch() and URLSearchParams.

For our specific use case, it does present a couple of inconveniences:

you read its entries via a dedicated API, with two separate methods .get() and .getAll() depending on whether you're expecting one value or many;
everything except Blobs is cast to a string.

Let's take these minuscule concerns as an opportunity to implement a slightly-enhanced version of FormData of our own, that produces a plain old JavaScript object, and keeps the value types closer to their underlying form controls.

Let's reimplement `FormData` for some reason

The HTML specification helpfully lists the steps for constructing the entry list for a given form element. We want our implementation to be fairly robust against the markup you'd write today, but not necessarily cover the historical aspects; as such, the implementation is going to gloss over <input type='image'> with its very specific behavior.

Finding elements that should be submitted

Form elements are grouped in overlapping categories:

Submittable elements are <button>, <input>, <select>, <textarea>, and any form-associated custom elements.
Listed elements include <fieldset>, <object>, and <output>, in addition to submittable elements. They can have an explicit form attribute that associates them with a form somewhere else in the DOM tree.

The HTMLFormElement.elements collection does the legwork of gathering the listed elements associated with the form, taking into account any explicit form attribute on the elements. The only work that leaves for our implementation is to filter out any element types that are listed but not submittable:

function formDataMap(form, submitter) {
	const excludedTags = ['FIELDSET', 'OBJECT', 'OUTPUT'];
	const submittable = Array.from(form.elements)
		.filter(el => !excludedTags.includes(el.tagName));
}

Out of all submittable elements, only form controls that comply with a set of rules are actually submitted. Any such element must:

have a non-empty name attribute (except for custom elements associated with the form, which in some cases can go without);
not be disabled, either via its disabled attribute or through its position in the DOM tree;
not be nested inside a <datalist> element;
be checked, in the case of radio and checkbox inputs;
not be a button, except for the button that submitted the form, if applicable.

These rules are merged into the shouldSubmit(el) function below:

function formDataMap(form, submitter) {

	const excludedTags = ['FIELDSET', 'OBJECT', 'OUTPUT']
	const excludedTypes = ['button', 'reset', 'image'];

	function shouldSubmit(el) {
		if (!el.name) return false;
		if (excludedTags.includes(el.tagName)) return false;
		if (excludedTypes.includes(el.type)) return false;
		if (el.type === 'submit' && el !== submitter) return false;
		if (el.type === 'radio' && !el.checked) return false;
		if (el.type === 'checkbox' && !el.checked) return false;
		if (el.disabled || el.matches(':disabled')) return false;
		if (el.closest('datalist')) return false;
		return true;
	}

	const toSubmit = Array.from(form.elements).filter(shouldSubmit);
}

Adding values based on the type of form control

With the rules out of the way, on to the fun part of getting nice values based on the type of each element. Here's the plan:

String: most form controls work okay with a string value. For inputs of type checkbox, color, email, hidden, password, radio, search, tel, or text, as well as for <textarea> elements, the plain element.value suffices. Similarly, <select> elements produce strings.
Number for inputs of types number and range.
Date for inputs of type date, datetime-local; date-adjacent types such as month, time, and week are left as strings currently, but they can probably afford something more interesting.
File for inputs of type file.
URL for inputs of type url.

Putting everything all together, here's the final function:

function formDataMap(form, submitter) {
	const excludedTags = ['FIELDSET', 'OBJECT', 'OUTPUT']
	const excludedTypes = ['button', 'reset', 'image'];

	function shouldSubmit(el) {
		if (!el.name) return false;
		if (excludedTags.includes(el.tagName)) return false;
		if (excludedTypes.includes(el.type)) return false;
		if (el.type === 'submit' && el !== submitter) return false;
		if (el.type === 'radio' && !el.checked) return false;
		if (el.type === 'checkbox' && !el.checked) return false;
		if (el.disabled || el.matches(':disabled')) return false;
		if (el.closest('datalist')) return false;
		return true;
	}
	
	const result = {};

	function append(key, val) {
		result[key] = 
			Object.hasOwn(result, key) ? 
				[].concat(result[key], val) 
				: val;
	};

	Array.from(form.elements).forEach(el => {
		if (!shouldSubmit(el)) return;
		const { name, type } = el;
		if (type === 'number' || type === 'range') {
			append(name, +el.value);
		} else if (type === 'date' || type === 'datetime-local') {
			append(name, el.valueAsDate());
		} else if (type === 'file') {
			append(name, el.files);
		} else if (type === 'url') {
			append(name, new URL(el.value));
		} else if (type === 'select-one' || type === 'select-multiple') {
			Array.from(el.selectedOptions).forEach(
				option => append(name, option.value)
			);
		} else {
			append(name, el.value);
		}
	});

	return result;
};

Let's use `formDataMap()`

One great web platform feature with which to pair formDataMap() is event propagation, which enables us to capture events on the ancestor form:

<form id='song-config'>
	<label>
		Song title:
		<input type='text' name='title' />
	</label>
	<label>
		Cowbell level: 
		<input name='cowbell' type='range' min='0' max='11'>
	</label>
	<button type='submit'>Apply configuration</button>
</form>

<script type='module'>
	const form = document.getElementById("song-config");
	form.addEventListener('input', e => {
		const data = formDataMap(form);
		/* do great things with `data` */
	});
</script>

Depending on the level of responsiveness the interactive demo needs, you can choose between input, change and submit events. The latter also gives you access to the form's submitter element, which can be factored into the returned data, a feature FormData does not currently support [whatwg/xhr#262]:

form.addEventListener('submit', e => {
	e.preventDefault();
	const data = formDataMap(form, e.submitter);
	/* do great things with `data` */
});

Update March 11, 2023: The aforementioned issue has been fixed, with submitter added as a second, optional argument to the FormData() constructor. Chrome 112 is the first browser shipping support for it.

Conclusion

In all fairness, [leans in and starts whispering:] instead of reimplementing everything from scratch, you could get most of the same functionality with the form's vanilla FormData object serialized to a plain JavaScript object, followed by casting the values to numbers, dates, etc. as needed before using them for computations.

However, for that extra bit of convenience, formDataMap() is listed in full on its separate page.

Appendix: Handling custom HTML elements

ElementInternals is a new API that lets custom HTML elements participate in forms. The article More capable form controls by Arthur Evans goes into more detail, but in a nutshell, your custom element needs to:

make itself form-associated by declaring the static formAssociated property;
access form functionality with the ElementInternals.attachInternals() method.

class MyControl extends HTMLElement {
	static formAssociated = true;
	constructor() {
		super();
		this.internals = this.attachInternals();

		// Set the element's submission value
		this.internals.setFormValue('some-value');
	}
}

customElements.define('my-control', MyControl);

With the setFormValue() method, custom elements can specify their submission value which the FormData API can access. The submission value can be a string, a Blob, or a FormData object. The latter is used when the custom element wants to relay multiple values, and it's the only case when a custom element doesn't need a name attribute for it to be included in the form's submission data.

Unfortunately for us, the value set with the setFormValue() method is not accessible through any standard interface, so it's up to each custom element to decide how (and if) to expose an equivalent.

To remain generic, formDataMap() can only fall back to the standard append(name, el.value) approach.

My favorite records from 2022

2022-12-05T00:00:00Z

December, the month of dwindling daylight and obligatory retrospection, is upon us once again. Here are my favorite records of the year 2022, ordered alphabetically. My top ten are marked with a ★ (star).

The manicule ☞ marks retroactive additions of favorite albums I’ve discovered after having made the initial list.

Live shows I've attended this year: Tindersticks in Lisbon; Dead Can Dance and Arctic Monkeys in Bucharest; Altın Gün and WhoMadeWho in Cluj.

Timeline of favorite records: 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025.

Other 2022 lists: Bleep, Rough Trade UK, The Quietus.

Relational data in Eleventy

2022-11-26T00:00:00Z

Many-to-many relationships are a fixture of structured content.

A basic example is a collection of Posts, each written by one or more Authors. So how do you shape the content so that it's easy to generate pages for Posts complete with nice bylines, and for individual Authors including a list of their posts?

The setup

The code snippets throughout this article use Eleventy 1.0.2, the latest version at the time of writing. They assume the input directory is a folder named content/, and use the Nunjucks templating language throughout. The corresponding .eleventy.js configuration is below:

/* File: .eleventy.js */

module.exports = config => {
	return {
		markdownTemplateEngine: 'njk',
		htmlTemplateEngine: 'njk',
		dir: {
			input: 'content'
		}
	};
};

The content/ folder holds all Posts and Authors in individual .md files. We'd like the frontmatter of one such file to reference information stored in a different file, and have that information readily available when rendering the page.

Posts reference each Author by their file path relative to the input directory. This path serves as an unique key for a piece of content. Here's how content/posts/hello.md might look:

---
title: Hello
authors:
  - authors/dan.md
  - authors/catalin.md
layout: layouts/post.njk
---

This is our first collective post!

Author files then hold the actual information in the frontmatter — things such as the full name, or the path to an avatar image — as well as the author bio in the Markdown content section. Here's content/authors/dan.md:

---
title: Dan Burzo
avatar: img/authors/dan-burzo.jpg
layout: layouts/author.html
---

This is Dan's short bio.

We want to accomplish two things:

expand the authors array in the Post's frontmatter into the actual pages they reference, so we can access all their properties in the template.
on the Author page, aggreggate the author's posts under the author_posts data field.

Augment the frontmatter with Computed Data

Eleventy comes with a cool feature called Computed Data that lets us add template data, at any level of the data cascade. More importantly, it lets us overwrite existing frontmatter data with richer values. We only need to define eleventyComputed once for each type of content, using directory data files.

For Posts, the content of the content/posts/posts.11tydata.js file is shown below. By defining the tags field, we add all entries in the folder to the posts collection. We do the same in content/authors/authors.11tydata.js to gather all Authors in the corresponding collection.

In Eleventy Collections, the unique identifier for a piece of content is its inputPath, which is the items's file path relative to the project's root, starting with the path for the input directory. In our case, all inputPaths start with ./content/.

With eleventyComputed, we replace the Post's authors field with the corresponding items from the authors collection, matching their inputPath. Remember that we referenced post authors by paths that were relative to the input directory. We have to concatenate that back into our paths before we can match against inputPath values.

/* content/posts/posts.11tydata.js */

module.exports = {
	layout: 'layouts/post.njk',
	tags: 'posts',
	eleventyComputed: {
		authors: data => {
			const postAuthors = data.authors || [];
			const collection = data.collections.authors;
			return postAuthors.map(authorPath => 
				collection.find(item => 
					item.inputPath === `./content/${authorPath}`
				)
			);
		}
	}
};

The inverse, showing all Posts by a specific Author, is similarly done with eleventyComputed. This time, we look in the posts collection for items whose authors data field includes the current inputPath.

/* content/authors/authors.11tydata.js */

module.exports = {
	layout: 'layouts/author.html',
	tags: 'authors',
	eleventyComputed: {
		author_posts: data => {
			const inputPath = data.page.inputPath;
			return data.collections.posts.filter(item => {
				const postAuthors = item.data.authors || [];
				return postAuthors.some(
					authorPath => `./content/${authorPath}` === inputPath
				);
			});
		}
	}
};

This setup makes it straightforward to use the enriched template data. In the layout for Posts...

<!-- content/_includes/layouts/post.njk -->

<hgroup>
	<h1>{{ title }}</h1>
	<p> By
	{% for author in authors %}
		<a href='{{ author.url }}'>{{ author.data.title }}</a>
		{%- if not loop.last -%}, {%- endif -%}
	{% endfor %}
	</p>
</hgroup>

{{ content | safe }}

...and for Authors:

<!-- content/_includes/layouts/author.html -->

<h1>{{ title }}</h1>

{{ content | safe }}

<h2>{{ title }}'s posts</figure>
<ul>
	{% for post in author_posts %}
	<li><a href='{{ post.url }}'>{{ post.data.title }}</a></li>
	{% endfor %}
</ul>

The two basic patterns — find by ID and filter by attribute — can be replicated for each relationship between data types you care to represent.

But before we pepper that pesky "./content/" string around a dozen directory data files, let's factor it out, while improving performance in the process.

To make collection items easier to find by ID, let's put all the content in one big dictionary, indexed by the keys used across the .md files to reference each other: the file path relative to the input directory. In other words, the inputPath with the input directory trimmed. We do that by defining a custom collection called _indexed in the project's .eleventy.js config:

/* .eleventy.js */

const path = require('path');

module.exports = config => {

	const INPUT_DIR = 'content';

	/*
		Index all content relative to the input directory
		in an Eleventy collection called `collections._indexed`
	 */
	config.addCollection('_indexed', data => {
		const index = {};
		data.getAll().forEach(item => {
			const key = path.relative(INPUT_DIR, item.inputPath);
			index[key] = item;
		});
		return index;
	});

	return {
		markdownTemplateEngine: 'njk',
		htmlTemplateEngine: 'njk',
		dir: {
			input: INPUT_DIR
		}
	};
};

This custom collection simplifies our computed data. To fetch Post authors, we can look them up in the index directly, which is much faster than iterating through the collection, and involves none of that string concatenation.

/* content/posts/posts.11tydata.js */

module.exports = {
	layout: 'layouts/post.njk',
	tags: 'posts',
	eleventyComputed: {
		authors: data => {
			const postAuthors = data.authors || [];
			const index = data.collections._indexed;
			return postAuthors.map(authorPath => index[authorPath]);
		}
	}
};

In the case of Author posts, we replace string concatenation with reading the paths from the index, making the code if not faster then at least more resilient.

/* content/authors/authors.11tydata.js */

module.exports = {
	layout: 'layouts/author.html',
	tags: 'authors',
	eleventyComputed: {
		author_posts: data => {
			const inputPath = data.page.inputPath;
			const index = data.collections._indexed;
			return data.collections.posts.filter(item => {
				const postAuthors = item.data.authors || [];
				return postAuthors
					.map(authorPath => index[authorPath].inputPath)
					.includes(inputPath)
			});
		}
	}
};

These could be further refactored into reusable functions, to make declaring many relationships more palatable, but this is the basic idea.

This website uses a variable font

2022-08-22T00:00:00Z

Around the end of 2021, this little corner of the web started using a variable font. Newsreader is a beautiful design from Production Type commissioned by Google Fonts, whose sources are available on GitHub under the Open Font license (OFL).

I'd been reading about variable fonts for a while, but had probably never actually typed up the CSS with my fingers for a project up to that point. Here are a few things I learned about self-hosting variable fonts in the process of freshening up the typography on here.

A first good thing to do is add all the necessary properties to the `@font-face` declaration

Newsreader comes with two separate font files, one for roman and one for italics. Each file has two variation axes: the weight (wght) and the optical size (opsz).

My initial @font-face declaration for the roman style was pretty straightforward, and replacing the old typeface worked well out of the box.

@font-face {
	font-family: Newsreader;
	font-style: normal;
	src: url('/fonts/Newsreader.woff2') format('woff2-variations');
}

body {
	font-family: Newsreader;
}

It became apparent rather soon, however, that this setup only works in Firefox. Things that were supposed to look bold — headings, <strong>, and the like — didn't look as good in Safari and Chrome, as seen in this demo. Both had trouble, in different ways, rendering font-weight: 700.

Each browser renders font-weight: 700 differently.

Safari produces what seems to be twice-bolded text by obtaining the appropriate bold weight from the variable font but then synthesizing a bolded version of that. In fact, disabling the browser's font synthesis with font-synthesis: none fixes the issue. As for Chrome, whatever it's doing, it's not improved by this declaration.

What gives? wght was supposed to be a registered variation axis that can be controlled via font-weight but, as seen in the demo, only font-variant-settings: "wght" 700" works consistently across browsers for bold text.

It was only obvious in retrospect that a webfont with a weight variation axis absolutely needs its weight range spelled out in the @font-face declaration, for the axis to be correctly mapped to the font-weight property. You do that with the @font-face/font-weight property:

@font-face {
	font-family: Newsreader;
	font-style: normal;
	font-weight: 200 800;
	src: url('/fonts/Newsreader.woff2') format('woff2-variations');
}

Similar declarations are needed for other registered axes:

the slnt axis which controls the angle of the oblique style needs a range defined with @font-face/font-style
the wdth axis which controls the font width needs a range defined with @font-face/font-stretch

Adding the correct @font-face properties enables declarations such as font-style: oblique 30deg or font-width: 125% to work as expected.

Variable fonts can also technically include the registered ital axis to bundle both roman and italic styles in a single file. Using such a font in CSS is a bit more complicated, so as a consequence pretty much everyone bundles romans and italics in separate files.

A note on `format()` in the `src` descriptor

By the time I got to reading up on variable fonts, the syntax for @font-face/src in the spec did no longer match the recommendations I'd found elsewhere for hinting to the browser that the url() points to a variable font.

Where were format('woff2-variations') and format('woff2 supports variations') coming from? But, more importantly, how to usefully hint variable fonts today? I made a browser test to check support for the various syntaxes and came to these conclusions:

format('*-variations') was the proposed syntax around the time when browsers adopted variable fonts, and the only syntax supported by browsers at the time of writing;
format(woff2) tech(variations) is the latest syntax. It separates the font format from font technology descriptor, as explained by Chris Lilley and Dominik Röttsches. This syntax is unsupported in current browsers and, if specified, must be done in a second @font-face/src declaration.

With these findings in mind (which you can now find in the compatibility table on MDN), variable fonts using the WOFF2 format only really need the format('woff2-variations') hint to ensure only browsers that have support for variations download the font file. This syntax works today and will most likely work indefinitely.

It's also probably a good idea to optimize variable web fonts (as long as you're allowed to)

Between the two variation axes (weight and optical size), Newsreader packs the information from nine separate source fonts. That adds up to a total of 455kb for the two WOFF2 files it ships. This is the overhead you have to pay for being able to produce as many fonts as you like, everywhere across the design-variation space.

Newsreader is based on nine master fonts, here distributed horizontally along the Weight axis (wght) and vertically along the Optical size (opsz) axis.

This overhead is not always justified for web pages, so a common thing to do is split the font into many pieces across an aspect of the font. fontTools is a collection of libraries and command-line tools for all sorts of font manipulation written in Python.

Richard Rutter has a guide on installing fonttools on macOS and using it to subset variable fonts. One understanding of subsetting is to cherry-pick a set of Unicode ranges that cover all the glyphs your content needs and call it a day. A more resilient approach is to effectively split the font in a series of scripts („alphabets”). As long as you know the Unicode bounds of these scripts — and Paul Hebert reminds us that, in a pinch, you can grab some ranges from Google Fonts — this lets you serve the entire glyph set the font offers, and let the browser fetch whatever it needs to render the content of the web page.

Narrowing the variation space

In addition to glyph sets, there's another direction along which to subset a variable font. fonttools comes with the varLib.instancer module that allows you to create full instances (i.e. static fonts) from variable fonts, as well as 'partial' variable fonts that only contain a subset of the original variation space.

There is such a thing as variable lite. If, for example, you can make do with a single optical size, or you've decided wght: 376 is the perfect weight for body text, and you only need another bold weight to go with it, it might be worth it to either:

produce a handful of static instances of the variable font, or
restrict the design-variation space to just the region you need.

The command below pins the optical size at 12 while reducing the weight range to [300–700] for the Newsreader roman font:

fonttools varLib.instancer ./Newsreader.woff2 wght=300:700 opsz=12 -o ./Newsreader-partial.woff2

This cuts the file size in half, from 215kb to 98kb. I've intentionally picked a "bad" example, because the reduction is foremost attributable to removing the optical size variation axis. If we omit the wght=300:700 option in our command we end up with mostly the same reduction (215kb to 102kb):

fonttools varLib.instancer ./Newsreader.woff2 opsz=12 -o ./Newsreader-partial.woff2

Recall that Newsreader uses font data from wght=200,400,800, corresponding to the minimum, default, and maximum weight. To render the wght=300:700 range we still need data for the new minimum and maximum weight. To truly see a reduction in size, our weight range would have to be defined in such a way that at least one set of font data can be dropped from the variable font, for example wght=400:800:

fonttools varLib.instancer ./Newsreader.woff2 wght=400:800 opsz=12 -o ./Newsreader-partial.woff2

Legal aspects of subsetting

Fonts are distributed under a variety of licenses that govern their use. The following apply to fonts distributed under the SIL Open Font License, as is the case for Newsreader. Obviously, I'm not a lawyer so this is just my layperson understanding of the matter.

Converting a .ttf / .otf file to a .woff / .woff2 just to optimize its delivery across the network (WOFF is a compressed format), without any other alterations, preserves its Functional Equivalence, and is permitted under the OFL license;
Subsetting a font alters its functionality, so it produces a derivative work, which is subject to some rules.

When producing a derivative work you need to change the font's name to something completely different when and if the OFL license mentions a Reserved Font Name (RFN) as part of its copyright line. Newsreader has the following copyright line:

Copyright 2020 The Newsreader Project Authors (http://github.com/productiontype/Newsreader)

A sample copyright line from the OFL license that does not reserve the font name.

If the authors wanted Newsreader to be an RFN they would have mentioned that in the copyright line, and I would then have been compelled by the license to rename my subsets some cringeworthy pun like, I dunno, Oldswriter.

Copyright 2020 The Newsreader Project Authors (http://github.com/productiontype/Newsreader), with Reserved Font Name Newsreader

A sample copyright line from the OFL license that reserves the font name.

Anyways, just something to be aware of. And if I'm getting this wrong, I would appreciate a nudge!

Addenda: readings, tools, and resources

I can't help myself from turning every article into a little compendium, so here are some tangentials I've found useful.

OpenType Font Variations is part of the OpenType specification. John Hudson announced this addition to OpenType 1.8 with Introducing OpenType Variable Fonts, highly recommended reading.

A few guides to getting started:

The Variable fonts guide on MDN
A Variable Fonts Primer. Still from Jason Pamental, Variable Fonts: What Authors Need to Know and An Introduction to Variable Fonts for 24 Ways
Introduction to variable fonts on the web on web.dev.
The newly-inaugurated Google Fonts Knowledge covers variable fonts.
Zach Leatherman on developing a strategy for loading fonts on CSS tricks.

An excellent tool for inspecting variable fonts (and, really, any kind of webfont) is Wakamai Fondue, available on the web and at the command line.

Finally, a couple of fun facts that surfaced while researching this article:

Chris Coyier: Actually, the San Francisco Typeface Does Ship as a Variable Font.
Firefox is the only browser that uses b, strong { font-weight: bolder } in its user agent stylesheet. Šime Vidas points out how this can be a problem with variable fonts.
the largest Unicode code point is U+10FFFF.

Sizing images based on their aspect ratio

2022-08-07T00:00:00Z

Grids of logos are my nightmare.

I mean, never mind the opportunity to learn the bewildering, but admittedly finite, array of file formats in which visual assets can conceivably be stored and distributed. But the intricate dance of making all logos look equally prominent in the grid is something for which I can only muster very little enthusiasm.

Like with all tedious things, I've found myself wishing more than once that CSS included a declarative way to make images of various aspect ratios look the same size.

Making images „look the same size”

A definition of that might be to make the images occupy the same surface area. Let's work out the math.

We want to keep constant the area of an image of natural width W and height H. To that end, we must find its preferred dimensions Wp and Hp so that Wp × Hp is uniform across images. The givens:

area = Wp * Hp;
aspect_ratio = W / H = Wp / Hp;

…ultimately lead to the formula below. (Individual steps are left as an exercise to the reader.)

Wp = sqrt(area) * sqrt(W / H);

Let's express this formula in HTML and CSS.

You should already have explicit width and height attributes on <img> elements in your markup to define the intrinsic size of the image and prevent layout shifts as the image loads. The values of these attributes cannot be used in CSS directly, so we also pass them as custom properties via the style attribute.

<div class='ratio-gallery'>
	<img 
		src='https://source.unsplash.com/random/800x600' 
		alt='800 by 600 pixels placeholder image'
		width='800' 
		height='600' 
		style='--w: 800; --h: 600'
	/>
</div>

Note that we're passing the width and height as unitless numbers. This gives us the most flexibility when using the values in CSS math functions. The sqrt() function, in particular, only accepts <number>s. Our basic CSS looks like this:

.ratio-gallery {
	--basis: 300px;
}

.ratio-gallery img {
	--w: 1;
	--h: 1;
	width: calc(var(--basis) * sqrt(var(--w) / var(--h)));
	height: auto;
}

Instead of defining an --area constant like in our math formula, we use its square root directly as --basis. This has the added benefit of being more intuitive: you can think of its value as making the image as large as a square of that side length. For example, --basis: 300px makes the image as large as a 300×300 square.

That's pretty much all there is to the technique. Below are some images sized with it, placed in a flexbox container. In a browser that supports the sqrt() CSS function — which, at the moment of writing, is just Safari — you should see three images of identical surface areas:

Fallback to a fixed aspect ratio

The following @supports at-rule will check if the browser supports the sqrt() CSS function:

/*
	To detect support for `sqrt()` we use `flex`,
	the shortest (afaict) CSS property that accepts 
	the `<number>` value that `sqrt()` produces.
 */
@supports (flex: sqrt(0)) {

}

In browsers that don't support this function, we could enforce a fixed aspect-ratio and use the object-fit property to clip the image to fit, as described by Michelle Barker. To make the fallback comparable, we do have to precompute the square root of this fixed aspect ratio and factor it in — not ideal, but not exceedingly annoying. Here's the technique along with the fallback:

.ratio-gallery {
	--basis: 300px;
}

.ratio-gallery img {
	--w: 1;
	--h: 1;
	width: calc(var(--basis) * sqrt(var(--w) / var(--h)));
	height: auto;
}

@supports not (flex: sqrt(0)) {
	.ratio-gallery img {
		width: calc(var(--basis) * 1.224 /* = sqrt(3/2) */);
		aspect-ratio: 3/2;
		object-fit: cover;
	}
}

Here is a more developed demo:

Demo: equally-sized images, with fallback

Wrapping up

Turns out aspect-ratio-aware sizing is not too hard to pull off as long as we have control of image dimensions in the markup. The technique may be especially useful in content management systems where authors are able to upload arbitrary assets that need to look good next to each other, and where the author is not expected, or is unable, to fine-tune the sizes via custom CSS.

Addenda

Defensive CSS

Šime helpfully pointed out that the basic technique does not handle extreme aspect ratios well. In fact, the arbitrary in arbitrary aspect ratio is the cue to put our defensive CSS hat on.

We can limit the space the image takes in any one direction with max-width and max-height:

.ratio-gallery img {
	--w: 1;
	--h: 1;
	width: calc(var(--basis) * sqrt(var(--w) / var(--h)));
	height: auto;
	max-width: calc(var(--basis) * 2);
	max-height: calc(var(--basis) * 2);
}

(You might also want to throw in an object-fit: cover to handle very tall images that get squished when max-height kicks in.)

Here is the demo again, which includes the defensive CSS:

Demo: equally-sized images, with fallback

Prior art

Update Dec. 2022: Piper Haywood had described back in 2020 a technique for sizing images using the sqrt() CSS function, at a time when the function was not yet supported in any browser. Nick Sherman produced a nice demo for the technique, using an approximation of sqrt().

Button type matters, after all

2022-03-26T00:00:00Z

The <button type='button'> construct is HTML's eat your veggies. It's good advice and you should always do it. Between you and me, we both know it's a bit silly: of course a button is a button, I mean…

Well, buddy, if you've been omitting your type attribute with impunity, I'm here to tell you that one day, without warning, this habit is going to bite you in the ass. I know it because *cue pensive piano music* it happened to me. One day I did a boo-boo and it only occurred to me a while later that the boo-boo was there.

In all honesty, the actual event lacked the gravitas of my dramatization here, but I thought it was delightfully unintuitive form behavior so I posted about it on social media. Seeing other people go huh, I thought I'd unpack the idea a bit.

Here is the markup of a typical JavaScript-enhanced log in form. Excuse the inline event listeners, which are used to make the code sample simpler:

<form action='' onsubmit='login(…); return false;'>
	<p>
		<label>Username: <input type='text' name='username'/></label>
	</p>
	<p>
		<label>Password: <input type='password' name='password'/></label>
	</p>
	<button type='submit'>Log in</button>
</form>

Now let's say you add to the form a button that reveals the password in plain text:

<form action='' onsubmit='login(…); return false;'>
	<p>
		<label>Username: <input type='text' name='username'/></label>
	</p>
	<p>
		<label>Password: <input type='password' name='password'/></label>
		<button onclick='this.form.password.type="text"; return false;'>
			Show password
		</button>
	</p>
	<button type='submit'>Log in</button>
</form>

What unexpected behavior have you introduced to this form with the addition of that button?

Answer: If the user presses the Enter key after they've typed in their password, instead of submitting the form, the user's password is revealed in plain text.

The Show password button lacks an explicit type='button'and so it gets the default type='submit'. Outside of forms, this has no ill effect: without a form to submit, the button behaves like type='button' in that it does nothing. Put it into a form and it suddenly behaves as an actual submit button.

When the user presses the Enter key while focused on one of the form's inputs, the form gets submitted via the so-called implicit submission. The browser doesn't simply submit the form, it actually clicks the first submit button it finds in the form. From the HTML spec (emphasis mine):

If the user agent supports letting the user submit a form implicitly (for example, on some platforms hitting the "enter" key while a text control is focused implicitly submits the form), then doing so for a form, whose default button [ie. the first submit button in tree order whose form owner is that form element] has activation behavior and is not disabled, must cause the user agent to fire a click event at that default button.

Because the Show password button is implicitly a submit button, and it happened to be added sooner in tree order than the legit submit button, the implicit submission reveals the user's password. Ta-daa!

And that's why you always write <button type='button'>.

Coda: actually marking up a login form

Besides the point I was trying to make about implicit form submission, there are more things that this toy markup misses, among which:

The autocomplete attribute can help password managers make better choices about storing and filling in information for the form.
Users of assistive technology are not well served by the Show password functionality. If you're serious about implementing this feature, Nicolas Steenhout touches on the topic in his Show/Hide password accessibility and password hints tutorial, and the GDS document even more gotchas in Simple things are complicated: making a show password option. But, more importantly, everyone seems to agree that we would be better off if browsers themselves had the feature baked in.

Observe an element's focus-within state

2022-03-18T19:23:37Z

With this short tip, we'll devise a way to tell when a DOM element's focus-within state changes, that is observing whenever the element, or any of its descendants, holds the focus.

You may already be familiar with the the CSS :focus-within pseudo-class that provides such a hook:

/*
	Emphasize the container when it has focus within.
 */
.container:focus-within {
	outline: 1px dotted currentColor;
}

In JavaScript, you could match that CSS pseudo-class or look at the containment of the active element to check if, at that particular point in time, the focus is within a DOM element:

/*
	Test if the container has focus within with either:

	* matching the :focus-within CSS pseudo-class
	* checking that the active element is contained within
 */
containerElement.matches(':focus-within');
containerElement.contains(document.activeElement);

Those checks are great for one-off tests, but what if we want to observe changes in the element's focus containment? While there are no specific DOM events for it, we'll build our own using the available focus events.

DOM focus events: a refresher

There are four events under the FocusEvent umbrella that tell us when an object obtains or loses focus. Here they are, helpfully categorized like bottled water:

focusin and focusout are the bubbly events;
focus and blur are the still events (they don't, ahem, bubble).

I don't have the exact reasons for why the focus and blur events don't bubble up the DOM tree, but Peter-Paul Koch has a plausible explanation:

The reason focus and blur don’t bubble is that the events mean something quite different on the window and on any other focusable element. These two definitions should not be confused, and therefore the events cannot be allowed to bubble up to the document.

The great thing about all focus events, which makes many scenarios much simpler to manage, is that their relatedTarget property points to the other relevant element. For events related to loss of focus (blur and focusout) the related target is the element that will receive the focus next, if any; for events signifying acquisition of focus (focus and focusin), the related target is the previously focused element, if any.

Here's the sequence of events that gets triggered for when focus shifts from element A to element B:

Order	Event	`.target`	`.relatedTarget`
1	`blur`	A	B
2	`focusout`	A	B
3	`focus`	B	A
4	`focusin`	B	A

All this being said, let's write some code.

Observing the focus-within state

Whenever the container, or one of its descendants, receives focus, the focusin event bubbles up the DOM tree to the container (and beyond). The event's relatedTarget property points to the previously focused element, if any. To detect when the container first receives focus from outside, we can check for containment:

containerElement.addEventListener('focusin', function(e) {
	if (e.currentTarget.contains(e.relatedTarget)) {
		/* Focus was already in the container */
	} else {
		/* Focus was received from outside the container */
	}
});

We use the same check for containment to detect when focus leaves the element, this time with the focusout event. Since this event's relatedTarget property now points to where the focus is heading next, the check works the other way around too:

containerElement.addEventListener('focusout', function(e) {
	if (e.currentTarget.contains(e.relatedTarget)) {
		/* Focus will still be within the container */
	} else {
		/* Focus will leave the container */
	}
});

And that's it! Within a few short lines, we're already handling focus containment changes that cover a whole range of input methods (mouse, touch, keyboard).

Handling focus outside the page

When used as the trigger for hiding pop-ups or drop-downs, the basic focusout implementation can occasionally be too eager: annoyingly, the element disappears before we can inspect it with the browser's developer tools.

This is just one instance of the focus moving outside the web page (without necessarily hiding the page). In these cases we might decide we want to keep the element visible.

In the code sample below, we use the Document.hasFocus() method to detect the lost focus and keep the element visible:

containerElement.addEventListener('focusout', function(e) {
	/*
		If the document has lost focus,
		skip the containment check 
		and keep the element visible.
	 */
	if (!document.hasFocus()) {
		return;
	}
	if (!e.currentTarget.contains(e.relatedTarget)) {
		hideSelf();
	}
});

However, once the element loses focus along with the document, and we just ignore the event and not hide the element, we run into the opposite problem: the element just sits in our face when we get back and poke around the page. It doesn't know we're back.

Before giving away the document's focus, we need to attach a listener for when, if ever, the focus returns. The window focus event — the non-bubbly kind — is perfect here, when paired with one of the two on-demand tests we mentioned in the introduction:

containerElement.addEventListener('focusout', function(e) {
	const self = e.currentTarget;
	/*
		If the document has lost focus,
		don't hide the container just yet,
		wait until the focus is returned.
	 */
	if (!document.hasFocus()) {
		window.addEventListener('focus', function focusReturn() {
			/* 
				We want the listener to be triggered just once,
				so we have it remove itself from the `focus` event.
			*/
			window.removeEventListener('focus', focusReturn);

			/*
				Test whether the container is still in the DOM 
				and whether the active element is contained within.
			 */
			if (self.isConnected && !self.contains(document.activeElement)) {
				hideSelf();
			}
		});
		return;
	}
	if (!self.contains(e.relatedTarget)) {
		hideSelf();
	}
});

A couple of notes on this listener:

Because the focus event that returns focus to the page can happen after a long time (or maybe never), it's useful to check that the element is still in the DOM when it finally occurs.
Since the event listener is set up to remove itself after the first invocation, we don't expect it to generate a memory leak. The addEventListener() method does have the convenient { once: true } option but the do-it-yourself way is more resilient. A browser that doesn't support the once option would treat the function as a normal listener and keep it around forever — leaks ahoy!

Fixing some browser quirks

Blurring in iOS Safari

In iOS Safari, tapping on non-focusable elements on the page won't blur the active element. It seems to need a new focus target to which to switch before it gives up its current focus. To make sure that the tap outside to blur functionality works as expected, we can mark the body as focusable with tabindex='-1':

<html lang='en'>
	<body tabindex='-1'>
		…
	</body>
</html>

Conclusion

You can see the full code in action in the demo below, which compares the CSS :focus-within pseudo-class with the JavaScript implementation:

Demo: Detect focus-within state

My favorite records from 2021

2022-01-02T00:00:00Z

Here are my top 20 albums of 2021, in alphabetical order:

More great albums released this year:

Found after the year was over:

Enzo Favata The Crossing (found 2023)

Timeline of favorite records: 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025.

Other 2021 lists: Rough Trade UK, Rough Trade US, Bleep, The Quietus, Boomkat, The Wire.

Pinch me, I'm zooming: gestures in the DOM

2021-11-07T00:00:00Z

Interpreting multi-touch user gestures on the web is not as straightforward as you'd imagine.

In this article we look at how current major browsers behave (and misbehave) in regards to gestures, and piece together a workable solution that uses wheel, touch, and gesture DOM events.

Table of contents

Anatomy of a gesture

Two-finger gestures on touchscreens and modern trackpads allow users to manipulate on-screen elements as if they were physical objects: to move them and spin them around, to bring them closer or push them further away. Such a gesture encodes a combination of translation, uniform scaling, and rotation to apply to the target element. This is also known as an (affine) linear transformation.

The impression of direct manipulation is created when the transformation maps naturally to the movement of the touchpoints. There are ideas for novel ways to interpret a gesture, but operating systems have settled on a mapping which keeps the parts you touch underneath your fingertips throughout the gesture. This is the approach we're most familiar with, and the one we will explore in this article.

Let's see how a two-finger gesture maps to the basic components of a linear transformation.

Scale. The change in distance between the two touchpoints throughout the gesture dictates the scale: if the fingers are brought together to half the initial distance, the object should be made half its original size.

Rotation. The slope defined by the two touchpoints dictates the rotation to be applied to the object.

Origin and translation. The midpoint, located halfway between the two touchpoints, has a double role: its initial coordinates establish the transformation origin, and its movement throughout the gesture translates the object accordingly.

Native applications on touch-enabled devices have to access to high-level APIs that provide the translation, scale, rotation, and origin of a user gesture directly. On the web, we have to glue together several types of events to get a similar results across a variety of platforms.

The relevant DOM events: wheel, touch, and gesture

A WheelEvent is triggered when the user intends to scroll an element with the mousewheel (from which the interface takes its name), a separate "scroll area" on older trackpads, or the entire surface area of newer trackpads with the two-finger vertical movement.

Wheel events have deltaX, deltaY, and deltaZ properties to encode the displacement dictated by the input device, and a deltaMode to establish the unit of measurement:

`deltaMode`	Value	Meaning
`DOM_DELTA_PIXEL`	`0`	scroll a precise amount of pixels
`DOM_DELTA_LINE`	`1`	scroll by lines
`DOM_DELTA_PAGE`	`2`	scroll by entire pages

As pinch gestures on trackpads became more commonplace, browser implementers needed a way support them in desktop browsers. Kenneth Auchenberg, in his article on detecting multi-touch trackpad gestures, brings together key pieces of the story.

In short, Chrome settled on an approach inspired by Internet Explorer: encode pinch gestures as wheel events with ctrlKey: true, and the deltaY property holding the proposed scale increment. Firefox eventually did the same, and with Microsoft Edge recently having switched to Chromium as its underlying engine, we have a "standard" of sorts. I use scare-quotes because, as we'll see in the next section, some aspects don't quite match across browsers.

Sometime between Chrome and Firefox adding support for pinch-zoom, Safari 9.1 brought its very own GestureEvent, which exposes precomputed scale and rotation properties, to the desktop.

To this day, Safari remains the only browser that implements GestureEvent, even among browsers on touch-enabled platforms. Instead, mobile browsers produce the lower-level TouchEvents, which encode the positions of individual touchpoints in a gesture. They allow us, with a bit more effort than is required with higher-level events, to compute all the components of the linear transformation ourselves.

Whereas WheelEvent only encodes scale, and GestureEvent includes scale and rotation, TouchEvent lets us capture the translation as well, giving us finer-grained control over how we interpret the gesture.

Combined wheel, gesture and touch events seem sufficient to handle two-finger gestures across a variety of platforms. Let's see how this intuition, *ahem*, pans out.

Putting browsers to the test

I've put together a test page that logs relevant properties of all the wheel, gesture, and touch events it captures:

DOM Gesture Logger

I've tested a series of scrolls and pinches in recent versions of Firefox, Chrome, Safari, and Edge (Chromium-based), on a variety of devices I managed to procure for this purpose:

a MacBook Pro (macOS Big Sur);
a Surface Laptop with a touchscreen and built-in precision touchpad (Windows 10);
an ASUS notebook with a non-precision touchpad (Windows 10);
an iPhone (iOS 14);
an iPad with a keyboard (iPadOS 14); and
an external mouse to connect to all laptops.

Let's dig into a few of the results, and how they inform our solution.

Results on macOS

When you perfrom a pinch-zoom gesture, Firefox and Chrome produce a wheel event with a deltaY: ±scale, ctrlKey: true. They produce an identical result when you scroll normally with two fingers while physically pressing down the Ctrl key, with the difference that the latter is subject to inertial scrolling.

Safari reacts to the proprietary gesturestart, gesturechange, and gestureend events and produces a precomputed scale and rotation.

In all browsers, clientX and clientY, as well as the position of the on-screen cursor, remain constant throughout two-finger gestures. This pair of coordinates establishes the gesture origin.

In the process of testing various modifier keys, I noted some default browser behaviors that you'll likely need to deflect with event.preventDefault():

Option + wheel in Firefox navigates (or rather flies) through the browser history; this would make sense for discrete steps on a mousewheel, but feels too weird to be useful on an inertial trackpad.
Command + wheel in Firefox zooms in and out of the page, similarly to the Command + and Command - keyboard shortcuts;
Pinching inwards in Safari minimizes the tab into a tab overview screen.

External, third-party mice are a different matter. Instead of the smooth pixel increments on the trackpad, the mouse's wheel jumps entire lines at a time. (The Scrolling speed setting in System Preferences > Mouse controls how many.)

Accordingly, Firefox shows deltaY: ±1, deltaMode: DOM_DELTA_LINE for a tick of the wheel. This is the first, and at least on macOS the only, encounter with DOM_DELTA_LINE. Chrome and Safari stick with deltaMode: DOM_DELTA_PIXEL and a much larger deltaY, sometimes hundreds of pixels at a time. This is an instance of the many more pixels than expected deviation of which we'll see more throughout the test session. A basic pinch-zoom implementation that doesn't account for this quirk will zoom in and out in large, hard-to-control strides when you use the mousewheel.

In all three browsers, deltaX is normally zero. Holding down the Shift key, a common way for users of an external mouse to scroll horizontally, swaps deltas and deltaY becomes zero instead.

Results on Windows

A precision touchpad works on Windows similarly to the Magic Trackpad on macOS: Firefox, Chrome, and Edge produce results comparable to what we've seen on macOS. The quirks emerge with non-precision touchpads and external mice, however.

On Windows, the wheel of an external mouse has two scroll modes: either L lines at a time (with a configurable L), or a whole page at a time.

When you use the external mouse with line-scrolling, Firefox produces the expected deltaY: ±L, deltaMode: DOM_DELTA_LINE. Chrome generates deltaY: ±L * N, deltaMode: DOM_DELTA_PIXEL, where N is a multiplier dictated by the browser, and which varies by machine: I've seen 33px on the ASUS laptop and 50px on the Surface. (There's probably an inner logic to what's going on, but it doesn't warrant further investigation at this point.) Edge produces deltaY: ±100, deltaMode: DOM_DELTA_PIXEL, so 100px regardless on the number of lines L that the mouse is configured to scroll. With page-scrolling, browsers uniformly report deltaY: ±1, deltaMode: DOM_DELTA_PAGE. None of the three browsers support holding down the Shift to reverse the scroll axis of the mousewheel.

On non-precision touchpads, the effect of scrolling on the primary (vertical) axis will mostly be equivalent to that of a mousewheel. The behavior of the secondary (horizontal) axis will not necessarily match it. At least on the machines on which I performed the tests, mouse settings also apply to the touchpad, even when there was no external mouse attached.

In Firefox, in line-scrolling mode, scrolls on both axes produce deltaMode: DOM_DELTA_LINE with deltaX and deltaY, respectively, containing a fraction of a line; a pinch gesture produces a constant deltaY: ±L, deltaMode: DOM_DELTA_LINE, ctrlKey: true. In page-scrolling mode, scrolls on the primary axis produce deltaMode: DOM_DELTA_PAGE, while on the secondary axis it remains in deltaMode: DOM_DELTA_LINE; the pinch gesture produces deltaY: ±1, deltaMode: DOM_DELTA_PAGE, ctrlKey: true. In Chrome, a surprising result is that when you scroll on the secondary axis you get deltaX: 0, deltaY: N * ±L, shiftKey: true. Otherwise, the effects seen with a non-precision touchpad on Windows are of the unexpected deltaMode or unexpected deltaY value varieties.

Unifying wheel, touch, and gesture events

The API that unifies wheel, touch, and gesture events should look a lot like Safari's GestureEvent. We will model it around three callbacks:

startGesture(gesture), invoked at the beginning of the transformation;
doGesture(gesture), invoked continously throughout the transformation;
endGesture(gesture), invoked at the end of the transformation.

The gesture object should describe the transformation completely:

{
	origin: { x: …, y: … },
	translation: { x: …, y: … },
	scale: …,
	rotation: …
}

Let's see how each type of event maps to this setup.

Processing Safari's gesture events

GestureEvents are the most straightforward to map, so we'll start with those.

We pick scale and rotation properties directly from the event object, and fill in the origin based on the mouse coordinates. Since these types of events don't include a translation, we assume there to be no translation, that is translation: { x: 0, y: 0 }.

/* Handle Safari GestureEvents */

let gesture = false;
container.addEventListener('gesturestart', e => {
	if (e.cancelable !== false) {
		e.preventDefault();
	}
	if (!gesture) {
		startGesture({
			translation: { x: 0, y: 0 },
			scale: e.scale,
			rotation: e.rotation,
			origin: { x: e.clientX, y: e.clientY }
		});
		gesture = true;
	}
}, { passive: false });

container.addEventListener('gesturechange', e => {
	if (e.cancelable !== false) {
		e.preventDefault();
	}
	if (gesture) {
		doGesture({
			translation: { x: 0, y: 0 },
			scale: e.scale,
			rotation: e.rotation,
			origin: { x: e.clientX, y: e.clientY }
		});
	}
}, { passive: false });

container.addEventListener('gestureend', e => {
	if (gesture) {
		endGesture({
			translation: { x: 0, y: 0 },
			scale: e.scale,
			rotation: e.rotation,
			origin: { x: e.clientX, y: e.clientY }
		});
		gesture = false;
	}
});

An occasional misfire where the gestureend event is emitted twice at the end of a gesture (WebKit#233137) is worked around with the gesture flag.

Safari also has a built-in pinch to show all tabs gesture which normally gets canceled when we call preventDefault() on the gesture events. However, when the user combines a scale and rotation gesture, the browser behavior will be triggered nonetheless (WebKit#233141). I don't have a workaround yet, but would love to know if there is one.

Sidenote: Passive event listeners

It used to be the case that we could preventDefault() most events from any listener. This forces the browser to always be ready to have its default behavior overriden, which in some situations (scrolling, touch events) leads to less than ideal performance.

To mitigate this, the passive flag was introduced as an option for addEventListener(). To be able to prevent the default browser behavior, you'd need to register an active event listener by sending in the { passive: false } option.

For backwards compatibility, events are active by default. But, in some browsers for some performance-critical contexts, they default to being passive. To make sure our event listeners work as expected (now, and going forwaRD), throughout the code samples we use { passive: false } explicitly whenever we want to call preventDefault(), first checking that the event is cancelable.

Starting with Safari 15, macOS Safari also emits wheel events for the pinch-zoom gesture (WebKit#225788). If you're only interested in scale transformations, in the future you'll be able listen to wheel events, as shown in the next section, instead of relying on the non-standard GestureEvent.

Converting wheel events to gestures

For wheel events, we have a few things to figure out:

How to normalize the various ways browsers emit wheel events into an uniform delta value.
How to map the occurrence of wheel events to startGesture, doGesture, and endGesture.
How to compute the scale value from the delta.

Let's explore each sub-problem one by one.

1. Normalizing `wheel` events

Our goal here is to implement a normalizeWheelEvent function as described below:

/*
	Normalizes WheelEvent `e`,
	returning an array of deltas `[dx, dy]`.
*/
function normalizeWheelEvent(e) {
	let dx = e.deltaX;
	let dy = e.deltaY;
	// TODO: normalize dx, dy
	return [dx, dy];
}

This is where we can put our experimental browser data to good use. Let's recap some findings relevant to normalizing wheel events.

The browser may emit deltaX: 0, deltaY: N, shiftKey: true when scrolling horizontally. We want to interpret this as deltaX: N, deltaY: 0 instead:

// swap `dx` and `dy`:
if (dx === 0 && e.shiftKey) {
	[dx, dy] = [dy, dx];
}

Furthermore, the browser may emit values in a deltaMode other than pixels; for each, we need a multiplier:

if (e.deltaMode === WheelEvent.DOM_DELTA_LINE) {
	dx *= 8;
	dy *= 8;
} else if (e.deltaMode === WheelEvent.DOM_DELTA_PAGE) {
	dx *= 24;
	dy *= 24;
}

The choice of multipliers ultimately depends on the application. We might take inspiration from browsers themselves or other tools the user may be familiar with; a document viewer may respect the mouse configuration to scroll one page at a time; map-pinching, on the other hand, may benefit from smaller increments.

Finally, a browser may not emit DOM_DELTA_LINE or DOM_DELTA_PAGE where the input device settings dictate them, and instead offer a premultiplied value in DOM_DELTA_PIXELs. This value is often very large, 100px or more at a time.

Why would browsers do that? With a whole lot of code out there that fails to look at the deltaMode, minuscule DOM_DELTA_LINE / DOM_DELTA_PAGE increments that get incorrectly interpreted as pixels would make for lackluster scrolls. Browsers can be excused for trying to give a helping hand, but premultiplied pixel values — often computed in a way that only works if you think of wheel events as signifying scroll intents — makes them harder to use for other purposes.

Thankfully, even in the absence of a more sophisticated approach, simply setting the upper limit of deltaY to something reasonable (e.g. 24px), just to pull the breaks on wild zooms, can go a long way towards improving the experience:

/*
	Note: we're using `Math.sign()` and `Math.min()` 
	to impose a maximum on the *absolute* value 
	of a possibly-negative number.
 */
dy = Math.sign(dy) * Math.min(24, Math.abs(dy));

These few adjustments should cover a vast array of variations across browsers and devices. Yay compromise!

2. Generating gesture events from `wheel` events

With normalization out of the way, the next obstacle is that wheel events are individual occurrences, for which we must devise a "start" and "end" if we want to call startGesture and endGesture.

The first wheel event marks the beginning of a gesture. But what about the end? In line with keeping things simple, we consider a gesture done once a number of milliseconds pass since the last wheel event. An outline for batching wheel events into gestures is listed below:

let timer;
let gesture = null;
container.addEventListener('wheel', function(e) {
	if (e.cancelable !== false) {
		e.preventDefault();
	}
	/*
		If we don't have a `gesture`, it means
		we're just starting a batch of `wheel` events.
	 */
	if (!gesture) {
		gesture = { … };
		startGesture(gesture);
	}

	/*
		Perform the current wheel gesture
	 */
	gesture = { … };
	doGesture(gesture);

	if (timer) {
		window.clearTimeout(timer);
	}

	/*
		When the time runs out, call `endGesture`.
	 */
	timer = window.setTimeout(function() {
		endGesture(gesture);
		gesture = null;
	}, 200); // timeout in milliseconds
}, { passive: false });

The actual gesture arguments to startGesture, doGesture, and endGesture functions are explored in the next section.

3. Converting the wheel delta to a `scale`

In Safari, a gesturechange event's scale property holds the accumulated scale to apply to the object at each moment of the gesture:

final_scale = initial_scale * event.scale;

In fact, the documentation for the UIPinchGestureRecognizer which native iOS apps use to detect pinch gestures, and which works similarly to Safari's GestureEvent, emphasizes this aspect:

Important: Take care when applying a pinch gesture recognizer’s scale factor to your content, or you might get unexpected results. Because your action method may be called many times, you cannot simply apply the current scale factor to your content. If you multiply each new scale value by the current value of your content, which has already been scaled by previous calls to your action method, your content will grow or shrink exponentially. Instead, cache the original value of your content, apply the scale factor to that original value, and apply the new value back to your content. Alternatively, reset the scale factor to 1.0 after applying each new change.

On the other hand, pinch gestures encoded as wheel events contain deltas that correspond to percentual changes in scale that you're supposed to apply incrementally. Negative deltas increase the object's scale, while positive deltas dicrease the object's scale. For example:

delta: 10 shrinks the object by 10%
delta: -20 enlarges the object by 20%

A single formula covers both cases:

let scale = previous_scale * (1 - delta / 100);

Accumulating a series of deltas d1, d2, …, dN into a final scaling factor requires some back-of-the-napkin arithmetics. The intermediary scales…

let scale1 = initial_scale * (1 - d1/100);
let scale2 = scale1 * (1 - d2/100);
let scale3 = scale2 * (1 - d3/100);
// …and so on

…lead us to the formula for the final scale:

let factor = (1 - d1/100) * (1 - d2/100) * … * (1 - dN/100);
let final_scale = initial_scale * factor;

This lets us flesh out the scale we're supposed to send to our startGestue, doGesture and endGesture functions we introduced in the previous section:

let timer;
let gesture = null;
container.addEventListener('wheel', function(e) {
	if (e.cancelable !== false) {
		e.preventDefault();
	}
	let [dx, dy] = normalizeWheel(e);

	if (!gesture) {
		gesture = {
			origin: { x: e.clientX, y: e.clientY },
			scale: 1,
			translation: { x: 0, y: 0 }
		};
		startGesture(gesture);
	}
	
	if (e.ctrlKey) {
		// pinch-zoom gesture
		let factor = (1 - dy / 100);
		gesture = {
			origin: { x: e.clientX, y: e.clientY },
			scale: gesture.scale * factor,
			translation: gesture.translation
		};
	} else {
		// pan gesture
		gesture = {
			origin: { x: e.clientX, y: e.clientY },
			scale: gesture.scale,
			translation: { 
				x: gesture.translation.x - dx, 
				y: gesture.translation.y - dy
			}
		};
	}
	doGesture(gesture);

	if (timer) {
		window.clearTimeout(timer);
	}
	timer = window.setTimeout(function() {
		if (gesture) {
			endGesture(gesture);
			gesture = null;
		}
	}, 200);
}, { passive: false });

This approach will get us scale values in the same ballpark for WheelEvent and GestureEvent, but you'll notice pinches in Firefox and Chrome effect a smaller scale factor than similar gestures in Safari. We can solve this by mixing in a SPEEDUP multiplier that makes up for the difference:

/*
	Eyeballing it suggests the sweet spot
	for SPEEDUP is somewhere between 
	1.5 and 3. Season to taste!
*/
const WHEEL_SCALE_SPEEDUP = 2.5;
let factor = (1 - (WHEEL_SCALE_SPEEDUP * dy) / 100);

As Stephane points out over email, there's one final touch-up we could make that involves the symmetry of negative and positive dy values: when you shrink an object by 20%, you can't bring it back to its original scale by enlarging it by 20%.

That wheel events for pinching in and out don't add up to zero is an unfortunate side-effect of how browsers have implemented the pinch-to-wheel feature. To work around the asymmetry we can adjust how we shrink the object by N% to mean shrink it by X% so that enlarging it by N% would restore the original scale. Solving the equation for X:

(1 - X/100) * (1 + N/100) = 1

…gives us the adjusted factor for positive values of dy:

let factor = dy <= 0 ? 
	1 - (WHEEL_SCALE_SPEEDUP * dy) / 100 : 
	1 / (1 + (WHEEL_SCALE_SPEEDUP * dy) / 100);

The listing below contains the final code for handling wheel events, let's see what we can do about touch events next.

Full listing for the wheel handling code

const WHEEL_SCALE_SPEEDUP = 2;
const WHEEL_TRANSLATION_SPEEDUP = 2;

let gesture = false;
let timer;

container.addEventListener('wheel', function(e) {
	if (e.cancelable !== false) {
		e.preventDefault();
	}
	let [dx, dy] = normalizeWheel(e);

	if (!gesture) {
		gesture = {
			origin: { x: e.clientX, y: e.clientY },
			scale: 1,
			translation: { x: 0, y: 0 }
		};
		startGesture(gesture);
	}

	if (e.ctrlKey) {
		// pinch-zoom
		let factor = dy <= 0 ? 
			1 - (WHEEL_SCALE_SPEEDUP * dy) / 100 : 
			1 / (1 + (WHEEL_SCALE_SPEEDUP * dy) / 100);
		gesture = {
			origin: { x: e.clientX, y: e.clientY },
			scale: gesture.scale * factor,
			translation: gesture.translation
		};
	} else {
		// panning
		gesture = {
			origin: { x: e.clientX, y: e.clientY },
			scale: gesture.scale,
			translation: { 
				x: gesture.translation.x - WHEEL_TRANSLATION_SPEEDUP * dx, 
				y: gesture.translation.y - WHEEL_TRANSLATION_SPEEDUP * dy
			}
		};
	}
	doGesture(gesture);
	
	if (timer) {
		window.clearTimeout(timer);
	}
	timer = window.setTimeout(function() {
		if (gesture) {
			endGesture(gesture);
			gesture = null;
		}
	}, 200);
}, { passive: false });

Converting touch events to gestures

Touch events are more low-level. They contain everything we need to derive each component of the linear transformation ourselves. Each individual touchpoint is encoded in the event.touches list as a Touch object containing, among others, its coordinates clientX and clientY.

Emitting gesture-like events

The four touch events are touchstart, touchmove, touchend and touchcancel. We want to map these to the startGesture, doGesture and endGesture callbacks.

Each individual touch produces a touchstart event on contact and a touchend event when lifted from the touchscreen. The touchcancel event is emitted when the browser wants to bail out of the gesture (for example, when adding too many touchpoints to the screen).

For our purpose we want to observe gestures involving exactly two touchpoints, and we use the same function watchTouches for all three events.

let gesture = false;
function watchTouches(e) {
	if (e.touches.length === 2) {
		gesture = true;
		if (e.cancelable !== false) {
			e.preventDefault();
		}
		startGesture(…);
		el.addEventListener('touchmove', touchMove);
		el.addEventListener('touchend', watchTouches);
		el.addEventListener('touchcancel', watchTouches);
	} else if (gesture) {
		gesture = false;
		endGesture(…);
		el.removeEventListener('touchmove', touchMove);
		el.removeEventListener('touchend', watchTouches);
		el.removeEventListener('touchcancel', watchTouches);
	}
};
document.addEventListener('touchstart', watchTouches);

The touchmove event is the only one using its own separate listener:

function touchMove(e) {
	if (e.touches.length === 2) {
		doGesture(…);
		if (e.cancelable !== false) {
			e.preventDefault();
		}
	}
}

Producing the linear transformation

The initial touches that begin a gesture must be stored so we can keep track of how they move throughout the gesture. We take advantage of the fact that TouchList and Touch objects are immutable and just save a reference:

let gesture = false;
let initial_touches;
function watchTouches(e) {
	if (e.touches.length === 2) {
		gesture = true;
		initial_touches = e.touches;
		startGesture(…);
		…
	}
	…
}

The argument to startGesture is straightforward: we haven't done any gesturing yet, so all parts of the transformation are set to their initial values. The origin of the transformation is the midpoint between the two initial touchpoints:

startGesture({
	scale: 1,
	rotation: 0,
	translation: { x: 0, y: 0 },
	origin: midpoint(initial_touches)
});

With the midpoint computed as:

function midpoint(touches) {
	let [t1, t2] = touches;
	return {
		x: (t1.clientX + t2.clientX) / 2, 
		y: (t1.clientY + t2.clientY) / 2
	};
}

For the doGesture function, we must compare our pair of current touchpoints to the initial ones, and using the distance and angle formed by each pair (for which functions are defined below):

function distance(touches) {
	let [t1, t2] = touches;
	return Math.hypot(t2.clientX - t1.clientX, t2.clientY - t1.clientY);
}

function angle(touches) {
	let [t1, t2] = touches;
	let dx = t2.clientX - t1.clientX;
	let dy = t2.clientY - t1.clientY;
	return Math.atan2(dy, dx) * 180 / Math.PI;
}

We can produce the argument to doGesture:

let mp_init = midpoint(initial_touches);
let mp_curr = midpoint(e.touches);

doGesture({
	scale: distance(e.touches) / distance(initial_touches),
	rotation: angle(e.touches) - angle(initial_touches),
	translation: {
		x: mp_curr.x - mp_init.x, 
		y: mp_curr.y - mp_init.y
	},
	origin: mp_init
});

Finally, let's tackle the argument to endGesture. It can't be computed on the spot, since at the moment when endGesture gets called, we explicitly don't have two touchpoints available anymore. We must keep track of the last gesture we have produced and send that to the endGesture function. The gesture variable, which up until this point held a boolean value, sounds like a good place to do it.

Expand the section below to see how the watchTouches and touchMove functions look with everything put together.

Full listing for the touch events code

let gesture = null;
let initial_touches;

function watchTouches(e) {
	if (e.touches.length === 2) {
		initial_touches = e.touches;
		gesture = {
			scale: 1,
			rotation: 0,
			translation: { x: 0, y: 0 },
			origin: midpoint(initial_touches)
		};
		if (e.type === 'touchstart') {
			e.preventDefault();
		}
		startGesture(gesture);
		container.addEventListener('touchmove', touchMove, { passive: false });
		container.addEventListener('touchend', watchTouches);
		container.addEventListener('touchcancel', watchTouches);
	} else if (gesture) {
		endGesture(gesture);
		gesture = null;
		container.removeEventListener('touchmove', touchMove);
		container.removeEventListener('touchend', watchTouches);
		container.removeEventListener('touchcancel', watchTouches);
	}
}

el.addEventListener('touchstart', watchTouches);

function touchMove(e) {
	if (e.touches.length === 2) {
		let mp_init = midpoint(initial_touches);
		let mp_curr = midpoint(e.touches);
		gesture = {
			scale: distance(e.touches) / distance(initial_touches),
			rotation: angle(e.touches) - angle(initial_touches),
			translation: { 
				x: mp_curr.x - mp_init.x, 
				y: mp_curr.y - mp_init.y
			},
			origin: mp_init
		};
		doGesture(gesture);
		e.preventDefault();
	}
}

Safari mobile: touch or gesture events?

Safari mobile (iOS and iPadOS) is the only browser that has support for both GestureEvent and TouchEvent, so which one should we choose for handling two-finger gestures?

On the one hand, enhancements Safari applies to GestureEvents makes them feel smoother; on the other hand, TouchEvents afford capturing the translation aspect of the gesture. We can't have both… can we?

Surprisingly, we can. Safari's implementation of TouchEvent contains the same scale and rotation properties as the equivalent GestureEvent, if we ever want to use the browser's, rather than our own manually computed, values.

A check for the existence of the two interfaces lets us restrict gesture events to desktop Safari:

/*
	Only attach GestureEvent listeners on macOS Safari.
 */
if (window.GestureEvent !== undefined && window.TouchEvent === undefined) {
	container.addEventListener('gesturestart', …);
	container.addEventListener('gesturechange', …);
	container.addEventListener('gestureend', …);
}

Applying the transformation

The final piece of the puzzle has us actually applying the transformation to an element. We we talk about transforming elements on a web page, we generally mean either an HTML or a SVG element. The techniques are similar, but the two languages diverge in some aspects.

From gesture to DOMMatrix

We can express the gesture as a transformation matrix, which uses the DOMMatrix interface:

function gestureToMatrix(gesture) {
	return new DOMMatrix()
		.translate(gesture.translation.x || 0, gesture.translation.y || 0)
		.rotate(gesture.rotation || 0)
		.scale(gesture.scale || 1);
}

To apply the DOM matrix to an HTML element, we simply add it to the element's style on the transform property. On SVG elements we can similarly set the element's transform attribute:

function applyMatrix(el, matrix) {
	if (el instanceof HTMLElement) {
		el.style.transform = matrix;
		return;
	}
	if (el instanceof SVGElement) {
		el.setAttribute('transform', matrix);
		return;
	}
	throw new Error('Expected HTML or SVG element');
}

Applying the gesture origin

The origin of the transformation for an element can be configured via the transform-origin CSS property or its equivalent SVG attribute. But we can actually factor it right into our transformation. The CSS Transforms Module Level 1 states:

The transformation matrix is computed from the transform and transform-origin properties as follows:

Start with the identity matrix.

Translate by the computed X and Y of transform-origin.

Multiply by each of the transform functions in transform property from left to right.

Translate by the negated computed X and Y values of transform-origin.

We can update the gestureToMatrix() function to reference an origin:

function gestureToMatrix(gesture, origin) {
	return new DOMMatrix()
		.translate(origin.x, origin.y)
		.translate(gesture.translation.x || 0, gesture.translation.y || 0)
		.rotate(gesture.rotation || 0)
		.scale(gesture.scale || 1)
		.translate(-origin.x, -origin.y);
}

You may be wondering why we are sending in origin as a second argument to the gestureToMatrix() function instead of just reading it off the gesture object. The reason for this is that the origin of the transformation is fixed at the midpoint of the initial touchpoints.

The origin doesn't change with each doGesture(). We compute it once, at the beginning of the gesture.

For HTML elements, we need to express the origin in relation to the element itself, so we read the element's bounding client rectangle. On the other hand, transformations to a SVG element relate to the element's nearest <svg> container, which establishes its coordinate system. The container's getScreenCTM() returns the matrix that maps from its coordinate system to screen coordinates, so we use its inverse() to express the transformation origin in terms of <svg> coordinates.

The unified getOrigin() function below works for both HTML and SVG elements:

function getOrigin(el, gesture) {
	if (el instanceof HTMLElement) {
		let rect = el.getBoundingClientRect();
		return {
			x: gesture.origin.x - rect.x,
			y: gesture.origin.y - rect.y
		}
	}
	if (el instanceof SVGElement) {
		let matrix = el.ownerSVGElement.getScreenCTM().inverse();
		let pt = new DOMPoint(gesture.origin.x, gesture.origin.y); 
		return pt.matrixTransform(matrix);
	}
	throw new Error('Expected HTML or SVG element');
};

For transforms to work correctly on HTML elements, we need to jump through a couple of more hoops:

Set the element's origin to the top-left corner with transform-origin: 0 0. The default is the object's center at 50% 50%.
Clear the element's transform at the beginning of each gesture, before reading its getBoundingClientRect(), to obtain the origin in relation to the original, untransformed position of the element.

These concerns are factored into the final solution below.

Putting it all together

Here's the code to apply the transformation matrix to the object (either HTML or SVG) on the startGesture, doGesture and endGesture callbacks.

Notice how we hold onto the object's initial matrix in init_m to multiply into the current matrix at every step of the gesture.


/*
	Older versions of Safari expose transformation matrices 
	on the `WebKitCSSMatrix` interface instead of `DOMMatrix`
 */
if (!window.DOMMatrix) {
	if (window.WebKitCSSMatrix) {
		window.DOMMatrix = window.WebKitCSSMatrix;
	} else {
		throw new Error("Couldn't find a DOM Matrix implementation");
	}
}

let origin;
let init_m = new DOMMatrix();
let el = document.querySelector('#target');

/*
	HTML elements have their `transform-origin` 
	set to '50% 50%' by default, we need to 
	reset it to the top-left corner.
 */
if (el instanceof HTMLElement) {
	el.style.transformOrigin = '0 0';
}

function startGesture(gesture) {
	if (el instanceof HTMLElement) {
		/*
			Clear the element's transform so we can 
			measure its original position wrt. the screen.

			(We don't need to restore it because it gets 
			overwritten by `applyMatrix()` anyways.)
		 */
		el.style.transform = '';
	}
	origin = getOrigin(el, gesture);
	applyMatrix(el, gestureToMatrix(gesture, origin).multiply(init_m));
}

function doGesture(gesture) {
	applyMatrix(el, gestureToMatrix(gesture, origin).multiply(init_m));
};

function endGesture(gesture) {
	init_m = gestureToMatrix(gesture, origin).multiply(init_m);
	applyMatrix(el, init_m);
};

Test this code out in these demos:

Since browsers on touchscreen-enabled devices implement several default behaviors for user gestures, any tap on the screen is under scrutiny: will it be part of a double-tap? does the user want to initiate a scroll, or follow the hyperlink underneath the touchpoint?

Disabling some of these default behaviors disambiguates taps. If we don't need double-tap-to-zoom gesture, the browser can make taps work like clicks without introducing artificial delays.

This is the general idea behind the touch-action CSS property. It instructs the browser to only apply some of its default behaviors when the user peforms one- or two-finger gestures: one-finger scrolling, pinch-zooming, or the double-tap to zoom behavior.

Depending on the exact needs of our implementation, we might apply touch-action: pan-x pan-y (which tells the browser to apply one-finger scrolling while ignoring all other gestures), or even touch-action: none to our container, in which case the responsibility is ours to implement all touch interactions. As a rule of thumb for touch-action, only disable the browser behaviors you plan to replace with custom gestures.

Some applications may benefit from a bit more nuance. For example, as gestures tend to be imprecise, we might impose thresholds that the various components of the transformation must reach to be considered intentional. Alternatively, we might tease out, and apply, only the most prominent component of the transformation, while ignoring the rest.

I hope this article has made the basic approach clear enough that these refinements can be neatly layered on top of it. You may find some pointers in the Questions & Answers section.

Conclusion

In this article we've looked at how we can treat DOM GestureEvent, WheelEvent, and TouchEvent uniformly to add support for two-finger gestures to web pages with some pretty good results across a variety of devices.

Some quick links:

This supplemental material is also published on GitHub in the danburzo/ok-zoomer repository.

Questions & Answers

How do I find the element's current scale?

To know the element's scale at any given moment, we need to either:

keep track of all the gestures we've applied and accumulate the scales in a variable, or
somehow extract the scale from the element's current transformation matrix.

The DOMMatrix interface doesn't have a method to retrieve individual components such as scale, translation, or rotation from a matrix, so we have to implement it ourselves.

To that end we can use the algorithm described in Spencer W. Thomas's article Decomposing a matrix into simple transformations, published in Graphics Gems II (1991). A pseudo-code version is published in the CSS Transforms specification, and a C implementation is available on GitHub.

The algorithm handles cases that don't apply to our situation — non-uniform scaling, skewing, etc. — so if we're only interested in extracting the uniform scale, we can get away with a one-liner:

const getScaleFromMatrix = matrix => Math.hypot(matrix.a, matrix.b);

And if you are interested in the general method, you can find some JavaScript implementations on GitHub.

Knowing the current scale is useful in a variety of cases:

Zooming to a specific scale. To produce an absolute scale, such as 50% or 400%, we can express it as relative to the current scale and create a gesture for it:

let current_scale = getScaleFromMatrix(current_transform_matrix);
let gesture = {
	scale: 0.5 / current_scale, // 50% scale
	// …
};
// apply gesture

Limiting the zoom level to a minimum/maximum. Similarly to zooming to an absolute scale, we can clamp our scale to a minimum and maximum. The function below limits the scale in a gesture so that the resulting scale is in the 25–400% interval:

function clampScale(gesture) {
	let s = getScaleFromMatrix(m);
	let proposed_scale = gesture.scale * s;
	if (proposed_scale > 4 || proposed_scale < 0.25) {
		return {
			...gesture,
			scale: Math.max(0.25, Math.min(4, proposed_scale)) / s
		};
	}
	return gesture;
}

You can see both these examples in action in Demo: Combined gestures and zoom buttons on an HTML element.

Revisions

Nov 22, 2020: Published a first draft of this article on dev.to.

Nov 15, 2021: Updated the Safari gesture events section to note that Safari 15 now also produces wheel events for pinch-zoom gestures, in line with the other major browsers, as well as to point out the double-gestureend bug.

Jan 10, 2022: Fixed some typos, improved wheel-to-gesture code, and added a Questions & Answers section.

May 19, 2022: Fixed the SVG case in applyMatrix() for Chrome, which doesn't currently support a DOMMatrix argument to SVGTransformList.createSVGTransformFromMatrix(). (Chromium#835431)

Thanks to Arne, Stephane and Sam for helping improve this article.

On some features in Safari 15

2021-09-29T00:00:00Z

A new major version of Safari was pitched back in June at the Apple WWDC 2021 event. In the Design for Safari 15 (33min video, transcript available), Jen Simmons and Myles C. Maxfield walk us through some of the biggest changes we could expect for the web platform.

Last week Safari 15 was officially released as part of iOS/iPadOS 15. It was also included in a recent update to macOS Big Sur, although the release notes hint that it was initially planned for macOS Monterey.

Now that I've had the chance to play around with the new version, here are some personal highlights from the release notes.

More ways to specify colors

Safari 15 is the first browser to support the new color syntaxes defined in the CSS Color Level 4 spec.

HSL, and its close relative HSV, rework the RGB color model (basically squishing the RGB cube into a cylinder) to separate colors into more intuitive dimensions. For a long time, hsl() has been the only alternative to rgb() for specifying colors, and is unquestionably an improvement: it's very hard to imagine a RGB color by looking at the R/G/B components, and it's impractical for picking colors. By comparison, you can sort of imagine the attributes of a color just by reading its H/S/L components — what hue it has and how colorful, and light, it is — and it's easier to match a target color by adjusting Hue, Saturation, and Lightness sliders. (You can try this old-school color matching game in RGB vs. HSL mode to see the difference.)

The HWB color space makes picking colors even more intuitive: provide a hue, and optionally mix in some white and some black to obtain a color. In CSS it's available under the hwb() syntax.

HSL, HSV, and HWB all use attributes that are easier to reason about, but they're not really aligned to how we perceive colors. HSL has its drawbacks and so does HSV and, by extension, so does HWB. The CIELAB color space is much more perceptually uniform and now we can use it in CSS, with the lab() and lch() forms.

Finally, the color() function notation, which debuted in Safari 10.1 with support for the srgb and display-p3 predefined color spaces, is supplemented in Safari 15 with a few more:

a98-rgb, the compatible-with but not, legally speaking, the actual Adobe RGB (1998) color space;
prophoto-rgb, the ProPhoto RGB color space;
rec2020, the Rec. 2020 color space;
xyz, the CIE XYZ color space with a D50 white point.

A redesigned color picker

Safari 15 on mobile comes with redesigned form controls, the most spectacular of which is the color picker. It now includes three separate selection modes:

the swatches panel from the previous version;
a hue/lightness spectrum for picking fully-saturated colors;
red/green/blue sliders and a hex input.

The three panels in the mobile Safari 15 color picker.

Other features include the ability to save colors for reuse, and an eyedropper to sample colors from the screen. Sampling a color switches the hex input to display-p3, which sort of makes sense (after all, the screen is able to render display-p3 colors) but on the other hand there's no concept of display-p3 hex code in CSS, which may confuse folks.

Since <input type='color'> only supports six-digit hex values, an opacity slider is not included in the picker like in native apps. On the other hand, one cool feature adopted from macOS is the ability to drag & drop one color well atop another to apply the value:

A built-in pull-to-refresh gesture

Safari 15 introduces a built-in pull-to-refresh gesture on mobile that's pretty handy.

I see it as especially beneficial to progressive web apps, where you don't have a way to refresh the page unless you implement a custom action. However, at the moment of writing, the gesture does not carry over to Progressive Web Apps.

It also seems that you can't disable the gesture using the overscroll-behavior CSS property, as it's not currently implemented (WebKit#176454). Websites that implement their own similar gesture may suffer from a jarring double-refresh effect. If that's the case, the only course of action is to disable the custom behavior. Since overscroll-behavior-y is the most likely vehicle for preventing the built-in gesture when it becomes possible, you can use this JavaScript snippet to target problematic browser versions:

/*
	Feature-detect Safari versions 
	with an unpreventable pull-to-refresh gesture.

	How it works: 

	Safari 15 introduced support for the `xyz` color space,
	while simultaneously being the last major browser engine 
	lacking support for `overscroll-behavior`.
 */
const isSafariWithUnstoppablePullRefresh = 
	window.CSS && 
	CSS.supports &&
	CSS.supports('(color: color(xyz))') && 
	!CSS.supports('(overscroll-behavior-y: contain)') && 
	window.TouchEvent && 
	!navigator.standalone;

if (!isSafariWithUnstoppablePullRefresh) {
	// initialize custom pull-to-refresh gesture
}

The `theme-color` HTML meta tag

Across platforms, Safari 15 is using the theme-color meta tag to tint the browser UI.

What I found surprising is the feature is not opt-in. In the absence of this meta tag, Safari will try to infer a tint for the top bar, and the color it chooses may not always be appropriate. It may be useful to include this meta tag to your HTML boilerplate, along with the other things that go in <head>, to avoid weird color combos.

Manuel Matuzović explores what you can and can't do with theme-color in this CSS-Tricks article.

A new tab bar

Safari debuted with a radical interface redesign that merged the old address bar and the navigation bar from previous versions into a single, floating URL bar at the bottom of the screen.

The change was met with both enthusiasm and reluctance. One concern with the floating tab bar was that it may stand in the way of things on the page. It was acknowledged and planned for: a bullet point under the CSS section in the release notes reads adjusted environment variable calculations where appropriate to adjust for the safe area of the new iOS design. As documented by Luke Channings, Safari 15 Beta did afford a combination of height: 100vh and env(safe-area-inset-bottom) to place a toolbar at the bottom of the screen without risking it being hidden behind the URL bar.

The final Safari 15 release back-pedalled into more familiar ground, with a tamer combined bottom bar, and an option to bring back the old top-anchored address bar. After a week of using it, the new UI seems to have mostly faded out of attention, and I appreciate the ease of switching tabs with a horizontal swipe. And although the Aa menu is becoming a bit of a kitchen sink cabinet, all in all I feel like this is a step in the right direction.

What about the changes to env()? As seen in this demo, they seem to have been reverted for the case we were interested in: env(safe-area-inset-bottom) is 0 when floating toolbar is shown, and it still obstructs the bottom part of the page.

For reference: Here's a browser test that shows the computed value of available env() properties, as well as 100vh and the -webkit-fill-available height.

The way out seems to be the new viewport units, in particular dvh (dynamic viewport height). Bramus has an explainer on these units. (Nov 24, 2021 update: Safari TP 135 has just added support for them).

How it's made: Watch/Star/Fork

2021-09-12T09:01:00Z

I thought I'd write a bit about my awkward but workable flow for adding several dozens of links to each Watch/Star/Fork edition, and my usage of bookmarks in general.

From many inboxes to one

So, out of the two available types of people, I am a bookmark person. The only time I have more than a dozen tabs open is while I research something, and even that dissipates as quickly as I ⌘-clicked my way there.

Firefox has the best ergonomics for bookmark people, so that's where I hang out most. Whenever I see something interesting and/or potentially useful, I drag & drop the tab onto my bookmarks toolbar, which has little bins for sorting everything neatly. If it's something I feel belongs here, I drop it in the wsf folder.

Before, if an online service had some sort of star/like/favorite/upvote function that gets saved and attached to my profile, I'd use it to bookmark things I wanted to get back to later. But with so many inboxes, I'd rarely actually revisit them, so I've started to direct everything towards actual bookmarks.

To get the data out of the various places in the weird de facto standard bookmark format, I employed a variety of tools, some of which — hred and nbf — I wrote for the purpose. The nbf repository page collects a few recipes for things like GitHub stars or NetNewsWire favorites.

As a grand final gesture I tried removing my historical "bookmarks" from these services, with whichever method seemed quicker. I mostly succeeded, save for a few minor incidents involving GitHub stars (where a kind person from GitHub support fixed a lingering star count) and unreachable social media likes. Oops!

I now use temporary social media likes to show my interest & appreciation, but once a week I'll go through them, bookmark any useful links, and then reset everything. (I know there's the separate Bookmarks feature, but I prefer to send a little signal of gratitude.) And with the new system in place, my GitHub stars page is always empty.

Safari's Reading List as syncing tool

To sync bookmarks between my phone and my laptop I use, out of all the possible technology available in the year 2021, Safari's Reading List. A bit like in this funny, insightful tweet I saw on my timeline today:

my toxic designer trait is using the rectangle tool to make boxes in order to measure spacing between objects instead of using any sort of built-in measuring/ruler/guide tool the hardworking developers have made for me — @sievish on Sep 10, 2021

The rationale is simple: all apps on my phone that deal with web pages (Safari, NetNewsWire, Are.na, etc.) have access, directly or indirectly, to the Add to reading list action from the iOS sharing panel, so it's just a convenient, mostly reliable way to add things to a single inbox that then shows up on my laptop without me needing to configure or install anything extra.

One snag I have with this setup is that Safari sometimes decides, out of the blue and without indication, to stop saving web pages to the Reading List. I haven't traced the reason behind it, and it's been an issue for a number of years now, but it usually fixes itself in a couple of days (not exactly sure how), and I'm not too precious about the odd bookmark going missing here and there. But just so you know.

From macOS Safari to Firefox is a short trip: nowadays Safari provides an Export bookmarks function that includes the Reading List, and before that I used to maintain a little tool to extract the bookmarks from Safari's Bookmarks.plist file.

From bookmark to Markdown

The last leg of the journey from browser tabs to blog post is turning the wsf bookmarks folder into the Markdown that powers this site.

As I mentioned earlier, Firefox has great affordances around bookmarks. One of them is being able to Right-click → Copy or drag & drop entire folders. Pasting a folder into Clipboard inspector, it transpires that Firefox puts into the clipboard, as the text/html entry, actual, honest-to-goodness HTML (in the Netscape Bookmark Format), similar to what you'd get if you used the Export bookmarks to HTML function.

On the other hand, there several online one-page tools to convert HTML to Markdown; I've settled on Turndown, which works nicely with the default settings. There's a small hoop to jump through: when you paste a Firefox folder into Turndown's <textarea> element, it gets the text/plain clipboard entry. I've submitted a pull request to grab the text/html data when it exists, but in the meantime I use Clipboard Inspector's Copy as plain text function.

One thing I still do by hand is add the authors' names next to each link, but I'm glad I get at least a head start on all of the title/link pairs.

Use code to explore and change JavaScript files

2021-09-08T00:00:00Z

A while back I wrote, as an exercise in minimalism, the nano-i18n library for localizing strings. You write internationalized strings with a template tag:

import { t } from 'nano-i18n';
const name = 'Dan';
console.log(t`Hello, ${name}!`);

It also provides a hook for missing translations, so you can log them to the browser console, or collect them in one place so that they're easier to find when you want to translate them. Pretty straightforward stuff.

import { t, config } from 'nano-i18n';
config({
	log: (msg, key) => console.warn(`Missing: "${key}"`);
});

const name = 'Dan';
console.log(t`Hello, ${name}!`);

// => Missing: "Hello, {}!"

This way of collecting strings has its disadvantages. Someone needs to go through all the possible states of the interface to trigger aforementioned hook. Worse, when you redo bits of the interface, you need the presence of mind to remember to clean up the strings that are no longer in use.

Instead, let's see how we can automate our way out of this predicament, and extract from a JavaScript codebase all string literals tagged with the t template with a script.

For answering basic questions about a codebase, or for simple code alterations, I would normally first attempt a well-crafted regular expression. I'll paste it into Sublime Text's Search & Replace interface, or ripgrep (look at the --only-matching and --replace options), or some combination standard command-line tools I'll never remember unless I have it written down somewhere.

This is not one of those times. The t tag can interpolate basically any JavaScript expression within the translation, so it's impossible to deploy a regex to match all the patterns that might occur in the typical codebase. We need a tool that understands the syntax we're working with.

A short survey of the tools available

There are quite a few options for parsing JavaScript: there's esprima, acorn, and @babel/parser. These parsers produce an Abstract Syntax Tree (AST) from a JavaScript string, either adhering the ESTree format, or to something fairly similar.

Further along, recast helps you alter the AST, and then remake it into a string. A combination of astring and astravel serve a similar purpose. But how do you know how to alter the AST? AST Explorer lets you type in sample JavaScript code and shows you the resulting tree as an interactive, navigable JSON.

Finally, jscodeshift is a command-line tool written in JavaScript that uses recast and helps with bits of admin, such as:

picking up on your Babel configuration if you have one; this is handy if you're using plugins for more exotic syntax.
running things in parallel to speed up processing a large codebase.

It's used for a variety of purposes, such as keeping your React components up to date with the occasional changes in React's API.

You could start with the tools from any level on the abstraction ladder, and build up from there. In this particular case, I'd rather not get bogged down in unrelated complexities & gotchas and focus on the unique aspects of the task at hand. With a few tweaks here and there, we can adapt jscodeshift to not modify JavaScript files, but instead gather statistics on them, so that's going to be the tool of choice today.

Analyzing code with `jscodeshift`

Install jscodeshift from npm and add a script to your package.json:

{
	"scripts": {
		"gather": "node node_modules/.bin/jscodeshift --help"
	}
}

Running the script with npm run gather just displays its help information for now, but I wanted to get out of the way the non-standard way of invoking it. You don't usually need to run Node.js CLI tools with node, but this form is necessary at the time of writing to work around a quirk in jscodeshift.

To actually do something, the tool takes a JavaScript file containing the transform we want to perform on our JavaScript files, under the --transform command-line argument. It also needs a folder in which to look for files, so a proper invocation looks like this (with the node part omitted):

jscodeshift --transform=gather-translatables.js js/

A word of caution: jscodeshift has the ability to overwrite your JavaScript files. Make sure you use a version control system such as Git on the codebase you're working with, and that you don't have any pending changes to commit, before messing around with transforms.

The transform is listed below. The API looks a bit like jQuery, with chained methods on a collection of AST nodes.

Technically this is the point where you'd modify the AST to write back to the file, the task at which jscodeshift excels. We only want to gather some statistics, so we don't return anything from the transform function — this instructs jscodeshift to keep the source files intact.

Instead we use the report function that writes its argument to the console output.

gather-translatables.js

/*
	The jscodeshift transform
	-------------------------
 */
module.exports = (fileInfo, api) => {
	const { jscodeshift, report } = api;
	jscodeshift(fileInfo.source)
		.find(jscodeshift.TaggedTemplateExpression)
		.filter(isTranslationTag)
		.forEach(path => {
			const key = toTranslationKey(path);
			report('\n' + key);
		});
};

/*
	Matches template literals tagged with "t":

		t`Hello, world!`
 */
function isTranslationTag(path) {
	const { type, name } = path.node.tag;
	return type === 'Identifier' && name === 't';
}

/*
	Converts a tagged template literal 
	to a `nano-i18n` translation key:

		t`Hello, ${stranger}!`

	Becomes:

		'Hello, ${0}!'
 */
function toTranslationKey(path) {
	const { quasis } = path.node.quasi;
	return quasis
		.map((q, idx) => {
			return q.value.raw + (q.tail ? '' : `{${idx}}`);
		})
		.join('');
}

To see what I need to match and how to process the AST in the transform function, I've looked at the structure of a typical tagged template literal in AST Explorer, with this sample JavaScript code:

t`Hello, ${stranger}!`;

AST Explorer output

This is a simplified JSON output with just the essential properties for each node.

{
	"type": "TaggedTemplateExpression",
	"tag": {
		"type": "Identifier",
		"name": "t"
	},
	"quasi": {
		"type": "TemplateLiteral",
		"expressions": [
			{
				"type": "Identifier",
				"name": "stranger"
			}
		],
		"quasis": [
			{
				"type": "TemplateElement",
				"value": {
					"raw": "Hello, ",
					"cooked": "Hello, "
				},
				"tail": false
			},
			{
				"type": "TemplateElement",
				"value": {
					"raw": "!",
					"cooked": "!"
				},
				"tail": true
			}
		]
	}
}

The transform does what we want it to do — it extracts all the translation keys used in any JavaScript file from the the js/ folder. The AST processing part is done.

Let's turn our attention to how to shape this raw data we've just produced into something usable. Invoking the gather script, we can see that the output of report() is peppered with miscellaneous output from the tool, some of it colored. To clean up the output, we can use jscodeshift's --no-color and --silent flags, which suppress the color and the informational output, respectively.

Updated gather script in package.json

{
	"scripts": {
		"gather": "node node_modules/.bin/jscodeshift --no-color --silent --transform=gather-translatables.js js/"
	}
}

Running the script again produces a cleaner output as a series of items with the following structure:

 REP js/path/to/hello.js
Hello, ${0}!

This form is not ideal, but the data is good enough to pipe into a separate script to achieve its final form. Here's a small Node.js script that does two things:

the first part 'slurps' all the content from stdin (Sindre Sorhus has it packaged as get-stdin);
that content is then split into a flat list of unique, sorted translation keys.

sort-gathered.js

const { stdin } = process;
stdin.setEncoding('utf8');

/*
	Accumulate the input from `stdin`
	into the `content` string.
 */
let content = '';
stdin.on('readable', () => {
	let chunk;
	while ((chunk = stdin.read()) !== null) {
		content += chunk;
	}
});

/*
	When finished, process `content`.
 */
stdin.on('end', function analyze() {
	const items = content.split(/\n? REP .*\n/);
	/*
		Unique keys, sorted alphabetically
	 */
	const unique = [...new Set(items)].sort();
	console.log(unique);
});

And here's the final gather script, piped into sort-gathered.js:

{
	"scripts": {
		"gather": "node node_modules/.bin/jscodeshift --no-color --silent --transform=gather-translatables.js js/ | node sort-gathered.js"
	}
}

P.S. Nathan pointed out on social media that instead of piping into the second sort-gathered.js script, we could use jscodeshift's undocumented JavaScript API.

# Changing JavaScript files

Finally, let's use jscodeshift for the purpose for which it has been designed: to actually change JavaScript files.

I've recently switched culori to use native ES modules in Node.js for its inaugural 1.x release and realized — by carefully reading the documentation, haha just kidding, I promptly got a couple of hundred error messages — that all the imports need to use the full path, including the .js extension.

// From this:
import { interpolate } from '../interpolate';

// …to this:
import { interpolate } from '../interpolate.js';

Normally at this point I would despair at the prospect of changing hundreds of declarations by hand, but it was effortless with a transform:

imports-add-ext.js

/*
	jscodeshift transform: adds the '.js' extension
	to all import declarations with relative specifiers:

	From './file' to './file.js', and
	from '../file' to '../file.js'.
 */
module.exports = function (fileInfo, api) {
	let j = api.jscodeshift;
	return j(fileInfo.source)
		.find(j.ImportDeclaration)
		.forEach(path => {
			let { source } = path.node;
			if (source.value.match(/^\.{1,2}\//)) {
				source.value += '.js';
			}
		})
		.toSource();
}

node node_modules/.bin/jscodeshift --transform=imports-add-ext.js src/ test/

The beauty of writing your own transforms is they only have to be as comprehensive as the task requires. In fact, after changing the import declarations I realized I needed to address the export declarations as well. Eh.

How I digitize books

2021-07-09T00:00:00Z

One of my current passions is to publish interesting public domain Romanian books on llll.ro. The website doesn't just collect texts already available the web: the idea is to work with the primary sources to provide transcriptions that are faithful to the originals.

In its journey from paper to HTML, the material goes through a few steps; some are automated, others still rely on manual work. To ensure quality the worflow still needs a final pair of eyes, but we want as little grunt work as possible. This article describes the workflow on which I've settled (for now) to bring books online.

In short, the process entails:

photographing the pages;
performing Optical Character Recognition (OCR) on them;
cleaning up and formatting the text.

Image acquisition

The first step is to capture clear images of each page. While OCR can work on plain camera photographs, a bit of pre-processing can get you more accurate results. Books tend to have hundreds of pages, so every variation in the ergonomics of this step has significant cumulative effects.

I use the (free) Scannable app on iOS to capture, crop, and perspective-correct the pages all in one go. When I'm happy with the crops, I use Send → Share → AirDrop to transfer the set of images to my computer — just make sure the selected format is PNG, not PDF.

A sample image produced by Scannable (see larger size).

Optical character recognition

Next, we put the images to good use. For OCR to be truly useful, it has to be very accurate; otherwise, it's quicker and less frustrating to transcribe everything by hand than to fix an Unicode character soup.

For the kinds of texts I'm digitizing — Romanian, possibly using obsolete othography and diacritical marks — the offline OCR tools I've tested do a lukewarm job. Online services, for the most part, aren't much better, with one exception: Google's Vision API provides near-flawless results. It's a paid, but cheap, service: at the time of writing, the first 1000 images are free, after which you pay around $1.5 per 1000 images.

I wrote a little web tool called Vizor to interact with the Vision API. After you prepare an API key (remember to enable billing for it to work!) you simply drag-and-drop a set of images onto it and get plain text in return.

The API's JSON response the text is segmented in a hierarchy of Pages, Blocks, Paragraphs, Words and Symbols. Vizor stitches them together according to your needs: you can either preserve the line breaks (Verse), or obtain nice, flowing paragraphs (Prose).

Cleaning up the text

I bring the plain text into Sublime Text and run it through a series of checks I've written down. These are a series of regular expressions (regexes) that I plop into Sublime Text's search field — be sure to enable the regular expression search, and the case (in)sensitivity as needed — to bring out possible problems: the wrong diacritical marks, characters outside of the expected ranges, and so on.

Then come the manual bits. I mark up the headings, lists, and any bold/italic sections in Markdown syntax. To spell check, I grab the text and paste it into the Pages app, and use its spellchecking tools to identify any typos. The last pass involves eyeballing the entire text to identify any issues I missed with the automated checks. To do this, I produce a PDF or EPUB file from the HTML using percollate:

# Produce a PDF file:
percollate pdf /path/to/doc.html

# Produce an EPUB file:
percollate epub /path/to/doc.html

I then load the file on my iPad and skim it for anything out of the ordinary. Any error I spot I highlight or otherwise annotate right inside the app, so they're easy to review at the end.

This process allows me to produce high-quality hypertext out of a moderately-sized book in a few evenings' work, with proofreading taking the bulk of the time.

My favorite records from 2020

2020-12-24T00:00:00Z

This year has seen a ton of new releases from musicians both familiar and unknown-to-me. I haven't got around to giving a proper listen to many albums I had on my radar, but here's a sampler of what I liked, or found interesting, in 2020.

And a few individual tracks:

Ariel Sharratt & Mathias Kom — The Rich Stuff
Daniel Avery — Lone Swordsman
Dope Lemon — Streets of your Town
Doves — Carousels
Jon Hopkins — Dawn Chorus
Thomas Feiner — Guide for the Perplexed and Encounters at the End of the World
Tindersticks — You'll Have to Scream Louder
Yasmine Hamdan — Choubi (2017)
Francis Bebey — Sanza Tristesse (1982–1984)

Timeline of favorite records: 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025.

Lists from around the www:

R.I.P. Harold Budd (1936–2020)

A little npm head-scratcher

2020-11-20T00:00:00Z

The other day I ran into an interesting puzzle, which was fun to sort out, and I learned enough in the process that I thought I should write it down.

The setup

A JavaScript project I maintain has the following file structure, abridged:

src/
  util/
     slurp.js
  cli-opts.js
test/
  cli-opts.test.js
index.js

Two tools I normally use for JavaScript projects are tape for tests and eslint for linting, and these I ultimately ran as:

tape test/**/*.test.js
eslint {src,test}/**/*.js *.js

...but they're actually stored as npm scripts in my package.json file:

{
	"scripts": {
		"test": "tape test/**/*.test.js",
		"lint": "eslint {src,test}/**/*.js *.js"
	}
}

...and then invoked with npm run test and npm run lint respectively.

These commands worked out great. So great that I added them to a pre-commit hook, and ran them in GitHub Actions, to make sure the code is top-shelf quality.

Then one code change, which passed the pre-commit hooks, suddenly blew up the GitHub action: npm run lint had found two linting errors in the src/cli-opts.js file.

Huh. I fire up my terminal, on which I've been running the zsh shell for the last few years, and execute npm run lint, as one does.

No errors. What's going on?

In the off-chance you want to figure it out yourself (which I imagine is no fun without the actual setup with which to play around), stop here before reading the explanation below.

The explanation

What's going on is shells.

Remember I casually mentioned I run zsh? It turns out this matters. Bringing up the manual for npm run revealed this piece of hitherto unknown information:

The actual shell your script is run within is platform dependent. By default, on Unix-like systems it is the /bin/sh command, on Windows it is the cmd.exe. The actual shell referred to by /bin/sh also depends on the system.

Wait a second, you mean to tell me I've been running npm scripts with GNU bash, version 3.2.57(1)-release (x86_64-apple-darwin19) all along?!

One aspect for which the choice of shell is important is that different shells have different glob expansion rules.

zsh supports recursive expansion of the **/ pattern, so that src/**/*.js matches both src/util/slurp.js and src/cli-opts.js while bash 3.2 only matches the former. It's only in version 4 that bash gets a globstar option that allows recursive expansion, and even that might not be enabled by default.

Furthermore, when a glob pattern has no matching files, zsh throws an error. By default, bash outputs the glob pattern unchanged.

To see what the problem might be with these two pairs of diverging behaviors, here are the file structure and the glob patterns again, along with their expansion in zsh and bash:

src/
  util/
     slurp.js
  cli-opts.js
test/
  cli-opts.test.js
index.js

echo test/**/*.test.js
# zsh:
test/cli-opts.test.js
# bash 3.2:
test/**/*.test.js

echo {src,test}/**/*.test.js *.js
# zsh:
src/util/slurp.js
src/cli-opts.js
index.js
test/cli-opts.test.js

# bash 3.2:
src/util/slurp.js
index.js
test/**/*.test.js

Now, if we look at tape and eslint's respective package.json files, we'll see both use the glob package, which lets them accept glob patterns as operands, and to support the ** globstar pattern in their expansion.

Bash's behavior on globs it was unable to match, that is to forward them unchanged as operands to the tape and eslint commands, is (counterintuitively!) the key thing that held the whole charade together, making bash work almost like zsh.

But not entirely. If you examine the expansions above closely, you may notice that in bash, we're not linting one set of files: anything directly under the src/ folder. The linting command had quietly broke the moment I introduced the src/util subfolder, for reasons I'll leave as an exercise to the reader :-).

This subtle detail is why, for the most part, I hadn't realized anything was wrong with my setup; all tests were run and most files were linted. It was only when a recent mistake in src/cli-opts.js was caught by GitHub Actions, but not locally, that the jig was up.

Why did the lint command work in GitHub Actions? I have not had the energy to look into it, but my guess is the particular Ubuntu image I'm using may have bash version 4 or newer as its /bin/sh, with the globstar option enabled.

The solution

The solution, as always, is to quote glob patterns to prevent their expansion in the shell, and have them delivered intact to the tape and eslint commands, which will in turn expand them consistently regardless of the particular shell they're running in.

package.json

{
	"scripts": {
		"test": "tape 'test/**/*.test.js'",
		"lint": "eslint '{src,test}/**/*.js' '*.js'"
	}
}

I hope you found this write-up illuminating!

Make PNG font samples with ImageMagick

2020-04-27T00:00:00Z

In this article we'll be poking around ImageMagick from the command-line to get it to make great looking PNG previews of sample text typeset in various fonts, like the one below.

As always with ImageMagick and other tinker-friendly tools, we'll accidentally learn a few other things along the way.

Note: I'm using the latest version of ImageMagick which, at the time of writing, is 7.0.10. ImageMagick 7 introduces a single magick command for everything; replace it with convert in the examples below in case you're using version 6 or earlier.

Writing one line of text

The quick brown fox jumps over the lazy dog and The five boxing wizards jump quickly are two well-known pangrams — compact phrases that use most of the letters from the Latin alphabet, an aspect which makes them excellent choices for previewing typefaces.

As our first quest, let's write the sentence The five boxing wizards jump quickly on a piece of PNG.

In ImageMagick, the -draw option allows us to paint all sorts of things onto an image — pixels, shapes, and text:

magick \
  -size 1000x200 \
  canvas:none \
  -pointsize 48 \
  -draw "text 50,50 'The five boxing wizards jump quickly.'" \
sample.png

In the command above we set up a transparent canvas (canvas:none) of 1000×200 pixels (the -size option); using a font size of 48 points we then write our phrase starting at the (50,50) coordinate. The result, shown below with a red border to discern the canvas bounds, is already promising:

Our first line of text.

To place the text in a more predictable place on the canvas, for example to keep it vertically aligned regardless of the font in use, handwritten coordinates won't cut it, especially if we aspire to run the command automatically for lots and lots of fonts. This is where the -gravity option comes in handy: with it, we can align the canvas and the text by their matching side. For example, -gravity West will place the text's left-hand side against the canvas's left-hand side:

magick \
  -size 1000x200 \
  canvas:none \
  -pointsize 48 \
  -gravity West \
  -draw "text 0,0 'The five boxing wizards jump quickly.'" \
sample-centered.png

The same text, now centered vertically.

Much better! Notice we've replaced the (50,50) coordinate pair with (0,0); we don't want the text to be offset at all from the edge of the image.

Alternatively, instead of trying to position the text on the canvas, we can make the canvas fit snuggly around the text with the -trim option:

magick \
  -size 1000x200 \
  canvas:none \
  -pointsize 48 \
  -gravity Center \
  -draw "text 0,0 'The five boxing wizards jump quickly.'" \
  -trim \
sample-trimmed.png

For best results, place the text smack in the middle of the canvas (-gravity Center), and make sure the canvas is large enough to fit the entire text with a variety of fonts. The canvas gets trimmed in the end, it doesn't hurt to start with considerable padding.

Using specific fonts

Up until now we've been drawing text with some Helvetica-or-similar font. But the whole point of the exercise was to make PNG previews for fonts, plural. The -font option takes a path to a font file (.ttf, .otf, etc.) to use for drawing all the text:

magick \
  -size 1000x200 \
  canvas:none \
  -font ./MyFont.otf
  -pointsize 48 \
  -gravity Center \
  -draw "text 0,0 'The five boxing wizards jump quickly.'" \
  -trim \
MyFont-sample.png

The -font option also (technically, sort of) allows you to specify the font by its name instead of pointing to a font file; but the available fonts are not always, as one would assume, the fonts installed on your your machine. Instead you're bound to the list you see when you run magick -list font; what it contains depends on your operating system. On macOS, you might find this script by Justin Searls useful for making ImageMagick aware of system fonts.

What's better than using a custom font? Using a whole bunch of custom fonts! In a folder full of .otf font files, we can generate PNG samples for them in bulk using a for-loop:

for font in *.otf; do \
magick \
  -size 1000x200 \
  canvas:none \
  -font ./$font \
  -pointsize 48 \
  -gravity Center \
  -draw "text 0,0 'The five boxing wizards jump quickly.'" \
  -trim \
"$font-sample.png"; done

The $font variable holding the path to the current font shows up twice in the command: as -font ./$font for writing text, and as part of the output filename, $font-sample.png.

This gets us nicely named, nicely trimmed, previews:

Samples in various fonts.

Making a GIF out of the images

I thought ffmpeg is a good tool to make an animated GIF that uses the PNGs as frames, but this Stack Overflow answer showed me a quicker solution with ImageMagick's convert utility:

magick convert \
  -delay 0 \
  -dispose Previous \
*.png fonts.gif

The -delay option sets how much each frame in the animation lasts, with 0 having the frames play as fast as possible. The -dispose Previous option clears the canvas after each frame, instead of overlaying frames on top of each other.

All the samples as one animated GIF.

A beautiful animated GIF where... the canvas is 1000×200 pixels in size and all the texts are centered?! As far as we know, every individual sample is trimmed to a different size!

Turns out that ImageMagick tags images it produces with metadata it can, and will, then use if the image file is further processed. The identify command lists out the metadata:

magick identify -verbose MyFont-sample.png

Here's an abridged version of the output:

Image: MyFont-sample.png
  Format: PNG (Portable Network Graphics)
  (...)
  Geometry: 738x45+0+0
  (...)
  Page geometry: 1000x200+130+76
  Origin geometry: +130+76

It now becomes clear that the -trim option we had used to generate the PNGs stores the position of the trimmed area on the original canvas as the Page geometry metadata. Flashback to all the words in the docs and the bit about +repage starts to make sense:

The page or virtual canvas information of the image is preserved allowing you to extract the result of the -trim operation from the image. Use a +repage to remove the virtual canvas page information if it is unwanted.

To remove the extraneous Page geometry metadata, the adjusted command is:

magick \
  -size 1000x200 \
  canvas:none \
  -font ./MyFont.otf \
  -pointsize 48 \
  -gravity Center \
  -draw "text 0,0 'The five boxing wizards jump quickly.'" \
  -trim \
  +repage \
MyFont-sample.png

Sure enough, the same(-ish) command to build the GIF:

magick convert \
  -delay 0 \
  -dispose Previous \
  -layers trim-bounds \
*.png fonts.gif

Now does what we'd expected it to do in the first place:

All the samples as one animated GIF, properly sized and aligned.

Not that it's in any way better, but, you know, for the sake of completeness. And yes, I cheated a smidge. I added in the -layers trim-bounds option, on the house, to spare you the disappointment of finding out what ImageMagick does by default when it encounters frames of different sizes. Let me just say the option enlarges the canvas so that all the frames fit entirely.

After this brief foray into GIF-making, let's get back to the subject at hand.

Writing more than one line of text

ImageMagick doesn't have any built-in mechanisms to lay out text on multiple lines, so we have to do it manually, line by line. The -draw routine becomes:

-draw " \
  text 50,64 'The five boxing' \
  text 50,128 'wizards jump' \
  text 50,192 'quickly.'" \

Here we devise a line height of 64 points, and place the lines of text at 64×1, 64×2, and so on. On the horizontal axis, we're not starting the text directly at the edge of the image, because the flourishes on some of the more decorated typefaces may get cut off. With a 50-point offset, we give the font ample space to do its thing, and we'll get rid of the excess later, using the -trim option.

The full command is presented below:

magick \
  -size 640x320 \
  canvas:none \
  -font ./MyFont.otf \
  -pointsize 48 \
  -draw " \
    text 50,64 'The five boxing' \
    text 50,128 'wizards jump' \
    text 50,192 'quickly.'" \
  -trim \
  +repage \
MyFont-sample.png

And produces images such as this one:

A multiline font sample.

But when put side by side, we notice the baselines don't align across images.

Font samples side by side.

If we put the trimmed images side by side, we can tell the baselines don't match. Ideally, we only want to trim the excess space on three of the edges, and leave the top edge as-is, so that lines begin at the 64-point mark regardless of the font.

There must be more than one way to achieve this, but one that I found straightforward is to add a pixel guard at the top, trim normally, then chop the pixel off:

magick \
  -size 640x320 \
  canvas:none \
  -font ./MyFont.otf \
  -pointsize 48 \
  -background none \
  -splice 0x1 \
  -draw " \
    text 50,64 'The five boxing' \
    text 50,128 'wizards jump' \
    text 50,192 'quickly.' \
    point 50,0" \
  -trim \
  -chop 0x1 \
  +repage \
MyFont-sample.png

Firstly, -splice 0x1 adds a transparent (by virtue of the previous -background none declaration) pixel row at the top of the image. Then -draw point 50,0 places a solid black pixel on that top row, which causes the subsequent -trim option to only crop transparent pixels along the other three edges. Finally, -chop 0x1 removes the row we added earlier. This makes the text in all images line up nicely.

Font samples side by side, properly aligned.

That's it! That's how you make PNG font samples with ImageMagick.

My favorite records from 2019

2020-01-03T00:00:00Z

As you can notice, 2019 had a bit of a work-in-progress vibe to it.

Top records:

Sharon Van Etten — Remind Me Tomorrow
The National — I Am Easy To Find
Vanessa Wagner — Inland / Inland Versions
Jacques Greene — Dawn Chorus

Other records of note:

Abul Mogard
Acid Arab — Jdid
Aldous Harding — Designer
Alex Cameron — Miami Memory
Altin Gün — Gece
Angel Olsen — All Mirrors
Bedouine — Bird Songs of a Killjoy
Beirut — Gallipoli
Blanck Mass — Animated Violence Mild
Blawan — Many Many Pings
Devendra Banhart — Ma
Fennesz — Agora
Floating Points — Crush
Helado Negro — This Is How You Smile
Holly Herndon — Proto
Jay-Jay Johanson — Kings Cross
Kangding Ray — Azores EP
Kastil
Kazu — Adult Baby
Lana del Rey — NFR!
Nick Cave & the Bad Seeds — Ghosteen
Nikveh
Rhye — Spirit
Slow Meadow — Happy Occident
Sun O)))) — Life Metal
Thom Yorke — Anima
Tigran Hamasyan — They Say Everything Stays The Same
Tool

Timeline of favorite records: 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025.

Prevent history navigation on horizontally-scrolling elements with CSS

2019-10-16T00:00:00Z

Behold a horizontally-scrolling element:

.reel {
	display: flex;
	overflow-x: scroll;
}

This pattern is particularly useful on mobile devices as an alternative to stacking for breaking a grid apart, but its utility is not limited to small screens. A horizontally-scrolling section can also become the basis of an image slideshow on desktop browsers.

When people use the trackpad for navigating horizontally (often, with a two-finger gesture), we get an unintended side-effect: the gesture coincides with navigating through the browser history. A two-finger swipe to the right triggers the browser Back action, while two fingers to the left triggers the Forward action. When you reach the edges as you scroll the container, you often accidentally navigate away from the page.

To prevent the navigation, we can use the overscroll-behavior CSS property. A value of none or contain will make sure the excess scroll does not ripple to the container's ancestors and, ultimately, the page:

.reel {
	display: flex;
	overflow-x: scroll;
	overscroll-behavior-x: contain;
}

Here's a demo highlighting the difference.

At the time of writing, this property is supported in Firefox ¹, Chrome ², and Edge, so most desktop users will benefit from the enhanced behavior.

For extra credit also opt into smooth, accelerated scrolling in mobile Safari with -webkit-overflow-scrolling: touch. While iOS / iPadOS 13 makes this the default, it's still a nice, ahem, touch for older versions.

Updates

March 26, 2022: The overscroll-behavior CSS property is now available for testing in Safari Technology Preview 142 (yay!)

August 7, 2022: But history navigation is explicitly allowed despite overscroll-behavior (sad tromobone) [WebKit#240183].

¹ There's a small issue in Firefox with the first swipe.

² I stumbled upon a peculiar combination that made Chrome ignore the declaration.

Prevent the need to zoom into inputs with CSS

2019-10-08T00:00:00Z

Adrian Roselli describes a quick, effective way to make HTML inputs inherit the styles of the page they’re on, rather than deriving their appearance from operating system conventions. The following (simplified) declaration makes the font match the input’s surroundings; in particular, it makes its font-size equivalent to 1em:

textarea,
input {
	font: inherit;
}

If you use mobile Safari, you’ve probably noticed that it sometimes zooms into inputs as you focus them, to make them easier to read and type into. This happens whenever an input uses text smaller than 16px, and it’s a sensible thing to do. However, in some cases, the effect is purely accidental: you get this barely zooming into an input because it happens to have a computed font size of 15px, or 14px, as inherited from its parent.

To proactively fix this, and spare the user a potentially jarring interaction, I got into the habit of throwing in an extra declaration in my default stylesheet:

button,
select,
textarea,
input {
	font-size: max(16px, 1em);
}

In browsers supporting the max() function — including, thankfully, Safari — it prevents the inherited font size of inputs from going below 16px, and avoids the zoom behavior.

Nice and easy!

Some notes:

This technique only applies to 100% zoom; starting from version 13, mobile Safari has zoom controls, and zooming out of the page understandably brings back the zoom into input thing.
One thing that’s still prevalent is using maximum-scale=1.0, or user-scalable=no in the viewport meta tag. Despite Safari ignoring them since iOS 10 to allow users to pinch-zoom regardless, they’re still bad for accesibility.

Making sense of units in CSS Media Queries (in the year 2019)

2019-09-29T00:00:00Z

As browsers are starting to ship parts of the Media Queries Level 5 spec, recent discussion on CSS media queries understandably revolves around using these new features to better adjust web pages to users' needs and preferences. In 2019, the old-school queries published in 2012 as a W3C Recommendation, and near-universally supported across browsers, seem to have been exhaustively dissected and discussed.

Still, I felt some aspects of how they work continued to elude me. In this article I set out to clarify them.

Quick recap: media queries are a mechanism in CSS and HTML (with additional hooks for JavaScript) which lets us test certain aspects of the browser and device that display our web page. These aspects are external to the page, and not (usually) influenced by the styles we apply to it.

There are many features we can test. I'm going to look at a tiny slice: the width and height media features, with their associated min- and max- queries. They tell us things about the size of the space allocated for the web page.

A media query inside CSS uses the @media rule:

/*
	Makes the page red whenever there are 
	at least 400px available for it in the browser.
 */
@media (min-width: 400px) {
	html {
		background: red;
	}
}

When we qualify the width feature with the min- prefix, the query reads as at least, while the max- stands for at most.

The Media Queries Level 4 specification introduces a clearer syntax: (width >= 400px) instead of (min-width: 400px). Since it's a relatively new addition, it's not a good replacement for the classic syntax yet.

Are dimension queries useful?

Knowing what constraints the browser imposes on our page is useful for making adjustments to the layout to better adapt it to the myriad of screens on which it can potentially be displayed. Media queries have been pivotal to propelling Responsive Web Design into ubiquity.

With new, more powerful, ways of expressing layout such as Flexible Box and Grid, CSS gains alternatives to media queries for responsive layouts. Every Layout by Heydon Pickering and Andy Bell is an excellent resource to get a feel for using flex and grid properties, often combined with calc(), for common patterns normally solved by media queries. CSS is also getting the min(), max(), and clamp() comparison functions, which extend min-width/max-width/min-height/max-height to all properties, and promise to further erode dimension queries' territory.

Although these recent developments don't make dimension queries obsolete, they relegate them to an auxiliary role in responsive design. That's a good thing! Media queries are coarse, and best suited to make top-level adjustments based on top-level constraints.

Dimension queries are not strictly a CSS thing, eiher. In HTML, width queries also show up in the sizes attribute on <img> and <source> elements to enable responsive images.

All in all, it seems we can't Marie Kondo them out of our web design toolbox just yet, so let's see how we can use dimension queries efficiently. From here on, I'm going to call them just media queries, since they're the only ones discussed.

Units in media queries

How does our choice of CSS units in media queries influence our design, and our users' ability to express preferences for their experience?

Devices have screens made out of pixels. The browser takes part of those device pixels to display a web page in. The narrower the browser, the fewer pixels we get. CSS has the px unit, short for pixel. For the sake of simplicity let's gloss over, for a short while, how CSS pixels are not the same thing as device pixels. They sure feel, at first brush, like they're the same.

Writing media queries in pixels is pretty straightforward, feels intuitive (especially coming from graphic design tools), and produces the result we expect. At least on the screen for which we've designed it.

But px in media queries, and in general, go against the grain of the web. Content should flow like water regardless of the vessel holding it, and pixels make it akin to a lifeless lump of coal.

CSS gives us font-relative CSS units — em, rem, and their friends — which allow us to write styles in harmony to the content we want to display. When used in media queries, like we intuit we should, what do they relate to exactly?

According to the spec, they relate to the initial value of font properties. For em and rem, the relevant property is font-size, which most browsers initially set to 16px.

As such, changing the font size of the html element:

html {
	font-size: 1.25rem;
}

...detaches the meaning of rems in your styles from the meaning of rems in media queries: 1rem in styles is now equivalent to 20px, while in media queries 1rem, and 1em for that matter, is still 16px.

Why would the spec mandate this in the first place?

The CSS Working Group explain in a FAQ entry that selectors can't depend on layout. If rem / em media queries depended on the font-size of the html element, you could create an infinite loop:

html {
	font-size: 1rem;
}

@media (min-width: 60rem) {
	html {
		/* 
			Setting this invalidates 
			the media query selector 
			that triggered this style.
		*/
		font-size: 10rem;
	}
}

This makes things a bit more cumbersome, but the limitation makes sense. You take a mental note of this peculiarity, and make sure you always think of media queries in terms of initial sizes. Suddenly —

The trouble with Safari

Current browsers generally adhere to the spec in regards to font-relative units in media queries. The big outlier is Safari, on both desktop and mobile.

Safari follows the spec for most relative units: 1em in media queries is 16px regardless of the font size on the html element. But it scales rems in particular in accordance to the html element (WebKit#156684, fixed in Safari TP 137). Since this breaks the "no layout-dependent selectors" CSS rule, we can actually witness the infinite loop described above.

Got us there, Safari! But since we can use em and rem interchangeably, as they relate to the same thing in any spec-respecting browser, we just pick the not-broken one.

If we stick to em in media queries, we bring Safari's behavior in line with the other browsers.

User preferences

Users have a few ways of adjusting their experience of a web page. Let's go through them, one by one, to see their impact on our choice of units for media queries.

Zooming in

Remember the whole pixels are not pixels thing we avoided earlier? It becomes key to how zoom works. On screens, relative units resolve to px. These are CSS pixels, distinct from physical pixels on the device. They map to physical pixels based on the device's pixel density. You can read more about it in CSS Length Explained, but what matters is there's a certain ratio between what constitutes a pixel in CSS and on the device, so that you can experience one CSS pixel roughly the same across devices.

When you change the zoom level, modern browsers will tweak the ratio between CSS pixels and device pixels. 1px in CSS ends up meaning two device pixels, or four, or half a pixel. This is a brilliant way to keep the layout mostly intact, regardless of the choice of CSS units in stylesheets.

1rem is still 16px when you zoom in, but now there are fewer (CSS) pixels available to your page. This reflects in the media queries: min-width has a lower threshold — fewer pixels, fewer rems, fewer ems. Suddenly —

The trouble with Safari (again)

Safari on macOS has a bug where em and rem units in media queries get the browser's zoom level factored in (WebKit#156687).

As you zoom in, 1rem becomes 20px, and then 28px in media queries. This is concerning because the zoom level is now doubly-represented: once by the fact that we get fewer CSS pixels for the page, and again by it inflating our em and rems.

With iOS 13, and the new iPadOS, Safari also introduced zoom controls for mobile users. They work much better to adjust the layout than the Request Desktop/Mobile Website feature, which does nothing on websites built on responsive design principles. They're part of the reason I wanted to learn more about media queries and zooming.

Thankfully, the zoom controls on iOS 13 work in accordance to the rest of the browsers. (But a glance at desktop Safari 13, currently in the Technology Preview stage, reveals it still exhibits the bug.)

Since it's isolated to desktops (thus, larger screens), the behavior macOS Safari is not the end of the world. As the user zooms in, Safari thinks it has fewer ems available than it actually has, and triggers a mobile-friendly layout sooner than it needs to — no biggie. When zooming out, what can happen is the layout shrinks disproportionately to the text, and may warrant some extra attention.

Fun with vw. Safari on macOS applies the zoom level to all relative units, and that includes vw. Yes, min-width and max-width don't always match 100vw. Why, that means we can use media queries to detect the zoom level!

We can use this quirk to our advantage, and employ media queries to fix any broken aspects of the layout in zoomed-out Safari. Since vw media queries are not affected by the element's font size the way rems are, we can, if that helps in any way, go ahead and adjust it:

@media (min-width: 133.33vw) {
	/* the zoom level in Safari is at most 75% */
	html {
		/* Something smaller than usual */
		font-size: 0.9em;
	}
}

In the example above, 133.33 comes from dividing 100 with the maximum zoom level we want to match, in our case 0.75 (75%).

Adjusting the zoom level is common, as it's readily available in menus and via keyboard shortcuts, and browsers do a good job of honoring it.

Changing the font settings

Users have other points of leverage hidden among the browser preferences — adjusting how text is displayed on web pages. It comes in (at least) two distinct flavors:

Changing the default size

So far we haven't really examined an assumption we made earlier: that the initial font size in browsers is 16px.

According to research by Evan Minto, around 3% of users navigate the web at other sizes, either because browsers themselves have a default size other than 16px, or the user has changed the default.

The distinction doesn't matter, as both have the same effect. Whatever the initial font size the browser offers (either its default, or a user preference) becomes the basis of media queries, and the initial value for the html element's font size. It's just not always 16px.

At this point, it's worth noting the consequences of absolute units for the html font size. Using html { font-size: 12px; } forces a size on the page that outright ignores the user preference.

In addition to being insensitive to the user, we further (and unpredictably) detach the notion of 1em in media queries — which, remember, are still based on that preference — from what's actually displayed on the page.

Rather, think about it in terms of:

Do I want my page, as a whole, to be typeset larger/smaller than, or largely the same as, the average experience the user has?

...and then use font-relative units for the html font size to express it. These units tweak the user preference rather than dismiss it altogether.

Setting a minimum font size

As a supplement to the default font size, browsers can also impose a minimum font size.

This does not normally¹ affect the initial font size. The font-relative media queries and font-size declarations still use the initial font size as the basis. But at render time, text on the page will have the minimum baked in, and possibly display larger than we typeset it.

When the minimum font size kicks in, browsers behave slightly differently. In Firefox, style declarations other than font-size using em and rem remain unaffected — they use the original computed size, before the adjustment. Chrome and Safari, on the other hand, will trickle the font size adjustment to other properties as well, so for example a padding of 1em around a text will remain proportional if the size is increased as a result of the minimum font size.

¹ Safari comes with a single setting called never use font sizes smaller than X. It gets factored into the initial font size, affecting media queries in ways I can't quite make heads and tails of, so... it's left as an exercise to the reader? :-)

Text-only zoom

Firefox has a Zoom text only feature which alters the way zoom works. It disables the scaling of CSS pixels, and instead factors the zoom level into the initial font size.

That means that media queries using font-relative units (em, rem) get a new basis, matching the initial font size of the <html> element.

To really drive the feature home, and make it work as expected on pages which might use an absolute font size on the <html> element, it also factors the zoom level into the font-size computed value.

Everything works splendidly. The big losers here are px queries. When you zoom in, the content gets bigger and bigger, and nothing changes in queryland, since there's no scaling of CSS pixels.

One less reason to ever use them!

Conclusion

Some takeaways from this foray into media queries:

px-based media queries have little connection to the content displayed on the page, and are best avoided. They also fail to respond to the user's preferences about font size, and can't handle Firefox's text-only zoom.

When it comes to font-relative CSS units, your best bet for predictable cross-browser behavior is to use em in media queries. It avoids the problem with rem in desktop Safari, but otherwise they're interchangeable. Zoom out of the page in macOS Safari to check that it does not break.

When adjusting the font size on the html element, use font-relative units to respect the user's preferences. And keep in mind that by changing it from the default, you're slightly shifting the meaning of 1rem in styles vs. 1rem / 1em in media queries.

It's hard to obtain an intuition on the way zoom levels and user preferences interact with one another, and the truth is always in the pudding. So be sure to test your page in a variety of scenarios involving different browsers, zoom levels, and font settings, where available.

Thanks to Simon for corrections & guidance in navigating the W3C specs.

Appendix: Deprecated media queries

CSS Media Queries 4 deprecates the use of device-width, device-height, and device-aspect-ratio, which previously referred to physical pixels. Instead, browsers should start reporting them in CSS pixels, which Firefox has already started doing (Edge seems to do so as well, but I can't tell exactly in Browserstack). Safari and Chrome continue to report physical pixels at the time of writing.

To CSS authors, these queries are not recommended.

Appendix: Methodology

I made a diagnostics page to observe what information browsers expose to CSS and JavaScript APIs:

👉 Browser Summary 👈

So far I have looked at the browsers I had at hand:

Firefox macOS
Chrome macOS
Safari macOS 12 & 13 (Technical Preview)
Safari iOS 13
Safari iPadOS

In addition, I've used Browserstack to check:

Internet Explorer 11
Microsoft Edge (I couldn't find a way to change the default font settings from within Edge itself, so I'm not 100% sure about their impact)

Measuring Media Queries

Where do the values for min-width, min-height, et cetera come from on the diagnostics page?

JavaScript has access to media queries via the CSS Object Model API. One particular feature is we can match media queries from JavaScript using the Window.matchMedia() method:

let query = window.matchMedia('(min-width: 10rem)');
if (query.matches) {
	// ...
} else {
	// ...
}

This allows us to check min-width against a certain value that matters to us, and see if it matches or not. But, for the diagnostics page, I needed to find the actual breakpoint beyond which a query (e.g. min-width) stops matching — that is, the reverse of what matchMedia() was designed for.

Technically, the CSSOM View Module spec adds JS-accessible proxies for various measurements, but just to rule out possible inconsistencies in how browsers report these values vs. the actual pivotal points in media queries, I opted to obtain the numbers straight from the proverbial horse's mouth.

To do that, we can (ab)use matchMedia to learn the breakpoint of our current browser/device by asking repeatedly with different values. I used the bisection method to avoid making a gazillion queries:

function find_min_width() {
	let start = 0; // 0 px
	let end = 1000000; // 1 million px
	let precision = 1; // whole pixels

	while (end - start >= precision) {
		let midpoint = start + (end - start) / 2;
		let query = matchMedia(`(min-width: ${midpoint}px)`);
		if (query.matches) {
			start = midpoint;
		} else {
			end = midpoint;
		}
	}

	return Math.round(start);
}

This function returns the breakpoint value, in pixels, of the min-width media query for our current environment. The same technique, with some adjustments to the precision, can be used for em, rem, and vw.

A CSS-only layout debugger

2019-09-16T00:00:00Z

I've recently come across Gajus Kuizinas' Favorite CSS hack. I had used basic CSS debug styles (also known as diagnostic CSS) before, and kind of love their simplicity. I wondered if I could take them up a notch. The challenge?

Create a CSS-only element inspector: as you hover elements, show their bounding box, and how their descendants are laid out — all with minimal disruption to the layout.

The Approach

You can see what I came up with on this demo page, and follow along as I go into the thought process, the dead-ends, and interesting tidbits of CSS I learned in the process.

Basic styling

To show an element's box, we can outline it:

* {
	outline: 1px solid red;
}

The outline property does not alter the layout since it's painted on top of elements, and authors usually only include outline styles for focused elements, so it's relatively innocuous.

To discern how the elements are nested, let's also add onionskin backgrounds:

* {
	outline: 1px solid red;
	background: rgba(255, 0, 0, 0.1);
}

So far so good! This is starting to look promising, but everything is quite red.

Cycling the hue

To further distinguish elements at different levels of nesting, let's vary the outline / background color (as in Gajus' example). The hsl() notation, which is one of the few ways to obtain color variations in CSS right now, is a good candidate for expressing our colors.

First, a bit of refactoring, to bring red and rgba(255, 0, 0, 0.1) together:

* {
	--hue: 0; /* red */
	outline: 1px solid hsl(var(--hue), 100%, 50%);
	background: hsl(var(--hue), 100%, 50%, 0.1);
}

With the --hue custom property in place, and the outline and background based on it, we can simply assign various values to it and have everything change harmoniously.

Note: HSL is good, but not great. It replaces the machine-oriented red, green, and blue channels with something humans can better relate to — hue, saturation, and lightness. It's not, however, very true to how we perceive colors. Maintaining a constant saturation and lightness, colors of various hues will look wildly brighter or darker to the human eye. When it gets implemented in browsers, the lch() color notation will offer a better approximation.

How do we go about cycling the hue in, let's say, 60 degree increments? You may be thinking, as I did, that CSS custom properties work like normal variables in other programming languages, and reach for:

* {
	--hue: calc(var(--hue, 0) + 60);
}

However, CSS disallows cyclic dependencies between custom properties — sets of properties that define themselves in terms of one another — and that includes a property that refers to itself. In a future version of the spec we might get a way to let an element redefine a custom property based on the value it has inherited from its ancestors, but until then, no dice.

Leafing through the CSS values and units spec, I was surprised to find the toggle() function. It enables elements to cycle over a set of values instead of inheriting the value. You'd be able to write:

* {
	--hue: toggle(0, 60, 120, 180, 240, 300);
}

...to get elements at each subsequent level to move 60 degrees away from their parent. Nice and clear and... unsupported. Even though the toggle() idea has been floating around since as early as 1999, no browsers implement it at the time of writing.

So, unless I'm missing a clever workaround, we're back to old-school:

* {
	--hue: 0;
}
* > * {
	--hue: 60;
}
* > * > * {
	--hue: 120;
}
* > * > * > * {
	--hue: 180;
}
* > * > * > * > * {
	--hue: 240;
}
* > * > * > * > * > * {
	--hue: 300;
}

This setup caps out at the 300 hue (a nice fuchsia), but you can continue to cycle it for as many * > * selectors as your heart lets you.

Showing the padding around elements

If the browser barely broke a sweat from anything we did so far, it's time to raise the temperature with our next mini-challenge: showing padding visually.

We're going to need something that lets us hook into the element's content box, and its padding box, independently. Hello background-origin!

The background-origin property is only meant for background images, not background colors, so we need a way to make a background image out of a solid color. The CSS Images Level 4 spec defines the image() syntax which accepts a color, such as image(fuchsia), to produce an image. But until browsers support it, we need to improvise with gradients.

The shortest formula to get a solid color with the gradient syntax is, as far as I know:

* {
	background-image: linear-gradient(fuchsia, fuchsia);
}

To get different colors for the content box and the padding box, we layer two of these images and define their background-origin separately:

* {
	background-image: linear-gradient(fuchsia, fuchsia), linear-gradient(yellow, yellow);
	background-origin: content-box, padding-box;
	background-repeat: no-repeat;
}

The order of multiple backgrounds is from closest to the user (topmost) to furthest. In the code above, the content-bound fuchsia sits on top of the padding-bound yellow. I never remember this order and have to look it up constantly. It's important to include background-repeat: no-repeat for it to work as expected, which I also tend to forget.

Note: You can probably get a similar effect with background-clip instead of the background-origin / background-repeat combo, but I haven't looked into it.

For a cooler look, like the one you sometimes see in dev tools, let's turn our yellow padding box into nice diagonal stripes. The repeating-linear-gradient is useful for this:

 {
	background-image: repeating-linear-gradient(
		45deg,
		/* angle for diagonals */ fuchsia,
		fuchsia 1px,
		/* our 1px stripes */ transparent 1px,
		transparent 3px /* 2px space between stripes */
	);
}

If we work it into our inspector code:

* {
	/* Opaque version of the color */
	--c-solid: hsl(var(--hue), 100%, 50%);

	/* Translucent version of the color */
	--c-bg: hsl(var(--hue), 100%, 50%, 0.1);

	outline: 1px solid var(--c-solid);

	background-image: 
		
		/* Content box fill */ linear-gradient(var(--c-bg), var(--c-bg)),
		/* Content box white underpaint */ linear-gradient(white, white), /* Padding box stripes */
			repeating-linear-gradient(45deg, var(--c-solid), var(--c-solid) 1px, var(
						--c-bg
					) 1px, var(--c-bg) 3px);

	background-origin: content-box, content-box, padding-box;

	background-repeat: no-repeat;
}

To make the combo work with stripes, you may notice we've added a coat of white paint over the stripes along the context box, to obscure them.

Making our inspector hover-aware

So far we've done a decent job of highlighting everything on the page. It would be easier to follow if we could localize the highlights to the element we're hovering.

Small problem: when you hover an element on the page, you don't just hover that element. You also hover all its ancestry. And the way CSS is designed does not allow us to select just the innermost hovered element. (We would need to know when a particular element contains another hovered element.)

The closest we can get to the ideal is to change * (every element on the page) to body :hover, body :hover > *, which means hovered elements and their direct descendants. We're also not styling body itself, since it doesn't provide too much information and its add visual noise.

body :hover,
body :hover > * {
	/* Opaque version */
	--c-solid: hsl(var(--hue), 100%, 50%);

	/* Translucent version */
	--c-bg: hsl(var(--hue), 100%, 50%, 0.1);

	outline: 1px solid var(--c-solid);

	background-image: 
		
		/* Content box fill */ linear-gradient(var(--c-bg), var(--c-bg)),
		/* Content box white underpaint */ linear-gradient(white, white), /* Padding box stripes */
			repeating-linear-gradient(45deg, var(--c-solid), var(--c-solid) 1px, var(
						--c-bg
					) 1px, var(--c-bg) 3px);

	background-origin: content-box, content-box, padding-box;
	background-repeat: no-repeat;
}

A note on :focus. Unlike :hover, only one element at a time has :focus, and we could model our approach around that. However, to make all elements focusable, and avoid triggering their default behavior when we click on them, we would need the help of some JavaScript:

Array.from(document.querySelectorAll('*')).forEach(el => {
	el.setAttribute('tabindex', 0);
	el.addEventListener('click', e => {
		e.preventDefault();
		e.stopPropagation();
	});
});

...which takes away from the beauty of a CSS-only solution.

Extra credits: identifying the elements

One last mini-challenge: could we show information about elements — their tag name, ID and classes – as we hover them?

CSS has the attr() function to read attributes from HTML elements and use them in styles. At the time of writing, we can only use attr() as the content of ::beforeand ::after pseudo-elements, but for our modest goals it will do nicely. We can extract an element's class and id — but not its tag name — and display them as a floating label:

[id]:hover::before,
[class]:hover::before {
	position: absolute;
	transform: translate(0, -100%);
	background: #000;
	color: hsl(var(--hue), 100%, 80%);
}

:not([id])[class]:hover::before {
	content: '.' attr(class);
}

:not([class])[id]:hover::before {
	content: '#' attr(id);
}

[id][class]:hover::before {
	content: '#' attr(id) '.' attr(class);
}

Let's unpack that.

The [id]:hover::before, [class]:hover::before selector matches the ::before pseudo-element of hovered elements which have either an ID or a class attribute attached to them.

Because we can't set these elements' content conditionally (based on which of the ID / class attributes are present) we set it for elements which have both ([id][class]), and separately for ones which have just one (:not([id])[class]) or the other (:not([class])[id]).

position: absolute takes the ::before pseudo-element out of the normal flow. By not specifying top and left offsets we leave it in its default place at the top-left hand corner of its parent's content box. Instead, we use transform(0, -100%) to pull it upwards, so it sits on top of its parent.

Note: Since we're taking over the ::before element, we might break aspects of the layout that may depend on it. And even so, the technique is not bulletproof, and might benefit from setting position: relative on the parent and explicit top and left offsets, with the risk of further altering the original layout.

All together now

Here is the final version of the code:

/* 
	Hue rotation 
	------------
*/

* {
	--hue: 0;
}
* > * {
	--hue: 60;
}
* > * > * {
	--hue: 120;
}
* > * > * > * {
	--hue: 180;
}
* > * > * > * > * {
	--hue: 240;
}
* > * > * > * > * > * {
	--hue: 300;
}
* > * > * > * > * > * > * {
	--hue: 0;
}
* > * > * > * > * > * > * > * {
	--hue: 60;
}
* > * > * > * > * > * > * > * > * {
	--hue: 120;
}
* > * > * > * > * > * > * > * > * > * {
	--hue: 180;
}
* > * > * > * > * > * > * > * > * > * > * {
	--hue: 240;
}
* > * > * > * > * > * > * > * > * > * > * > * {
	--hue: 300;
}

/* 
	Draw elements' boxes
	--------------------
*/

body :hover,
body :hover > * {
	/* Opaque version */
	--c-solid: hsl(var(--hue), 100%, 50%);

	/* Translucent version */
	--c-bg: hsl(var(--hue), 100%, 50%, 0.1);

	outline: 1px solid var(--c-solid);

	background-image: 
		
		/* Content box fill */ linear-gradient(var(--c-bg), var(--c-bg)),
		/* Content box white underpaint */ linear-gradient(white, white), /* Padding box stripes */
			repeating-linear-gradient(45deg, var(--c-solid), var(--c-solid) 1px, var(
						--c-bg
					) 1px, var(--c-bg) 3px);

	background-origin: content-box, content-box, padding-box;
	background-repeat: no-repeat;
}

/* 
	Show elements' classes / ID
	---------------------------
*/

[id]:hover::before,
[class]:hover::before {
	position: absolute;
	transform: translate(0, -100%);
	background: #000;
	color: hsl(var(--hue), 100%, 80%);
}

:not([id])[class]:hover::before {
	content: '.' attr(class);
}

:not([class])[id]:hover::before {
	content: '#' attr(id);
}

[id][class]:hover::before {
	content: '#' attr(id) '.' attr(class);
}

To make it more resilient, we can sprinkle some !important keywords, but that's left as an exercise to the reader.

Here's the demo page again. That is all! ✌️

My favorite records from 2018

2018-12-12T00:00:00Z

Abul Mogard - Above All Dreams
Against All Logic - 2012 - 2017
Alva Noto - Unieqav
Amen Dunes - Freedom
Amnesia Scanner - Another Life
Aphex Twin - Collapse EP
Autechre - NTS Sessions 1
AWVFTS - Long it May Sustain
Balmorrhea - Clear Language (Reworked)
Beak> - >>>; LA Playback
Biosphere - The Hilvarenbeek Recordings
Blawan - Wet Will Always Dry
Blanck Mass - Odd Scene / Shit Luck
Brian Eno & Kevin Shields - The Weight of History / Only Once Away my Son
Bruce Brubaker - Codex
Bruno Sanfilippo - Unity
Bucharest - Budapest
Chilly Gonzalez - Piano Solo III
Daniel Avery - Song for Alpha
Daniel Bjarnasson - Collider; Under the Tree
David August - D'Angelo; DCXXXIX A.C.
David Bryne - American Utopia
Deafhaven - Ordinary Corrupt Human Love
Dead Can Dance - Dionysus
Demdike Stare - Passion
Dita von Teese - Remix
☞ Dirtmusic - Bu Bir Ruya
Donato Dozzy - Filo Loves the Acid
Driftmachine - Shunter
Dustin O'Halloran - The Hate U Give OST; Puzzle OST
EELS - The Deconstruction
Eric Whitacre - Deep Field
Federico Albanese - By the Deep Sea
Fever Ray - Mustn't Hurry (remixes)
Film School - Bright to Death
Gas - Rausch
Gazelle Twin - Pastoral
Grouper - Field of Points
GusGus - Lies are More Flexible
Haroumi Hosono - NAGA
Ian William Craig - Thresholder
Ilya Beshevli - Deja Vu
Interpol - Marauder
Jacques Greene - Fever Focus
Joep Beving - Conatus
Jóhann Jóhannsson - Mandy OST; The Mercy OST
Jon Hopkins - Singularity
Josh T. Pearson - The Straight Hits!
Julia Holter - Aviary
Kenneth James Gibson - In the Fields of Nothing
Khruangbin - Como Todo el Mundo
Laurel Halo - Raw Silk Uncut Wood
Lubomyr Melnyk - Fallen Trees
Marianne Faithfull - Negative Capability
Marissa Nadler - For my Crimes
Mark Barrott - Nature Sounds of the Balearics
Max Würden - Momentum
Mogwai - Kin OST
Niklas Paschburg - Oceanic
Nils Frahm - All Melody; Encores 1
Nine Inch Nails - Bad Witch
Okkervil River - In the Rainbow Rain
Oneohtrix Point Never - Age Of
Oscar Mulero - Electric Shades EP
OZmotic - Elusive Balance
Peter Bjorn and John - Darker Days
Phosphorescent - C'Est la Vie
Rhye - Blood; Blood Remixed
Roger Eno - Dust of Stars
Roman Flügel - Themes
Ryuichi Sakamoto - Async Remodels
Sevdaliza - The Calling
Sigur Rós - Route One
Slow Meadow - Screensaver Prelude
Soundwalk Collective - Death Must Die
Spiritualized - And Nothing Hurt
Stuart A. Staples - Arrythmia
Taylor Deupree - Fallen
The Black Dog - Black Daisy Wheel; Post-Truth
The Blaze - Dancehall
The Brian Jonestown Massacre - Something Else
The Field - Infinite Moment
The Growlers - Casual Acquaintances
The Limiñanas - I've got trouble in mind; Shadow People
This Will Destroy You - New Others Part One; Part Two
Thom Yorke - Suspiria
Tigran Hamasyan - For Gyumri EP
Tim Hecker - Konoyo
uZiq - Challenge Me Foolish
V.A. - Climax OST
V.A. - Liminal
V.A. - In Death's Dream Kingdom
Vanessa Wagner - Liszt, Pärt
Vessel - Queen of Golden Dogs
WhoMadeWho - Through the Walls
Young Fathers - Cocoa Sugar

Timeline of favorite records: 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025.

My favorite records from 2017

2017-12-20T00:00:00Z

Here's this year's records, listed alphabetically, with favorites in bold.

Album	Bandcamp / SoundCloud / YT	Apple Music
Aldous Harding — Party	SoundCloud	🍎
Alessandro Cortini — AVANTI	SoundCloud	🍎
Alex Cameron — Forced Witness	Bandcamp	🍎
ANOHNI — Paradise EP	Bandcamp	🍎
Anton Kubikov — Whatness	Bandcamp	🍎
Astrïd & Rachel Grimes — Through the Sparkle	Bandcamp	🍎
Balmorhea — Clear Language	Bandcamp	🍎
Bedouine — Bedouine	Bandcamp	🍎
Ben Frost — The Centre Cannot Hold	Bandcamp	🍎
Björk — Utopia	—	🍎
Blanck Mass — World Eater	Bandcamp	🍎
Blonde Redhead — 3 O'Clock EP	—	🍎
Blondie — Pollinator	—	🍎
Brainwaltzera — Poly-Ana	Bandcamp	🍎
Brian Eno — Reflection	—	🍎
Burial — Rodent	Bandcamp	🍎
Cameron Avery — Ripe Dreams, Pipe Dreams	Bandcamp	🍎
Chilly Gonzales & Jarvis Cocker — Room 29	—	🍎
Charlotte Gainsbourg — Rest	YouTube	🍎
Cigarettes After Sex — Cigarettes After Sex	Bandcamp	🍎
Courtney Barnett & Kurt Vile — Lotta Sea Lice	Bandcamp	🍎
Daniele Luppi & Parquet Courts — Milano	SoundCloud	🍎
Delia Gonzalez — Horse Follows Darkness	Bandcamp	🍎
Dustin O'Halloran — 3 Movements	Bandcamp	🍎
Eluvium — Shuffle Drones	Bandcamp	🍎
Fatima Al Qadiri — Shaneera	Bandcamp	🍎
Fever Ray — Plunge	SoundCloud	🍎
Four Tet — New Energy	Bandcamp	🍎
Gas — Narkopop	Bandcamp	🍎
Godspeed You! Black Emperor — Luciferian Towers	Bandcamp	🍎
Grizzly Bear — Painted Ruins	—	🍎
High Plains — Cinderland	Bandcamp	🍎
Iron & Wine — Beast Epic	Bandcamp	🍎
Japandroids — Near to the Wild Heart of Life	Bandcamp	🍎
Jefre Cantu-Ledesma — On the Echoing Green	Bandcamp	🍎
Jlin — Black Origami	Bandcamp	🍎
Joni Void — Selfless	Bandcamp	🍎
Justin Walter — Unseen Forces	Bandcamp	🍎
Kastil — The Sadistic Abbess	Bandcamp	🍎
Kelly Lee Owens — Kelly Lee Owens	Bandcamp	🍎
Kendrick Lamar — DAMN.	SoundCloud	🍎
King Krule — The OOZ	SoundCloud	🍎
Kristoffer Lo — Anhedonia	SoundCloud	🍎
Lana Del Rey — Lust for Life	SoundCloud	🍎
Laraaji — Sun Gong	SoundCloud	🍎
LCD Soundsystem - american dream	SoundCloud	🍎
Leandro Fresco & Rafael Anton Irisarri — La Equidistancia	Bandcamp	🍎
Lift to Experience — The Texas-Jerusalem Crossroads (Reissue)	SoundCloud	🍎
Mdou Moctar — Sousoume Tamachek	Bandcamp	🍎
Mogwai — Every Country's Sun	Bandcamp	🍎
Murcof & Vanessa Wagner — EP02 & EP03	EP02, EP03	EP02, EP03
Oscar Mulero — Pattern Series Compilation	Bandcamp	🍎
Oxbow — The Black Duke	Bandcamp	🍎
Ryuichi Sakamoto - async	SoundCloud	🍎
Sevdaliza — Ison	YouTube	🍎
St. Vincent — MASSEDUCTION	SoundCloud	🍎
Tale of Us — Endless	SoundCloud	🍎
The Acid — The Bomb OST	SoundCloud	🍎
The Blaze — Territory EP	YouTube	🍎
The National — Sleep Well Beast	YouTube	🍎
The War on Drugs — A Deeper Understanding	SoundCloud	🍎
Timber Timbre — Sincerely, Future Pollution	Bandcamp	🍎
Tom Rogerson & Brian Eno — Finding Shore	Bandcamp	🍎
Visible Cloaks — Reassemblage	Bandcamp	🍎
Waxahatchee — Out in the Storm	Bandcamp	🍎
William Basinski — A Shadow in Time	Bandcamp	🍎
yaeji — EP2	SoundCloud	🍎

A significant album I was introduced to this year is the 2012 Changeling by Camille O'Sullivan 🍎, which has been on heavy rotation throughout. It starts with a cover of Gillian Welch's Revelator, about which I got excited this time last year.

Timeline of favorite records: 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025.

Other lists:

My favorite records from 2016

2016-12-06T00:00:00Z

It's been a great year for soundtracks, ambient, and modern classical music. Here are my selections for 2016, ordered A to Z, narrowed down to fifty albums I've listened to more closely and have enjoyed. My ten favorites are in bold.

Album	♫	🍏
Adam Bryanbaum Wiltzie – Salero	♫	🍏
Andy Stott – Too Many Voices	♫	🍏
ANOHNI – Hopelessness	♫	🍏
A Winged Victory for the Sullen – Iris	♫	🍏
Biosphere – Departed Glories	♫	🍏
Brian Eno – The Ship	♫	🍏
The Caretaker – Everywhere at the end of time	♫	N/A
Car Seat Headrest – Teens of Denial	♫	🍏
Circe – Circe	♫	🍏
Colin Stetson – Sorrow: A reimagining of Gorecki's 3rd Symphony	♫	🍏
Daniel Lanois – Goodbye to Language	♫	🍏
David Bowie – ★	♫	🍏
Demdike Stare – Wonderland	♫	N/A
Eluvium – False Readings On	♫	🍏
Explosions in the Sky – The Wilderness	♫	🍏
Floating Points – Kuiper	♫	🍏
Gold Panda – Good Luck and Do Your Best	♫	🍏
Kassel Jaeger, Stephan Mathieu, Akira Rabelais – Zauberberg	♫	🍏
Jambinai – A Hermitage	♫	🍏
Jherek Bischoff – Cistern	♫	🍏
Jóhann Jóhannsson – Orphée	♫	🍏
Jóhann Jóhannsson – Arrival	♫	🍏
King Ghazi Presents Abu Sayah – Houran & Shamaleh	♫	🍏
Kjartan Sveinsson – Der Klang der Offenbarung des Göttlichen	♫	🍏
Klara Lewis – Too	♫	🍏
Kristoffer Lo – The Black Meat	♫	🍏
The Limiñanas – Malamore	♫	🍏
Lambchop – FLOTUS	♫	🍏
Loscil – Monument Builders	♫	🍏
Lubomyr Melnyk – Illirion	♫	🍏
Ludovico Einaudi – Elements (The Remixes) EP	♫	🍏
Max Richter – Sleep (Remixes)	♫	🍏
Melanie de Biasio – Blackened Cities	♫	🍏
Mogwai – Atomic	♫	🍏
Murcof × Vanessa Wagner – Statea	♫	🍏
Nick Cave & the Bad Seeds – Skeleton Tree	♫	🍏
PJ Harvey – The Hope Six Demolition Project	♫	🍏
Praed – The Fabrication of Silver Dreams	♫	🍏
Radiohead – A Moon Shaped Pool	♫	🍏
Richard J. Birkin – Vigils	♫	🍏
Scott Walker – The Childhood of a Leader	♫	🍏
Tindersticks – The Waiting Room	♫	🍏
Trent Reznor & Atticus Ross – Juno	N/A	🍏
Trent Reznor & Atticus Ross, Gustavo Santaolalla, Mogwai – Before the Flood	♫	🍏
Various Artists – Eleven into Fifteen: a 130701 Compilation	♫	🍏
Various Artists – LateNightTales: Olafur Arnalds	♫	🍏
Various Artists ‐ Pop Ambient 2017	♫	🍏
Wolfgang Voigt – Ambient Grunge	♫	🍏
Woodkid & Nils Frahm – Ellis EP	♫	🍏
Yann Tiersen – EUSA	♫	🍏

Addendum, Dec 16, 2016

A great album that has cropped up since I've published the list is Alex Cameron's "Jumping the Shark" (🍏). Also worth noting is Sylvan Esso's cover of "Everything is Free" (🍏) by Gillian Welch, whose album "Time (The Revelator)" (🍏) was, well, a revelation.

Bonus: This year's list in the form of a glorious YouTube playlist, courtesy of my friend Adi.

Timeline of favorite records: 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025.

Other lists:

Extracting things from JavaScript strings

2016-08-19T00:00:00Z

You want to pull some information out of a JavaScript string and you have a pattern (regular expression, that is) to match against. Surprised that the String/RegExp combo API lacks a direct method, you comb the web for a solution. On StackOverflow you're invited to put a RegExp.exec() in a while loop. I'll show you a better if unorthodox way of doing it with String.replace.

(Ab)using String.replace

Let's start with the real-life-sounding, contrived scenario of wanting to extract all numbers from a JavaScript string. A simple pattern for matching all occurrences of numbers (specifically, decimal and floating point numbers) is:

/[+-]?\d+(\.\d+)?/g

(don't forget the g flag for Global)

The RegExp.exec way of doing it:

var str = "Some of the best numbers are 42, and, in particular 42.999.";
var number_regex = /[+-]?\d+(\.\d+)?/g;

var matches = [];

var match;
while ((match = number_regex.exec(str)) !== null) {
	matches.push(match[0]);
}

console.log(matches);

// => ["42", "42.999"]

If instead we use String.replace we can write:

var str = "Some of the best numbers are 42, and, in particular 42.999.";
var number_regex = /[+-]?\d+(\.\d+)?/g;

var matches = [];
str.replace(number_regex, function(match) {
	matches.push(match);
});

console.log(matches);

// => ["42", "42.999"]

In effect, we're hijacking String.replace to act as an iterator over the matches, rather than actually replacing anything in the String.

This has a couple of advantages:

you do away with the anxiety-inducing while loop because what can go wrong I'll tell you what can go wrong; use a regular expression literal in the while statement, instead of a regex saved in variable, and you'll get an infinite loop (courtesy of the lastIndex property):

while ((match = /[+-]?\d+(\.\d+)?/g.exec(str)) !== null) { FOREVERCODE }

you get to have named parameters for your matches instead indexes in an array.

Extracting parts of a pattern

Each group we create in a regular expression, using the (...) construct, will result in an additional parameter to our "replacer" function. Let's take another example.

Assume in an blog article you can add Wordpress-style shortcodes for embedding videos:

Top 10 videos this months:

1. [youtube:FyCsJAj69sc]
2. [vimeo:128373915]
...

A straightforward regular expression to match these shortcodes is:

/\[\w+:\w+\]/g

// match alphanumeric characters, followed by colon, 
// followed by another set of alphanumeric characters
// all wrapped in square brackets

but we want to match the parts individually, so we put them in groups:

/\[(\w+):(\w+)\]/g

Our pattern-extraction function now receives two extra parameters, one for each group:

var str = "Top 10 videos this months: \
			1. [youtube:FyCsJAj69sc] \
			2. [vimeo:128373915]";
var shortcode_regex = /\[(\w+):(\w+)\]/g;

var matches = [];
str.replace(shortcode_regex, function(match, code, id) {
	matches.push({
		code: code,
		id: id
	});
});

console.log(matches);

For which we get:

[
	{"code": "youtube", "id": "FyCsJAj69sc"}, 
	{"code": "vimeo", "id": "128373915"}
]

Tip: Have a regex group that you don't want to show up in the matcher function? Use the non-capturing group syntax (?: ... ).

Now you know how to make pattern extraction more readable and less error-prone.

A few FACT mixes

2016-01-22T00:00:00Z

Time for another listicle sans commentary!

Here are a few of the weirder FACT magazine mixes — the ones to which I find myself getting back, time and time again.

#379 - Grouper (Apr 2013)

Link. Tracklist N/A.

#399 - Zola Jesus (Sept 2013)

Link. Tracklist N/A.

#414 - Julianna Barwick (Dec 2013)

Link. Tracklist N/A.

#445 - Stephen O'Malley (Jun 2014)

Link.

Tracklist

Spiridon Shisgigin - ‘Tanz der Schamanin (Dance of the Female Shaman)’ (from Soul of Yakutia)
Akira Rabelais - ‘Comme Un Ange Enivré D’un Soleil Radieux’ (from Caduceus)
Hornroh - ‘MUEZZO’ (from Findling)
Ernstalbrecht Stiebler - ‘…Im klang II’ (from «… Im klang…» hat(now))
Angus MacLise - ‘Universal Solar Calendar’ (The Cloud Doctrine)
Angus MacLise - ‘Tambura Drone + Sine Wave Generator’ (from The Cloud Doctrine)
Moluk Zarrābi Darāmad - ‘Dād (Māhur)’ (from Let No One Judge You: Early Recordings From Iran, 1906-1933)
Montakhab-oz-Zākerin - ‘Qafqāz I (Segāh)’ (from Let No One Judge You: Early Recordings From Iran, 1906-1933)
Montakhab-oz-Zākerin - ‘Qafqāz II (Segāh)’ (from Let No One Judge You: Early Recordings From Iran, 1906-1933)
Irān-od-Dowleh Helen - ‘Darāmad, Dād, Khāvarān (Māhur)’ (from Let No One Judge You: Early Recordings From Iran, 1906-1933)
Hans Kennel, Mytha - ‘Chuehreiheli’ (from How It All Started)
Susan Alcorn - ‘Sapphire’ (from New Music For Old Instruments)
Christian Wolff - ‘Exercise 10’ (from 10 Exercises)
Arthur Brown’s Kingdom Come - ‘Triangles’ (from Journey)
Jacula - ‘Ego Sum Qui Sum’ (from Anno Demoni)
Antonius Rex - ‘Enchanted Woods’ (from Ralefun)
Fushitsusha - ‘暗号’ (from A Document Film Of Keiji Haino)
Joe Meek/The Blue Men - ‘The Bulblight’ (from I hear a new world)
François-Bernard Mâche - ‘Ouverture’ (from L’announce faite a marie)
François-Bernard Mâche - ‘Le baiser’ (from L’announce faite a marie)
François-Bernard Mâche - ‘Le vent’ (from L’announce faite a marie)
François-Bernard Mâche - ‘Chevauchée’ (from L’announce faite a marie)
François-Bernard Mâche - ‘Le pélerin’ (from L’announce faite a marie)
François-Bernard Mâche - ‘Ma mise au tombeau’ (from L’announce faite a marie)
Jakob Ullmann - ‘Disappearing Musics For Six Players (More Or Less)’ (from Edition Zeitgenössische Musik)

#471 - Jonny Trunk (Nov 2014)

Link.

Tracklist

Guide To Oral Sex (unreleased)
You – Mean
Flugerenden – Unknown
Hot Water – Hazlewood / Trey
Pace – Golden Ring 6
Screw On – Jacky Giordano
The Sapphic Sleep – Don Cherry
Ode To A Screw – Taking Off
The Wizard – Frankie Bones
Metallic Doings – Bruton Library
Electro People – Fox
Moogies Bloogies – Anthony Newley / Delia Derbyshire (unreleased)
Shadows Of Blood – Platonos
Eyes Without A Face – Jarre
See Saw – Libby
Smilin Billy – Heath Bros
Even The Horses Had Wings – Kathy Bobo Bates
Underwater Boy – Lindt
Airlock – Herrmann
Makkaresh – Torrossi
Tornadeo – Jiants
Ghost Horse – Elsie
Sea Drift – Jonny Trunk (unreleased)

#512 - Max Richter

Link.

Tracklist

Charles Ives – The Unanswered Question
Godspeed You! Black Emperor – Rockets fall on Rocket falls
J.S. Bach – Fugue in C# minor from Book 1 of The Well tempered Clavier
J.S Bach – Chorale from “Christ Lag in Todesbanden”
Osvaldo Golijov – Tenebrae II
Urmas Sisask – Ursa Minor from Starry Sky Cycle
Boards of Canada – Over the horizon radar
Sergei Rachmaninov – Rejoice O Virgin from The Vespers
Howard Skempton – Of Late
Philip Glass – Violin Concerto 2nd Movement
Grouper – Clearing
Henry Purcell – Fantasia in 7 parts
William Byrd – Mass for 5 voices, Agnus Dei
Luciano Berio – Wasserklavier
Michael Tippet – Concerto for Sting Orchestra, II Adagio Cantabile
Cat Power – Maybe Not

#522 - Vainio & Vigroux

Link.

Tracklist

Giacinto Scelsi – Anahit
Orchestra and choir of Polish radio
Pharmakon – Crawling on bruised knees
Napalm Death – Peel Sessions 88: tracks 1 to 10
Bernard Parmegiani – Accidents Harmoniques – De Naturae Sonorum (GRM)
Scott Walker – Clara
Techno Animal – Hell
Federico Schmucher – Print…?
Whitehouse – Wriggle like a Fucking Eel
Swans – Coward
Robert de Visee – Courante
Interprète Pascal Monteilhet (Orbe) – Zig Zag label
Haino Keiji – First Blackness
Disques Du Soleil Et De L’Acier
Shapednoise feat. Justin K Broadrick – Enlightenment

#527 - Jóhann Jóhannsson (Dec 2015)

Link.

Tracklist

Mihaly Vig: The Turin Horse
Dimitri Shostakovich: String Quartet No. 15 in E Flat Minor Op. 144 – 1. Elegy, Adagio
David Lang: Amelia (I’m Waiting for My Man)
Meredith Monk: Braid 1 and Leaping Song
Robert Turman: Flux
Glenn Branca: Second Movement (The Temple of Venus Pt. 2)
Gloria Coates: Chiaroscuro – Illumination
Witold Lutoslawski: Funeral Music – Prologue
Jón Leifs: Hinsta Kveðja (Elegy) Op. 53 for String Orchestra
Irena Havlová & Vojtěch Havel: Pod Hvězdou Pomiranč (Under The Orange Star)
Charlemagne Palestine: Sliding Fifths (1 2)
Alvin Lucier: I Am Sitting in a Room
Holger Czukay: Boat Woman Song
Charlemagne Palestine: One Two Three Fifths (1 3)

Drawing every street in Romania

2015-12-28T00:00:00Z

Ben Fry's project All Streets left quite the impression on me back in 2007 and it's stayed in the back of my head ever since. About a year ago I started to wonder if I could pull off something similar with tools I am comfortable with, namely JavaScript for data processing and SVG for drawing things.

And this happened:

Here's a step-by-step account of how I got there.

1. Get the data

Geofabrik thoughtfully packages OpenStreetMap data for every country, so I grabbed the .osm.pbf for Romania. PBF is an alternative to the XML format in which OSM data is usually kept.

OSM works with just three data types:

nodes define points in space (through latitude & longitude);
ways are collections of nodes which define linear features (yay, streets!) and area boundaries;
relations are sometimes used to explain how other elements work together — e.g. multiple ways that define a longer route.

For our modest purposes, we only need:

Ways that are labeled as streets;
The nodes that comprise those ways.

2. Extracting street data from the PBF

Time to brush off our Node.js skills and extract the data from the PBF file.

After a naïve attempt at loading everything in memory, it became apparent that data at this volume needs streaming — a technique in which we read data item-by-item, with only fraction in memory at any given time. osm-pbf-parser is a streaming parser which goes through the PBF data and outputs small sets of JSON objects in the formats below.

This is a node...

{
  type: 'node',
  id: 122321,
  lat: 53.527972600000005,
  lon: 10.0241143,
  tags: {...},
  info: {...}
}

...and this is a way

{
  type: 'way',
  id: 108,
  tags: {
    created_by: 'Potlatch 0.8',
    highway: 'living_street',
    name: 'Kitzbühler Straße',
    postal_code: '01217'
  },
  refs: [ 442752, 231712390, 442754 ],
  info: {...}
}

Traversing the PBF file, we can do these checks to pick up the items we need:

function isNode(item) {
	return item.type === 'node';
}

function isStreet(item) {
	return item.type === 'way' && item.tags.highway;
}

We'll put our extracted nodes and streets into plain-text files, with one item per line — this is a format that's amenable to streaming so it will be easy to read them back on subsequent steps.

extract-nodes.js

var fs = require('fs');
var through2 = require('through2');
var osm_parser = require('osm-pbf-parser');
var JSONStream = require('JSONStream');

var INPUT_FILE = 'data/data.osm.pbf';
var OUTPUT_FILE = 'output/nodes.txt';

function isNode(item) {
	return item.type === 'node';
}

function serializeNode(item) {
	return item.id + ',' + item.lat + ',' + item.lon;
}

console.log('Extracting nodes from data file: ' + INPUT_FILE);
fs.createReadStream(INPUT_FILE)
	.pipe(new osm_parser())
	.pipe(
		through2.obj(function (items, enc, next) {
			var nodes = items.filter(isNode);
			var output = nodes.map(serializeNode).join('\n');
			this.push(output);
			next();
		})
	)
	.pipe(fs.createWriteStream(OUTPUT_FILE))
	.on('finish', function () {
		console.log('Finished extracting nodes onto file: ' + OUTPUT_FILE);
	});

extract-streets.js

var fs = require('fs');
var through2 = require('through2');
var osm_parser = require('osm-pbf-parser');
var JSONStream = require('JSONStream');

var INPUT_FILE = 'data/data.osm.pbf';
var OUTPUT_FILE = 'output/streets.txt';

function isStreet(item) {
	return item.type === 'way' && item.tags.highway;
}

function serializeStreet(item) {
	return item.refs.join(',');
}

console.log('Extracting streets from data file: ' + INPUT_FILE);
fs.createReadStream(INPUT_FILE)
	.pipe(new osm_parser())
	.pipe(
		through2.obj(function (items, enc, next) {
			var streets = items.filter(isStreet);
			var output = streets.map(serializeStreet).join('\n');
			this.push(output);
			next();
		})
	)
	.pipe(fs.createWriteStream(OUTPUT_FILE))
	.on('finish', function () {
		console.log('Finished extracting streets onto file: ' + OUTPUT_FILE);
	});

Which outputs:

nodes.txt

360714, 44.493699500000005, 26.0854494
360853, 44.467436600000006, 26.0771428
537912, 44.425765000000006, 26.123137900000003
546140, 44.47436450000001, 26.123994300000003
...

(id,latitude,longitude)

streets.txt

656951, 2260664460, 3227352565, 656952, ...
256700851, 2152136723, 659642, 256705252, 2152144026, ...
304797001, 2382014755, 310215524, 255848765, ...

(node1,node2,node3,...)

Note: We're using through2.obj() to simplify the pipework.

3. Mapping node IDs to their coordinates

We now have a huge set of node coordinates and another huge set of node IDs. In order to map the IDs to the coordinates, we need to do two things:

Load the nodes into some sort of database
Query the database to look up the coordinates for a given ID

For storage I've turned to LevelDB which is a pretty straightforward, file-based database. You use it in Node through leveldown and levelup.

load-nodes.js

var fs = require('fs');
var through2 = require('through2');
var split2 = require('split2');
var levelup = require('level');

var DATABASE_NAME = 'everystreet';
var INPUT_FILE = 'output/nodes.txt';

var i = 0;

console.log('creating levelDB database ' + DATABASE_NAME);
levelup(DATABASE_NAME, function (err, db) {
	var write_stream = db.createWriteStream();
	fs.createReadStream(INPUT_FILE, { encoding: 'utf8' })
		.pipe(split2())
		.pipe(
			through2.obj(function (line, enc, next) {
				var parts = line.split(',');
				this.push({
					key: parts[0],
					value: parts[1] + ',' + parts[2]
				});

				// Prevent memory leak
				// See: https://github.com/rvagg/node-levelup/issues/298
				if (i++ > 999) {
					setImmediate(next);
					i = 0;
				} else {
					next();
				}
			})
		)
		.pipe(write_stream)
		.on('finish', function () {
			console.log(
				'Finished importing nodes into the database ' + DATABASE_NAME
			);
		});
});

This creates a LevelDB database with the name everystreet (which in turn creates an everystreet folder where the data is kept), and adds all nodes with key=ID and value=lat,lon.

Note: While attempting this I ran into some memory troubles to which the easy solution is to delay every 1000th next() call. There's also level-bulk-load which attempts to optimize bulk writing in LevelDB, so that might be something to look into.

Next, let's map the node IDs to their coordinates in our street definitions.

apply-nodes.js

var fs = require('fs');
var through2 = require('through2');
var split2 = require('split2');
var levelup = require('level');
var async = require('async');

var DATABASE_NAME = 'everystreet';
var INPUT_FILE = 'output/streets.txt';
var OUTPUT_FILE = 'output/streets-with-coordinates.txt';

console.log(
	'Applying node data from database ' +
		DATABASE_NAME +
		' to street data from file: ' +
		INPUT_FILE
);
levelup(DATABASE_NAME, function (err, db) {
	var write_stream = fs.createWriteStream(OUTPUT_FILE);

	fs.createReadStream(INPUT_FILE, { encoding: 'utf8' })
		.pipe(split2())
		.pipe(
			through2.obj(function (line, enc, next) {
				async.mapSeries(
					line.split(','),
					function (node_id, callback) {
						db.get(node_id, function (err, coords) {
							callback(err, coords);
						});
					},
					function (err, result) {
						this.push(result.join(',') + '\n');
						next();
					}.bind(this)
				);
			})
		)
		.pipe(write_stream)
		.on('finish', function () {
			console.log(
				'Finished applying node data into file: ' + OUTPUT_FILE
			);
		});
});

We're streaming through each street in the data file, querying the database for the coordonates — using async.mapSeries to make sure we get back the node data in the correct order — and serializing them into a plain-text file.

streets-with-coordinates.js

44.469672200000005, 26.093109000000002, 44.469469600000004, 26.093366600000003, ...
44.46975080000001, 26.092981700000003, 44.4696756, 26.092841000000004, ...

At this point we're done with extracting all the data we need but we still need to convert it from geographical coordinates to screen coordinates. *Takes deep breath*. Onwards!

4. Mapping geographical coordintes to screen coordinates

There are many different ways to project the Earth's surface onto 2D space. Many maps are laid out based on the spherical Mercator projection. Assuming λ is the longitude and φ is the latitude, both expressed in radians, the formula is simple:

function mercator(λ, φ) {
	return [λ, Math.log(Math.tan(Math.PI / 4 + φ / 2))];
}

Before we dive into it, let's see what we need to do:

Find the bounding box of all our coordinates and its aspect ratio;
Transform the geographical coordinates into screen coordinates, based on the bounding box.

The bounding box of our map is the smallest rectangle that contains all the nodes. We can find it by identifying the minimum/maximum longitude and latitude in our dataset. If we transform the points that define the bounding box using the Mercator projection, we can also obtain our final map's aspect ratio, which we're going to use later. The script below computes both:

bbox.js

var fs = require('fs');
var through2 = require('through2');
var split2 = require('split2');

var INPUT_FILE = 'output/streets-with-coordinates.txt';
var OUTPUT_FILE = 'output/bbox.json';

// initial values
var bbox = {
	north: -90, // minimum latitude
	south: 90, // maximum latitude
	east: -180, // minimum longitude
	west: 180 // maximum longitude
};

function toRadians(deg) {
	return (deg * Math.PI) / 180;
}

function mercator(λ, φ) {
	return [λ, Math.log(Math.tan(Math.PI / 4 + φ / 2))];
}

function projection(lat, lon) {
	return mercator(toRadians(lon), toRadians(lat));
}

console.log('Finding bounding box in file: ' + INPUT_FILE);
fs.createReadStream(INPUT_FILE, { encoding: 'utf8' })
	.pipe(split2())
	.pipe(
		through2.obj(function (line, enc, next) {
			var coords = line.split(',');
			for (var j = 0; j < coords.length; j += 2) {
				var lat = parseFloat(coords[j]),
					lon = parseFloat(coords[j + 1]);

				if (lat > bbox.north) {
					bbox.north = lat;
				}
				if (lat < bbox.south) {
					bbox.south = lat;
				}
				if (lon > bbox.east) {
					bbox.east = lon;
				}
				if (lon < bbox.west) {
					bbox.west = lon;
				}
			}
			next();
		})
	)
	.on('finish', function () {
		var nw_projected = projection(bbox.north, bbox.west);
		var se_projected = projection(bbox.south, bbox.east);

		var west = nw_projected[0];
		var north = nw_projected[1];
		var east = se_projected[0];
		var south = se_projected[1];

		var output = {
			bbox: bbox,
			ratio: (east - west) / (north - south)
		};

		fs.writeFile(OUTPUT_FILE, JSON.stringify(output, null, 2));
	});

The script outputs the following information:

bbox.json

{
  "bbox": {
    "north": 48.4394855,
    "south": 43.578847700000004,
    "east": 29.726612400000004,
    "west": 20.198656500000002
  },
  "ratio": 1.3601773494902782
}

Let's now take our geographical coordinates transform them using the Mercator projection; afterwards, we express them as percentages within the map's bounding box which will make it easy for us to draw at any scale.

map-coordinates.js

var fs = require('fs');
var through2 = require('through2');
var split2 = require('split2');

var INPUT_FILE = 'output/streets-with-coordinates.txt';
var OUTPUT_FILE = 'output/streets-with-coordinates-mapped.txt';
var BBOX_FILE = 'output/bbox.json';

// read the bounding box and project it using Mercator
var o = JSON.parse(fs.readFileSync(BBOX_FILE, 'utf8'));
var nw_projected = projection(o.bbox.north, o.bbox.west);
var se_projected = projection(o.bbox.south, o.bbox.east);
var north = nw_projected[1];
var south = se_projected[1];
var west = nw_projected[0];
var east = se_projected[0];

function toRadians(deg) {
	return (deg * Math.PI) / 180;
}

function mercator(λ, φ) {
	return [λ, Math.log(Math.tan(Math.PI / 4 + φ / 2))];
}

function projection(lat, lon) {
	return mercator(toRadians(lon), toRadians(lat));
}

function percent(lonlat) {
	return [
		(lonlat[0] - west) / (east - west),
		(lonlat[1] - south) / (north - south)
	];
}

console.log('Mapping nodes using Mercador projection from file: ' + INPUT_FILE);
fs.createReadStream(INPUT_FILE, { encoding: 'utf8' })
	.pipe(split2())
	.pipe(
		through2.obj(function (line, enc, next) {
			var coords = line.split(',');
			var pts = [];
			for (var i = 0; i < coords.length; i += 2) {
				pts.push(
					percent(projection(coords[i], coords[i + 1])).join(',')
				);
			}
			this.push(pts.join(';') + '\n');
			next();
		})
	)
	.pipe(fs.createWriteStream(OUTPUT_FILE))
	.on('finish', function () {
		console.log(
			'Finished mapping nodes using Mercator projection onto file: ' +
				OUTPUT_FILE
		);
	});

All nodes should be now in the [0,1] range:

streets-with-coordinates-mapped.txt

0.6186481719547, 0.17686588159630384; 0.6186752081839509, 0.17682535252522288; ...
0.618634811271534, 0.1768816051533656; 0.6186200442006669, 0.17686656174973386; ...
...

5. Drawing the map in SVG

We now have everything we need to start drawing some SVG paths. This is the structure we're aiming for:

<svg width="..." height="..." viewbox="...">
	<path d="M x1 y1 L x2 y2 L x3 y3 ..." />
	...
</svg>

Remember the map ratio we computed earlier? We can use that to derive the height of our map based on a width of our choice. And to transform our points from the [0,1] range to SVG-ready coordinates, we just need to factor in the map's dimensions:

var map_width = 1500;
var map_height = map_width / map_ratio;

var screen_x = longitude * map_width;
var screen_y = (1 - latitude) * map_height;

Note: The 1 - latitude is to account for the fact that the origin of SVG coordinates is at the top left corner while our coordinates assume an origin in the bottom left corner.

generate-svg.js

var fs = require('fs');
var through2 = require('through2');
var split2 = require('split2');
var multiline = require('multiline');

var DEFAULT_MAP_WIDTH = 1500; // px

var INPUT_FILE = 'output/streets-with-coordinates-mapped.txt';
var OUTPUT_FILE = 'output/streets.svg';
var BBOX_FILE = 'output/bbox.json';

var o = JSON.parse(fs.readFileSync(BBOX_FILE, 'utf8'));

var map_width = DEFAULT_MAP_WIDTH;
var map_height = map_width / o.ratio;

var write_stream = fs.createWriteStream(OUTPUT_FILE);

write_stream.write(
	"<svg xmlns='http://www.w3.org/2000/svg' width='{w}' height='{h}' viewbox='0 0 {w} {h}'>"
		.replace(/\{w\}/g, map_width)
		.replace(/\{h\}/g, map_height)
);

console.log('Generating SVG from file: ' + INPUT_FILE);
fs.createReadStream(INPUT_FILE, { encoding: 'utf8' })
	.pipe(split2())
	.pipe(
		through2.obj(
			function (line, enc, next) {
				var path_data =
					'M ' +
					line
						.split(';')
						.map(function (pt) {
							var lonlat = pt.split(',');
							return [
								lonlat[0] * map_width,
								(1 - lonlat[1]) * map_height
							].join(' ');
						})
						.join(' L ');
				this.push(
					'<path d="' +
						path_data +
						'" stroke-width="0.1" stroke="black" fill="none"/>\n'
				);
				next();
			},
			function (flush) {
				this.push('</svg>');
				flush();
			}
		)
	)
	.pipe(write_stream)
	.on('finish', function () {
		console.log('Finished generating SVG onto file: ' + OUTPUT_FILE);
	});

And voilá! We have our all streets in Romania drawn up in SVG, which you can open in your browser (as opposed to other tools).

Here it is in all its glory: streets.svg (Warning: 262MB file!)

Final thoughts

Making it printable. Loading or converting a 262MB SVG is no easy feat, but ImageMagick somehow miraculously created a wall-sized PNG image:

convert -density 900 output/streets.svg output/streets.png

Another idea worth pursuing is making electron print out a PDF.

Optimizing the map. Taking into account the output resolution, one could simplify the paths with simplify.js to eliminate details without affecting the appearance (e.g. points that are very close together):

simplify([{x: ..., y: ... }, { x: ..., y: ... }, ...], 0.5) => [{x : ..., y: ...}, ...]

And considering the browser needs to build the DOM tree along with drawing the millions of paths in our file, one easy fix to have fewer DOM nodes is to batch the path data into multipaths of, say, a thousand paths:

var path_buffer = '';
var counter = 0;
...
  path_buffer += path_data;
  if (counter++ > 999) {
    this.push('<path d="' + path_buffer + '" stroke-width="0.1" stroke="black" fill="none"/>\n');
    counter = 0;
    path_buffer = '';
  }

I hope you've enjoyed this short foray into mapping! You can find all the scripts discussed here on Github: danburzo/every-street. If you have any idea on how to make this workflow better, I'd love to hear it!

Eight Versions of Satie’s Gnossienne No. 1 (1890)

2015-12-26T00:00:00Z

1. Family Fodder - The Big Dig

The Big Dig / Plant Life (1982)

2. Daisaku Kume - Azuma No Theme

From the sountrack of Takeshi Kitano's Violent Cop (1989).

3. Jun Miyake - Gnossienne #1

(Glam Exotica!, 1999)

4. Arthur H & Feist - La chanson de Satie

(Adieu tristesse, 2005)

5. Beltuner - Gnossienne #1

(Beltuner, 2005)

6. Chicha Libre - Gnossienne No. 1

(¡Sonido Amazonico!, 2008)

7. Erkan Oğur - Gnossienne No. 1

(Mommo OST, 2009)

8. Orange Blossom - Ya Sîdî

(Under the Shade of Violets, 2014)

More Satie.

My favorite records from 2015

2015-12-18T00:00:00Z

Great albums released this year, A-Z with favorites are in bold.

Album	♫	🍏
Adam Bryanbaum Wiltzie – Travels in Constants Vol. 24	♫	🍏
Anthony Child – Electronic Recordings from Maui Jungle Vol. 1	♫	🍏
Arca – Mutant	♫	🍏
Bang on a Can All-Stars – Field Recordings	♫	🍏
Beirut – No No No	♫	🍏
Björk – Vulnicura	♫	🍏
Chilly Gonzales – Chambers	♫	🍏
Demdike Stare – Testpressing #007: Rathe/Patchwork	♫	🍏
Father John Misty – I Love You, Honeybear	♫	🍏
Four Tet – Morning/Evening	♫	🍏
Godspeed You! Black Emperor – 'Asunder, Sweet and Other Distress'	♫	🍏
Grimes – Art Angels	♫	🍏
Holly Herndon – Platform	♫	🍏
Inventions – Maze of Woods	♫	🍏
Jamie xx – In Colour	♫	🍏
Jeff Bridges – Sleeping Tapes	♫	🍏
Jenny Hval – Apocalypse, girl	♫	🍏
Jim O'Rourke – Simple Songs	♫
Joanna Newsom – Divers	♫
Jon Hopkins – Late Night Tales	♫	🍏
Kurt Vile – b’lieve i’m goin down...	♫	🍏
Lubomyr Melnyk – Rivers and Streams	♫
Luke Abbott – Music For A Flat Landscape: Original Soundtrack to 'The Goob'	♫	🍏
METZ – II	♫	🍏
Max Richter – From Sleep	♫	🍏
Nava Mamă – Nava Mamă	♫
Nils Frahm – Late Night Tales	♫	🍏
Nils Frahm – Solo	♫	🍏
Noveller – Fantastic Planet	♫
Oneohtrix Point Never – Garden of Delete	♫	🍏
OZmotic & Fennesz – AirEffect	♫	🍏
Protomartyr – The Agent Intellect	♫	🍏
Rachel Grimes – The Clearing	♫	🍏
Richard Hawley – Hollow Meadows	♫	🍏
Richie Hawtin – From My Mind To Yours	♫	🍏
Sleaford Mods – Key Markets	♫	🍏
Sleater-Kinney – No Cities to Love	♫	🍏
Squarepusher – Damogen Furies	♫	🍏
St Germain – St Germain	♫	🍏
Sufjan Stevens – Carrie and Lowell	♫	🍏
Sunn O))) – Kannon	♫	🍏
Tame Impala – Currents	♫	🍏
The Gurdjieff Ensemble, Levon Eskenian – Komitas	♫
Tigran Hamasyan – Luys i Luso	♫
Viet Cong – Viet Cong	♫	🍏
Wil Bolton – Marram	♫
William Basinski – The Deluge/Cascade	♫	🍏
Wolfgang Voigt – Rückverzauberung 10 / Nationalpark	♫	🍏
Yuta Nagashima – White Sleep	♫	🍏

Timeline of favorite records: 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025.

A few other year-end lists:

+ Largehearted Boy's excellent meta-list.

Walking in Walden

2015-01-20T00:00:00Z

Every sentence in Walden that contains the words I and walk.

"where I see in my daily walks human beings living in sties, and all winter with an open door, for the sake of light, without any visible, often imaginable, wood-pile, and the forms of both old and young are permanently contracted by the long habit of shrinking from cold and misery, and the development of all their limbs and faculties is checked.

"I walked about the outside, at first unobserved from within, the window was so deep and high.

"I never in all my walks came across a man engaged in so simple and natural an occupation as building his house.

"It would surpass the powers of a well man nowadays to take up his bed and walk, and I should certainly advise a sick one to lay down his bed and run.

"I walked over each farmer's premises, tasted his wild apples, discoursed on husbandry with him, took his farm at his price, at any price, mortgaging it to him in my mind.

"As I walk along the stony shore of the pond in my shirt-sleeves, though it is cool as well as cloudy and windy, and I see nothing special to attract me, all the elements are unusually congenial to me.

"There was a certain positive originality, however slight, to be detected in him, and I occasionally observed that he was thinking for himself and expressing his own opinion, a phenomenon so rare that I would any day walk ten miles to observe it, and it amounted to the re-origination of many of the institutions of society.

"As I walked in the woods to see the birds and squirrels, so I walked in the village to see the men and boys.

"Sometimes, after coming home thus late in a dark and muggy night, when my feet felt the path which my eyes could not see, dreaming and absent-minded all the way, until I was aroused by having to raise my hand to lift the latch, I have not been able to recall a single step of my walk, and I have thought that perhaps my body would find its way home if its master should forsake it, as the hand finds its way to the mouth without assistance.

"As I walked on the railroad causeway, I used to wonder at the halo of light around my shadow, and would fain fancy myself one of the elect.

"Once I was surprised to see a cat walking along the stony shore of the pond, for they rarely wander so far from home.

"I sometimes left a good fire when I went to take a walk in a winter afternoon.

"For many weeks I met no one in my walks but those who came occasionally to cut wood and sled it to the village.

"It chanced that I walked that way across the fields the following night, about the same hour, and hearing a low moaning at this spot, I drew near in the dark, and discovered the only survivor of the family that I know, the heir of both its virtues and its vices, who alone was interested in this burning, lying on his stomach and looking over the cellar wall at the still smouldering cinders beneath, muttering to himself, as is his wont. " I felt it, and still remark it almost daily in my walks, for by it hangs the history of a family.

"But no weather interfered fatally with my walks, or rather my going abroad, for I frequently tramped eight or ten miles through the deepest snow to keep an appointment with a beech tree, or a yellow birch, or an old acquaintance among the pines.

"As I walked over the long causeway made for the railroad through the meadows, I encountered many a blustering and nipping wind, for nowhere has it freer play.

"Sometimes, notwithstanding the snow, when I returned from my walk at evening I crossed the deep tracks of a woodchopper leading from my door, and found his pile of whittlings on the hearth, and my house filled with the odor of his pipe.

"Walden, being like the rest usually bare of snow, or with only shallow and interrupted drifts on it, was my yard where I could walk freely when the snow was nearly two feet deep on a level elsewhere and the villagers were confined to their streets.

"and then suddenly pausing with a ludicrous expression and a gratuitous somerset, as if all the eyes in the universe were eyed on him—for all the motions of a squirrel, even in the most solitary recesses of the forest, imply spectators as much as those of a dancing girl—wasting more time in delay and circumspection than would have sufficed to walk the whole distance—I never saw one walk—and then suddenly, before you could say Jack Robinson, he would be in the top of a young pitch pine, winding up his clock and chiding all imaginary spectators, soliloquizing and talking to all the universe at the same time—for no reason that I could ever detect, or he himself was aware of, I suspect.

"The ice in the pond at length begins to be honeycombed, and I can set my heel in it as I walk.

"I delight to come to my bearings—not walk in procession with pomp and parade, in a conspicuous place, but to walk even with the Builder of the universe, if I may—not to live in this restless, nervous, bustling, trivial Nineteenth Century, but stand or sit thoughtfully while it goes by."

I extracted the text by running this on the HTML version from Project Gutenberg:

Array.prototype.slice
	.call(document.querySelectorAll('p'))
	.map(function(p) { 
		return p.textContent;
	})
	.map(function(paragraph) { 
		return paragraph
			.split(/[\.\?\!\;]\s*/)
			.filter(function(sentence) { 
				return sentence.indexOf('walk') > -1 
					&& sentence.indexOf('I ') > -1;
			});
	})
	.filter(function(sentences) {
		return sentences.length;
	})
	.map(function(sentences) {
		return sentences
			.join('. ')
			.replace(/\n/g, '')
			.replace(/\s+/g, ' '); 
	})
	.join('.\n\n');

My favorite records from 2014

2015-01-13T00:00:00Z

In no particular order:

Album	♫
Mogwai – Rave Tapes	♫
A Winged Victory for the Sullen – Atomos	♫
Scott Walker + Sunn O))) – Soused	♫
Sharon Van Etten – Are We There	♫
This Will Destroy You – Another Language	♫
Fennesz – Bécs	♫
Flying Lotus – You're Dead!	♫
Caribou – Our Love	♫
Blonde Redhead – Barragán	♫
Aphex Twin – Syro	♫
Timber Timbre – Hot Dreams	♫
The War on Drugs – Lost in the Dream	♫
Plaid – Reachy Prints	♫
Amen Dunes – Love	♫
Strand of Oaks – HEAL	♫
Grouper – Ruins	♫
Jon Hopkins – Asleep Versions	♫
Ben Frost – A U R O R A	♫
Jóhann Jóhannsson – McCanick OST	♫
Leyland Kirby – We drink to forget the coming storm
Vivaldi Recomposed by Max Richter (reissue)	♫
Steve Reich – Radio Rewrite	♫
Inventions – Inventions	♫
Lisa Gerrard – Twilight Kingdom	♫
Locust – After the Rain	♫
Kyle Bobby Dunn – Kyle Bobby Dunn and the Infinite Sadness	♫
Various Artists – Pop Ambient 2015	♫
Gazelle Twin – UNFLESH	♫
Rhyton – Kykeon	♫
Andy Stott – Faith In Strangers	♫
Neel – Phobos	♫
Lubomyr Melnyk – Evertina	♫
Tujiko Noriko – My Ghost Comes Back	♫
Hildur Guðnadóttir – Saman	♫
Mike Weis – Don't Know, Just Walk	♫
Philip Corner – Satie Slowly	♫
Klara Lewis – Ett	♫
Wovenhand – Refractory Obdurate	♫

+ a couple of year-end lists to catch up with:

Timeline of favorite records: 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025.

Recently: Oldies

2014-11-07T00:00:00Z

Reading

Simon Reynold's Retromania: Pop Culture's Addiction To Its Own Past explores the recent phenomenon of near-past nostalgia.

Listening

I got the Beatles in Mono version of Revolver the other day, in part because it was there in the bookstore but also because I love Tomorrow Never Knows, which you might remember from, you know, every Chemical Brothers song, ever.

A note inside the sleeve reads:

This album was cut for vinyl from the original master tapes by using a completely analogue signal path and with constant reference to the notes made by the cutting engineer for the first pressing of the LP. It has been made with current technology and without imposing the restrictions necessitated by the limitations of record players in the 1960s. Consequently, this version reveals more of the content of the audio on the master tapes.

It's just an incredible album. Oh and the fact that it's universally recognized as one of the essential records of the 20th century makes its track-by-track, meticulously researched Wikipedia page an exquisite read.

On the same trip I got Sons of the Wind, "a sound journey along the Danube [featuring] recordings from Gypsy villages in Ukraine, Moldavia, Romania, Bulgaria, Macedonia, Serbia, Hungary, Slovakia, Austria". Its haunting cover (shown above) stopped me in my tracks and ultimately convinced me to give it a listen despite not knowing what's inside. I was expecting the usual Gypsy music compilation but instead I was greeted by a sound poem mixing field recording, ambient music, spoken word, acapella vocals and traditional instruments. This is design at its best: turning my attention to something I would have otherwise ignored, and then blowing my socks off in exchange of my trust.

This video by Soundwalk Collective gives you an idea.

There's also a three-part radio essay by Virginie Luc, who wrote the texts for the project.

Linked: Erik Satie

2014-10-24T00:00:00Z

Linked is where I rummage through my notes and bookmarks for bits and bobs around a subject.

"My only nourishment consists of food that is white: eggs, sugar, shredded bones, the fat of dead animals, veal, salt, coco-nuts, chicken cooked in white water, mouldy fruit, rice, turnips, sausages in camphor, pastry, cheese (white varieties), cotton salad, and certain kinds of fish (without their skin). I boil my wine and drink it cold mixed with the juice of the Fuschia. I have a good appetite but never talk when eating for fear of strangling myself."

— Erik Satie, A Day in the Life of a Musician (via UbuWeb)

Erik Satie was fond of invented musical taxonomy: gnossiennes, gymnopédies, vexations, ogives. His concept of furniture music was essential to the development of minimalist and ambient music. And shitty elevator music.

Branka Parlić's unhurried pace — what I imagine Satie meant when he instructed the performer to play the pieces lent et douloureux (slowly, sadly, gravely) — has pretty much ruined other renditions for me: they come off as sloppy and hasty in comparison. I've probably listened to her album Initiés '88 - Initiés '99 a hundred times. Sadly, it's been out of print for a while, so no chance to get it in a physical format. Next, listen to her play piano works by Philip Glass to convince yourself you should buy her latest album.

Eisoptrophobia translates as "fear of, or aversion to, reflections", the light version of which has possibly been impressed upon me by the seriously unsettling mirror scene in the film Below that resulted in this ominous undertone to any mirror gazing ever since. But it's also the name of an album by Akira Rabelais who crafts distorted, shimmering pieces based on music by Satie, Bartók and Carté.

"The smallest work by Satie is small in the way that a keyhole is small. Everything changes when you put your eye to it--or your ear."

— Jean Cocteau

Further down the distorsion spectrum, we've got Bionulor a.k.a. Sebastian Banaszczyk's Erik, a reworking of Satie's Gymnopédies that Luke Turner accurately describes as "the sound of a hangover inside Brian Eno's splendid dome after he's had a terrible sherry-fuelled row with William Basinski..."

Finally, in what could have been an early Christmas, it seems that every contemporary piano player I know about and listen to is featured on the compilation Erik Satie et les nouveaux jeunes. We've got Max Richter, Rachel Grimes, Sylvain Chauveau, Hauschka, Eluvium, Dustin O'Halloran, Nils Frahm, all the cool kids. The original is out of print, but some sort of reissue is going on. Fingers crossed!

Recently: living in cold places

2014-10-22T00:00:00Z

Reading

Consolations of the Forest: Alone in a Cabin in the Middle Taiga by Sylvain Tesson, a journaled account of the six months he lived in a small cabin next to lake Baikal in Siberia. I'm reading it in Romanian but the English version and has a much nicer cover.

Thinking about expanses of snow and ice reminded me of this essay from The Morning News about a dog sled race across the tundras of Russia.

And on a completely different scale, the Lykov family spent 40 years in complete isolation before being discovered in 1978 by a group of geologists. Agafia Lykov, the last surviving member of the family, still lives there.

Watching

Happy People: A Year in the Taiga, a documentary put together and narrated by Werner Herzog based on footage by Dmitry Vasyukov that I wanted to watch for a while sounded like a good complement to Tesson's book. (It was.)

Listening

Soused, a collaboration between Scott Walker and Sun O))) sounds like boiling tar, anvils and nightmare fuel. In other words, it's perfect and I can't stop listening to it.

Atomos by A Winged Victory for the Sullen is the much anticipated follow-up to their excellent self-titled debut and it might very well be my favorite record of the year.

Flying Lotus' latest offering, You're Dead!, is denser than his previous album but maintains the latter's dreamlike haze and submerged thumps.

Now seems like the perfect time to give Zola Jesus' Taiga a listen.

How to create a SVG icon system

2014-10-17T00:00:00Z

Wherein I describe a pretty nice workflow for creating and maintaining an SVG icon set that will make it easy to tweak/extend your set of icons in the comfort of your favorite vector graphics application (as long as your favorite vector graphics application happens to be Adobe Illustrator) while at the same time providing the tools to generate the SVG assets automatically.

The gist:

Keep your icons in a single .AI file with multiple artboards, and export each artboard as SVG;
Use grunt-svgstore to clean up and merge the SVG files and grunt-svginjector to generate a JavaScript file that you can use to inject the SVGs into your page;
Write minimal CSS to lay out and color your icons;
Enjoy the awesomeness of crisp, responsive icons.

Let's do this.

The case for SVG icons

People in the ongoing discussion around the best way to use icons in websites and web apps tend to agree that SVG is the optimal solution in many cases. I won't cover it here, but Chris Coyier's article explains well why we want to define our icons as named <symbol> elements that we can then reference like this:

<svg class="icon">
	<use xlink:href="#icon-iconName" />
</svg>

Design your icons

To work on your icons side by side and have them neatly packaged in a single .AI file, use multiple artboards--one for each icon in your set.

In the New Document screen, enter the number of artboards and choose other sensible settings (e.g. ✓ Align New Objects to Pixel Grid)

In the Artboards pane (if it's not shown, go in and check Window → ✓ Artboards) you can add, remove and rearrange the artboards in your file. Make sure each artboard has the appropriate name, as this will ultimately become the name of your icon in your icon set.

Pro tip interlude

Whenever possible, it's a good idea to make your icon a single compound path, which basically takes the various <path>, <rect>, <polygon> etc. elements and merges them into a single <path>. This gives you a slimmer SVG and you'll avoid Firefox rendering quirks — I've seen it antialias some of the paths and leave others aliased and it just makes the icon look half-assed which is super depressing.

In Illustrator, you create a compound path by selecting your shapes and hitting ⌘8 on your keyboard. Use ⌥⇧⌘8 to release a compound path if you find you need to make changes to individual paths. Both actions are accessible under Object → Compound Path.

Export time!

Fast-forward to the moment you're happy with the set of icons and/or working inside Adobe Illustrator becomes unbearable and it's time to export those babies as separate SVG files. Granted it's a bit obtuse, since we piggyback off the Save a copy... functionality to obtain that which might more accurately be described as an export, but I haven't found a more straightforward way to do it:

File → Save a copy… → Format: SVG (svg), Use artboards: All

On the SVG Options screen the default settings (i.e. Profile: SVG 1.1) are fine. Each artboard will be saved as a separate SVG file with the name fileName_artboardName.svg.

Clean up and package the icons

Next, we take all the little individual SVG files and package them into a single SVG file. For that we will need Grunt and a plugin called grunt-svgstore. If you haven't used Grunt before, you can check out this short introduction.

Here's how our Gruntfile should look:

module.exports = function (grunt) {
	grunt.loadNpmTasks('grunt-svgstore');
	grunt.initConfig({
		svgstore: {
			icons: {
				files: {
					'icons.svg': ['icons/*.svg']
				},
				options: {
					/*
            prefix all icons with an unambiguous label
          */
					prefix: 'icon-',

					/* 
            cleans fill, stroke, stroke-width attributes 
            so that we can style them from CSS
          */
					cleanup: true,

					/*
            write a custom function to strip the first part
            of the file that Adobe Illustrator generates 
            when exporting the artboards to SVG
          */
					convertNameToId: function (name) {
						return name.replace(/^\w+\_/, '');
					}
				}
			}
		}
	});
};

Next we need a way to include the icons.svg file in our web page. Rather than copying the content and inlining it in our HTML, we can include it via a <script> tag (making it easier to maintain and a candidate for browser caching), for which we can use grunt-svginjector:

module.exports = function (grunt) {
	grunt.loadNpmTasks('grunt-svgstore');
	grunt.loadNpmTasks('grunt-svginjector');

	grunt.initConfig({
		svgstore: {
			icons: {
				files: {
					'icons.svg': ['icons/*.svg']
				},
				options: {
					cleanup: true,
					convertNameToId: function (name) {
						return name.replace(/^\w+\_/, '');
					}
				}
			}
		},
		svginjector: {
			icons: {
				files: {
					'icons.js': ['icons.svg']
				},
				options: {
					container: 'icon-container'
				}
			}
		}
	});

	grunt.registerTask('icons', ['svgstore:icons', 'svginjector:icons']);
};

In our HTML we need a container into which we'll inject the content of icons.svg and then we can just include the script:

<div id="icon-container"></div>
<script src="icons.js"></script>

Note: Since the script inserts the content immediately, you must make sure the script is always included after the container in your DOM.

We've registered a task called icons to execute the svgstore and svginjector steps in order, so we can run:

$ grunt icons

...to prep our icons for usage.

Use and customize your icons

Some final touches and we're done. Firstly, we need to hide the icon container so it does not take space in the layout.

Remember that we set cleanup: true in grunt-svgstore to strip all presentational attributes like fill, stroke or stroke-width. This is a necessity if we want to control these attributes from our CSS, since no attribute defined inside the <symbol> elements can be overridden when we <use> them. To make sure everything looks okay, we'll define a stroke and a fill for the icons.

/* 
  Hide the icon container, because the injected SVG 
  takes up physical space.
*/
#icon-container {
	display: none;
}

/*
  Set up the size, layout and colors.
*/
.icon {
	display: inline-block;
	width: 2em;
	height: 2em;
}

.icon use {
	stroke: #000;
	fill: none;
}

Then, as promised, whenever you need to use an icon on your web page:

<svg class="icon">
	<use xlink:href="#icon-myicon" />
</svg>

Easy.

Dan Cătălin Burzo: Articles

HTTP caching, a refresher

What’s fresh?

Going past expiration

How caches store responses

Variable responses and the Vary response header

Your mileage may vary

Deduplicating responses with the No-Vary-Search response header

Cache-Control response directives

max-age=<number>

must-revalidate

no-cache

no-store

must-understand

private

public

s-maxage=<number>

proxy-revalidate

no-transform

stale-while-revalidate=<number>

stale-if-error=<number>

Cache-Control request directives

max-age=<number>

max-stale=<number>

min-fresh=<number>

no-cache

no-store

no-transform

only-if-cached

stale-if-error=<number>

Browser refresh mechanisms

Soft reloads

Hard reloads

The immutable response directive

Caching responses to authenticated requests

Conclusion

My favorite records from 2025

My favorite records from 2024

My “Skip to content” markup was breaking the back button on iOS

The problem: <main tabindex=-1> loses your scroll position

The solution: to be discussed

How to think about HTML responsive images

What’s a responsive image?

Level 1: one image, one resolution

Level 2: one image, many resolutions

Level 3: dynamic image density

Level 4: the <picture> element

The type attribute

The media attribute

Level 5: art direction

Extra credit: lazy images with sizes=auto

How browsers choose one image

Density descriptors in srcset

Width descriptors in srcset

Conclusion

Changelog

My favorite records from 2023

Heavy rotation

On the radar

Other things

So you want to add a web feed

Use the Atom format

Good IDs

Date format

HTML content

Absolute links

Check that the feed is valid

Put the feed on your server

Link to the feed in HTML

Next steps

Further reading

Slotted content in Eleventy

Adding slotted content to Eleventy

Step 1: Add slots data to each page

Step 2: Register the slot shortcode

Step 3: Use the Eleventy Render plugin

Conclusion

Sass in Eleventy, with versioning

Producing content hashes

Adding support for Sass with content hashing in Eleventy

Variable responses and the `Vary` response header

Deduplicating responses with the `No-Vary-Search` response header

`max-age=<number>`

`must-revalidate`

`no-cache`

`no-store`

`must-understand`

`private`

`public`

`s-maxage=<number>`

`proxy-revalidate`

`no-transform`

`stale-while-revalidate=<number>`

`stale-if-error=<number>`

`max-age=<number>`

`max-stale=<number>`

`min-fresh=<number>`

`no-cache`

`no-store`

`no-transform`

`only-if-cached`

`stale-if-error=<number>`

The `immutable` response directive

The problem: `<main tabindex=-1>` loses your scroll position

Level 4: the `<picture>` element

The `type` attribute

The `media` attribute

Extra credit: lazy images with `sizes=auto`

Density descriptors in `srcset`

Width descriptors in `srcset`

Step 1: Add `slots` data to each page

Step 2: Register the `slot` shortcode

Uses for the `lh` unit

Let's reimplement `FormData` for some reason

Let's use `formDataMap()`

A first good thing to do is add all the necessary properties to the `@font-face` declaration

A note on `format()` in the `src` descriptor

1. Normalizing `wheel` events

2. Generating gesture events from `wheel` events

3. Converting the wheel delta to a `scale`