DEV Community: MinSoo Kim

The comparison operator that returns true when there is nothing to compare

MinSoo Kim — Fri, 25 Sep 2026 12:02:49 +0000

I've been trying to add a "block the checkout if this rule matches" feature to a Shopify app I run, and I nearly shipped something that would have blocked every single cart in a store. Not some carts. All of them. The bug was one line long and it was already in production, doing something perfectly reasonable, and you'd have to squint to see anything wrong with it. Let's go through it, because I think the shape of it is a lot more common than the specific code, and you probably have one of these somewhere too.

Quick context so you can follow. The app has a small rules engine: 15 kinds of conditions (shipping country, cart total, product, customer tag, whether the address looks like a PO box, that sort of thing), written once in TypeScript and shared between the checkout function that runs as wasm and the rule tester inside the app. The two existing targets use those rules to hide a payment method or to rename a delivery option. The new work was supposed to be small: same condition vocabulary, one more output, "block". Easy, right? I thought so.

Where the function runs

So this is the part I didn't know. Shopify's Cart and Checkout Validation Function is not a checkout-only thing. It runs at 3 points in the buyer's journey: CART_INTERACTION, CHECKOUT_INTERACTION and CHECKOUT_COMPLETION.

The existing two targets only ever ran inside checkout, and the worst they could do to a buyer was hide a payment method a bit early or rename a delivery option. So for as long as that engine has been running, a wrong answer on a cart with no country had never cost anyone a sale. But at the cart stage there is no address yet. Nobody has typed one. And now the wrong answer would stop the sale. Obvious in hindsight? Completely. Did I think of it? I did not.

That is the whole bug, really. The rest is just working out which line it will land on.

The line

Our comparison operators don't fail closed. The not_in branch explicitly returns true when the value is missing. This isn't me guessing after the fact; it's what the code says:

// shared/rules-engine/evaluate.ts
case "not_in":
  return a === undefined || !list.includes(a);

Read that with a merchant's rule in mind: "block if the shipping country is not in [US]". On a cart with no address, a is undefined, so the operator says yes, the country is not in the list, then the rule matches, then the cart gets blocked. And at the cart stage every cart looks like that. From the moment a merchant turns that rule on, nobody will be able to get past the cart. What's the logic in that? There isn't any; it's just what the code does when you ask it to answer a question it wasn't built to answer.

I want to be precise about what actually happened, because "blocked every order" is the kind of sentence that gets repeated. This lived on a branch (feat/validation-rules). It never reached a merchant. The live app can't block anything and still has its 15 conditions. But if I had shipped the branch as it stood, that is what it would have gone on to do.

4 of the 15 conditions read the address: country, province, zip and po_box. The branch adds 4 more address-shaped ones (length, whether there's a street number, contains-string, non-Latin characters), so on the branch it's 8 of 19 that depend on something a cart doesn't have yet.

Why the obvious fixes don't work

So my first thought was the obvious one: make not_in return false when the value is missing. Fail closed, done. Right?

But that operator is not mine to change any more. It's shared with the two targets that are already live, and merchants have built their rules on top of what it does today. Flip the operator and I'd be changing the behaviour of software that merchants have configured and rely on, to fix a feature nobody is using yet. I'm not going to do that.

Second thought: use buyerJourney.step and just skip address rules at CART_INTERACTION. That's what the API is giving you the step for, surely? Surely?

It's not enough. The address can also be empty during checkout, before the buyer has got round to filling in the address form. So a rule can be evaluated at CHECKOUT_INTERACTION with the same missing value and the same wrong true. Filtering by step fixes the cart case and then leaves the checkout case exactly as broken as before.

What I did instead

So the engine now refuses to answer instead of guessing, which I'm pretty happy with. Any rule that needs an address is held until the cart actually has one, and the function decides that by looking at the cart, not at which step it is on.

export const ADDRESS_CONDITION_FIELDS: ConditionField[] = [
  "country", "province", "zip", "po_box",
  // …plus the 4 address-shape conditions (length, street number, contains, non-Latin)
];

export function ruleNeedsAddress(rule: Rule): boolean {
  return rule.conditions.some((c) => ADDRESS_CONDITION_FIELDS.includes(c.field));
}

// Function side. Not buyerJourney.step: does the cart have an address or not.
const addressKnown = (input.cart.deliveryGroups ?? []).some(
  (group) => !!group.deliveryAddress?.countryCode,
);
const { errors } = evaluateValidation(config, ctx, { addressKnown });

The rule tester inside the app doesn't take a default. It works out addressKnown from what the merchant actually typed: if they filled in a country, the rule is evaluated; if they left it blank, it shows "waiting for address" rather than silently matching, which is the same thing the checkout does, just made visible to them.

And there are regression tests pinning both directions now: cart stage with no address lets the cart through, checkout stage with an address blocks it. The original 4 (country, province, zip, po_box) never get evaluated on an address-less cart at all, because ruleNeedsAddress holds the whole rule first. The 4 new address-shape conditions have their own test, and one sentence I made it say out loud, because it's the sentence I got wrong: on a cart with no address, all 4 of them answer "no", including the negative forms (not_in, not_set). 173 tests pass on the branch.

The bit that generalises

The same operator is safe when the worst it can do is hide a payment button, and dangerous when it can stop a sale. Nothing about the operator changed between those two sentences. The thing that changed is how the caller reacts to a true. Is the operator wrong, then? I don't think it is. Is it dangerous? Obviously, in the right place.

So "fail open or fail closed?" isn't a property of the comparison. It's a property of the comparison plus whoever is holding the result. An engine that returns true for "I don't know" has a blast radius decided entirely by its callers, and when you reuse it somewhere new you're not just importing the vocabulary of conditions. You're importing the execution context that vocabulary was written in, and here that context was "the worst a wrong answer can do is hide a button". It wasn't written down anywhere. It was just true, until it wasn't.

I don't have a clever rule for catching this in general, sorry. The honest version is: when a shared function gets a new caller, go and read every branch that handles missing input, one by one, and ask yourself what the new caller will do with each answer. Then write that down. It's boring, but it would have been a lot more expensive to learn after launch.

Anyway, the branch is still a branch, and if you've got a shared rules engine of your own, I'd really go and read its missing-value branches this week. It gets the last checks (typegen, wasm build, a dev store run-through) before it goes anywhere near a real merchant, and now I'm slightly more nervous about the other 11 conditions than I was last week, which is probably the correct amount of nervous.

Why CookieMop waits 15 seconds after you close a tab, and why that is the hard part in Manifest V3

MinSoo Kim — Sat, 19 Sep 2026 12:03:56 +0000

CookieMop is a Chrome extension that deletes a site's cookies when you close its last tab, unless the site is on your whitelist. One sentence of product. The interesting engineering is in three words of that sentence: "last", "close", and the delay hiding between them.

Why not delete immediately

Closing a tab by accident is common, and cookies are what keep you logged in. So the extension does not clean on the close event. It schedules a cleanup 15 seconds later (the default; users can change it, and zero means immediate) and only then checks whether the site is still gone. Reopen the tab within the window and the pending cleanup is cancelled. One Playwright test exists for exactly that path: revisiting the site during the delay cancels the cleanup.

That sounds like a setTimeout. In Manifest V3 it cannot be only a setTimeout.

The service worker will not wait for you

In Manifest V3 the background script is a service worker, and Chrome can terminate it whenever it is idle. A timer living inside a worker that gets killed at second 9 of a 15-second wait never fires. The old Manifest V2 answer, a persistent background page, is gone.

The tool Chrome offers instead is chrome.alarms, which survives the worker being unloaded. It has one catch that shaped the whole design: alarms are clamped to a minimum of 30 seconds. A 15-second delay cannot be expressed as an alarm.

So the extension does both. While the worker is alive, a plain timer fires the cleanup on time. In parallel, every pending cleanup is written to storage with its fireAt timestamp, and one alarm is set for the earliest of them, pushed out to at least 30 seconds if needed:

const ALARM_MIN_MS = 30_000; // Chrome clamps MV3 alarms to a 30 s minimum
const earliest = Math.min(...pendings.map((p) => p.fireAt));
chrome.alarms.create(ALARM_NAME, { when: Math.max(earliest, now + ALARM_MIN_MS) });

If the worker lives, the timer wins and the alarm finds nothing to do. If the worker dies, the alarm wakes a fresh worker, which reads the pending list from storage and processes whatever is due. There is a test for that too: kill the service worker, and the alarm still fires the pending cleanup. The cost of the fallback is that a cleanup can land at 30 seconds instead of 15 when Chrome happened to unload the worker. I decided that late is fine and never is not.

"Last tab" means last tab of the site, not the page

The second word. If you have mail.google.com in one tab and docs.google.com in another, closing one must not log you out of the other. So the unit of tracking is not the hostname but the registrable domain, the eTLD+1: mail.google.com becomes google.com, and a.b.example.co.uk becomes example.co.uk.

Doing that properly means knowing which suffixes are "public", and the full Public Suffix List is thousands of entries. CookieMop ships no dependencies and no build step, so it carries a compact table of the common two-part suffixes instead: co.uk, co.kr, com.au, co.jp, 257 entries in total. A hostname ending in one of those needs three labels to be a site; anything else needs two. IP addresses and single-label hosts like localhost are left as they are. It is not the whole list, and I would rather say that here than pretend. It covers the cases people actually log in to.

The same table decides the lists. A whitelist rule on a subdomain survives a cleanup of its parent domain, and a more specific whitelist entry beats a greylist entry. Greylisted sites are the third state: they survive tab close and are cleaned when the browser restarts, in a startup pass that runs before you have opened anything.

The race nobody sees

There is a comment in the background script that I keep because it cost an afternoon. Recording a tab's domain on tabs.onUpdated and taking it back on tabs.onRemoved are both async read-then-write round trips to storage. If a tab is opened and closed fast enough, the "remove" read can overtake the still-pending "record" write, and the extension thinks a site was never open. The fix is a small promise queue that serializes every tab-record read and write, and the reason it is worth writing down is that it never shows up in manual testing. It shows up in a Playwright run that opens and closes tabs faster than a person can.

What "clean" means

By default only cookies are removed. The user can widen the scope to localStorage, or to all site data: IndexedDB, CacheStorage and service worker registrations, through chrome.browsingData. Widening it is a real trade-off, because the same storage that tracks you also holds a half-written draft on some sites, so the narrower default stays.

Everything runs locally. The extension makes no network requests, has no accounts and no analytics, and the repository on GitHub is the code that ships to the store. If you want to check the timer logic yourself, src/background.js is about 430 lines and the alarm fallback is the part worth reading first.

Have you ever lost a login to a tab you closed by mistake, or is 15 seconds too long for the way you browse?

The extension is here: https://chromewebstore.google.com/detail/nbehnialaodjcffgjkckbnocggbdmdel

Sources

chrome.alarms API, minimum alarm period in Manifest V3: https://developer.chrome.com/docs/extensions/reference/api/alarms
Extension service worker lifecycle (idle termination): https://developer.chrome.com/docs/extensions/develop/concepts/service-workers/lifecycle
Public Suffix List, what "registrable domain" means: https://publicsuffix.org/
CookieMop source, the exact code shipped to the Chrome Web Store: https://github.com/thoopring/cookiemop

The 10 percent that bought nothing: what a flooring calculator should actually tell you

MinSoo Kim — Wed, 16 Sep 2026 12:02:49 +0000

Wall Math is a set of three small calculators: paint, wallpaper, flooring. The flooring one is the simplest arithmetic on the site and the one that taught me the most about what a calculator owes its user. The whole engine function is nine lines. Here is the part that matters:

const requiredArea = area * (1 + extra / 100);
const boxes = Math.ceil(requiredArea / perBox);
return {
  area, requiredArea, boxes,
  purchasedArea: boxes * perBox,
  excessArea: boxes * perBox - area,
  roundingExtra: boxes * perBox - requiredArea,
};

Area, allowance, divide by the carton, round up. Every flooring calculator on the internet does this. The difference is in what gets returned, and the two extra fields at the bottom are the reason this post exists.

Two kinds of "extra"

When you buy flooring you always take home more than your floor. There are two reasons, and they are not the same kind of thing.

The first is the allowance you chose for cuts, mistakes and a spare plank or two. Ten percent is the number people repeat. It is a decision, and it is yours.

The second is that cartons come in fixed sizes. You cannot buy 3.86 cartons, so you buy 4, and the last carton's remainder lands on your garage floor whether you wanted it or not. That is not a decision. It is arithmetic.

Most calculators add these together and show one number: "you need 4 boxes." The user then reads that as "my 10 percent allowance is included," which is true, and concludes the allowance did something, which is often false.

The worked example that changed the output

A 12-by-15 foot living room is 180 square feet. Take three vinyl plank products from one manufacturer, all cut to the same 7-by-48-inch plank, with cartons of 51.33, 23.64 and 18.91 square feet. Those three figures come from Shaw's own product pages, read on 2026-09-10, and the exact styles are listed in the sources below.

With a 10 percent allowance, the area to cover becomes 198 square feet:

Carton	198 ÷ carton	Buy	Coverage
51.33	3.86	4	205.32
23.64	8.38	9	212.76
18.91	10.47	11	208.01

Now run the same floor with no allowance at all: 180 ÷ 51.33 is 3.51, so still 4 cartons. The other two drop to 8 and 10.

For the largest carton, the 10 percent bought exactly nothing. Four cartons either way. That floor was already going to arrive with 25.32 square feet spare, because you cannot buy three and a half cartons, and 25.32 is more than the 18 square feet that a 10 percent allowance on 180 square feet adds. The rounding had already handed you more than the allowance was ever going to.

On the smallest carton, the same 10 percent is the difference between 10 and 11 cartons. Real money, and also real safety, since dropping it leaves 9.10 square feet spare instead of 28.01.

Same room. Same rule of thumb. It costs a carton in one case and zero in another, and the thing that decides which is a number printed on the side of the box that most people have never looked up.

What the calculator returns now

So the result object separates them. excessArea is everything above the measured floor. roundingExtra is only the part above the area you asked for, the part you could not have avoided at that carton size. The page shows both, and a small chart on the rounding guide draws three bars for a 120 square foot floor: the floor, the floor with 10 percent, and what you actually buy in 23.64 square foot cartons. At 0, 10 and 15 percent allowance that floor is 6 cartons every time. Six, six, six. The allowance slider moves and the answer does not.

I think that is the single most useful thing the page does. Not the count. The count any spreadsheet can produce. The useful part is telling someone, before they drive to the store, that the decision they are agonising over changes nothing for their carton, or that it changes exactly one carton and here is what that carton buys them.

Nobody upstream publishes the 10 percent

We went looking for where the rule comes from. Shaw's vinyl planning and installation page and its flooring overview page, both read on 2026-09-10, state no waste or overage percentage and give no quantity guidance at all. What they do say is to "always work from multiple cartons to achieve a uniform appearance," which is worth knowing if your plan was to open one box at a time and return the rest.

So the calculator labels the allowance as the user's input, not a recommendation. The assumption string in the result says so in plain words, and the page repeats it. Which number did you assume was a rule the last time you bought flooring?

Checking arithmetic you publish

Every worked number in the guides, including the 0 to 15 percent allowance table, was computed by hand and matched against the engine's regression tests before the pages went live. That is slow, and it is the only way I know to publish a table of numbers under my own name without flinching. The whole formula fits on one line: floor area × (1 + allowance) ÷ square feet per carton, rounded up. The work is in saying which part of the answer was your choice.

The calculator is here: https://www.wallmath.com/flooring-calculator/

Sources

Shaw Prime Plank, style 0616V: 51.33 sq ft per carton, 7 in × 48 in planks: https://shawfloors.com/en-us/vinyl/prime-plank-greyed-oak-7-/0616v-00532
Shaw Distinction Plus, style 2045V: 23.64 sq ft per carton: https://shawfloors.com/en-us/vinyl/distinction-plus-barrel-oak-7-/2045v-07066
Shaw Paladin Plus, style 0278V: 18.91 sq ft per carton: https://shawfloors.com/en-us/vinyl/paladin-plus-fresh-pine-7-/0278v-05052
Shaw vinyl planning and installation page, no waste percentage stated (read 2026-09-10): https://shawfloors.com/en-us/plan-and-install/vinyl
Wall Math rounding guide (allowance vs whole-box rounding): https://www.wallmath.com/flooring-boxes/

The checkout never calls our server: how HideKit's rules run inside Shopify

MinSoo Kim — Mon, 14 Sep 2026 12:03:29 +0000

HideKit is a small Shopify app. A merchant writes rules like "hide cash on delivery for orders under ₩100,000 shipped to Korea" or "rename Standard Shipping to Ground for US addresses", and the checkout follows them. If ten thousand merchants installed it tomorrow, our server would not get one extra request at checkout time. That is the part I want to explain, because it decided almost everything else about how the app is built.

Where the rules live

The rules do not live in our database. They live in one JSON document in a Shopify metafield attached to the merchant's payment customization, under the namespace $app:payment-rules with the key function-configuration. A second customization holds the delivery rules. Our admin app writes to that metafield, and nothing else of ours is involved after that.

At checkout, Shopify runs a Function. Ours targets cart.payment-methods.transform.run, and a sibling targets cart.delivery-options.transform.run. Shopify hands the function an input it asked for in a GraphQL query: the cart total and currency, discount applications, the buyer's company if it is a B2B checkout, the customer's amount spent, order count and tags, the delivery address down to province and zip, each line's weight and collection membership, and the checkout language. The function reads the metafield, evaluates the rules against that input, and returns a list of operations: hide this method, rename that one, move this one to a different position. Three operation types, one metafield read, zero network calls. That is the whole runtime. If our servers are down, the checkout does not notice.

The function is compiled to WebAssembly and executed by Shopify, so the engine had to be plain TypeScript with no I/O. That constraint turned out to be a gift.

One engine, two callers

Because the engine is a pure module, shared/rules-engine, the admin app can import the same code. HideKit has a page called the Rule Tester where a merchant types in a cart: country, total, products, tags, and a list of payment methods (the default is three: cash on delivery, credit card, bank deposit). The page runs the merchant's saved rules through the same evaluateRules function the checkout uses and shows which rules fire and what each method would look like. No test orders, no fake customers, and no chance that the tester and the checkout disagree, because there is only one implementation.

"Why isn't it hidden?" is the support question every app in this category gets. The tester exists so the merchant can answer it themselves before a customer ever sees the checkout. Which method do your customers keep picking that you wish they wouldn't? That is usually the first rule a merchant writes.

Testing a thing you cannot step through

You cannot attach a debugger to a function running inside Shopify's checkout. So the tests run the compiled wasm against fixtures. There were 89 tests in the suite at the last count I wrote down, including an 18-case condition matrix run through the wasm build and boundary fixtures such as a rule at 20 with carts at 20 and 19.99, because "greater than or equal" is exactly the kind of thing that gets flipped in a refactor.

The end-to-end check was done by hand on a development store with a rule that reads "country is KR AND total is at least ₩100,000": a ₩58,000 cart showed cash on delivery, a ₩116,000 cart hid it. Boring, and the only proof that matters.

The incident that became a smoke test

Cleaning up a development preview once removed the payment customization that owned the metafield. The rules were still visible in the merchant's admin, pointing at an owner that no longer existed. The fix was to recreate the customization with the released function's ID, and doing it through the app's own UI turned the fix into a full pass of the create path: UI to server to the customization-create mutation to metafieldsSet. It is the most useful bug we have had, because it forced the exact flow a new merchant goes through.

What the architecture cannot do

Living inside Shopify means living with Shopify's limits, and we list them in the app instead of discovering them with a merchant. On non-Plus stores, checkout does not allow hiding the Shopify Payments gateway itself; only individual methods like cash on delivery or manual payments can be hidden. There is also a known checkout bug where a customer who selected a method that then becomes hidden can get stuck, so onboarding flags it up front. Two limits, both written on the listing, because a refund request is a worse place to learn about them.

I would build it this way again. The rules being the merchant's data, in their store, evaluated by the platform, is not only a nice property for uptime. It means uninstalling the app leaves nothing behind in the theme, and it means the thing the merchant tests is the thing that runs.

If you want to see the tester, the listing is here: https://apps.shopify.com/hidekit.

Sources

Payment customization function target: https://shopify.dev/docs/api/functions/reference/payment-customization
Delivery customization function target: https://shopify.dev/docs/api/functions/reference/delivery-customization
Shopify Functions overview (WebAssembly execution, input queries): https://shopify.dev/docs/apps/build/functions
HideKit listing, including the platform limits section: https://apps.shopify.com/hidekit

Why our product data pipeline refuses Amazon as a source

MinSoo Kim — Sat, 12 Sep 2026 12:03:46 +0000

I run a small site called Inch & Drawer. It answers one question: will this kitchen organizer actually fit in your drawer or cabinet? You type your inside measurements, and the site compares them against the published dimensions of every product it lists. Ten are live right now. Five more sit in draft.

That sentence hides the whole problem. "Published dimensions" is doing a lot of work. Where do the numbers come from, and how do I know they describe the exact product someone might buy?

Here is the rule set we ended up with, and the two bugs that shaped it.

Two sources, and Amazon is never one of them

Every product record needs two independent pages that agree on the model. The dimensions that get published on the site can only come from two kinds of pages: the manufacturer's own product page, or a retailer listing that prints the numbers itself.

Amazon pages are allowed in the record, but only as evidence for the model match. They never supply a published number. The site links to Amazon through the Associates program, and I did not want a page that earns a commission to also be the page that vouches for the measurement. Those are different jobs. Mixing them would have been the wrong call, and I'd rather list ten products with traceable numbers than fifty with numbers I copied from a marketplace.

Concretely, each product file carries a list of matched pages with a kind on each one: maker_site, retailer_listing, brand_storefront, amazon_listing. The importer on the site side only reads width, depth and height from the first two kinds. The other two can confirm "yes, this is the same model," and that is all they can do.

The fallback nobody looked at

The generator that builds these records had a fallback. If no evidence page was found for a product, it fell back to a URL from a targets file, so the record would at least point somewhere.

For one shelf riser, that fallback URL was an Amazon brand storefront. The rest of the pipeline treated it like any other source URL, and the record went out marked as importable. The site's catalog test caught it on the other side: it rejects any record whose source URL is on Amazon, drafts included. The importer had been stricter only for publishable records, so we tightened it to match the test.

The fix on the generator side was two lines of thinking. First, the fallback can no longer produce an Amazon URL. Second, there is now an assertion right before the file is written: if a primary source URL resolves to an Amazon domain, the write fails loudly. On its first run that assertion fired, which is how we found the fallback in the first place.

Midnight in the wrong time zone

Each record has a checked_at date. The site's freshness check reads that date as UTC midnight and refuses anything in the future. Our records are checked in Korea, nine hours ahead of UTC. Every morning between midnight and nine, a record checked "today" looked like it came from tomorrow, and the canary release failed on it.

We now write a full timestamp with the offset, checked_at_ts, next to the date. The importer converts that to a UTC date. If only the plain date exists, it takes the earlier of that date and today in UTC. Boring. It was also the only thing standing between the first automated product and the live site for about a day.

A sentence is not a number

One product page said the organizer needs a drawer that is "at least 3" high." The first import copied that whole sentence into the field meant for the printed value, so the card read like a quote inside a label. We changed it: the field holds the value as printed, 3", and the sentence lives in the evidence file that the card cites. Rules like "print the value, keep the sentence" are easy to write down and easy to forget. The importer now rejects any requirement value longer than 24 characters or without a digit, which is a crude way of saying "that's a sentence, not a number."

The pipeline reads pages logged out, at human speed, with a cap of 40 pages a day and a few seconds between requests. It is deliberately slow. Three products went live this week under these rules, and none of them needed a correction. The site publishes a handful of new products a week, and every one of them can be traced back to a page that printed the number.

If you want to see what the output looks like, the fit-check page is here: https://www.inchanddrawer.com/fit-check/. Each card shows where its dimensions came from, and marks the Amazon link as a paid link.

16 requests, 2 of them third-party, 0 ad requests (what a static calculator site actually loads)

MinSoo Kim — Thu, 10 Sep 2026 06:26:07 +0000

I wanted a calculator site that behaves like a document, not like a web app.

Type three numbers. Get the number of paint cans to buy. No account, no dashboard, no round trip to a server, no analytics watching you type. The page, the arithmetic, and the answer.

That one constraint decided almost every technical choice below, and it is also why the numbers are small enough to print in a table. Here is a cold load of wallmath.com, measured in a headless Chromium on 2026-09-10 against the live build:

What	Home page	Guide page
Total network requests	16	12
Requests to my own domain	14	10
Third-party hosts contacted	1	1
Requests to that host	2	2
Ad requests	0	0
Ad iframes	0	0
External stylesheets	0	0
HTML document	93,838 bytes raw, 26,621 gzipped	97,078 bytes raw

The one third-party host is pagead2.googlesyndication.com. It serves two script files and then stops, which is the part of this post I find most worth writing down.

Fonts: three files, subset, preloaded

Two families: Fraunces for headlines, Source Serif 4 for body text. Loading them from a font CDN would be one line of HTML. Instead they are three woff2 files on my own origin.

File	Bytes
`fraunces-700-800-latin.woff2`	36,620
`sourceserif4-400-600-latin.woff2`	50,824
`sourceserif4-italic-400-latin.woff2`	20,092

Three decisions kept that to 107,536 bytes total.

Variable fonts collapse the weight axis. Fraunces ships variable, so one file covers 700 and 800. Same for 400 and 600 in the body face. Six static files became two, and the two together are 87,444 bytes.

Latin subset only. The copy is English and contains no Cyrillic or Greek, so those ranges are cut. It is the largest single saving available and it costs nothing, because those glyphs would never render.

Each file sits in a <link rel="preload" as="font" type="font/woff2" crossorigin> in the head and @font-face uses font-display: swap, so the fetch starts in the same round trip as the document instead of waiting for CSS to parse.

The honest cost of self-hosting: I lose the shared-cache argument for CDN fonts. That argument is mostly gone anyway, because browsers partition the HTTP cache by top-level site, so a font your visitor already downloaded elsewhere does not help you.

CSS and JS live inside the document

There are no external .css or .js files at all. The build inlines 27,933 bytes of CSS and 45,164 bytes of JS into every page, spread over six <script> blocks, the largest of which is 24,877 bytes.

What it buys: first paint needs exactly one round trip. No stylesheet to discover, fetch and parse before anything renders. On guide pages, which are where search traffic lands, that is the difference between text appearing immediately and text appearing after a second request completes.

What it costs: no cross-page caching. Someone who opens three guides downloads the same CSS three times. Gzip softens it, since the whole document compresses from 93,838 bytes to 26,621, but it is a real cost and it grows with the site.

The number that decided it: the inlined document still compresses to under 30 KB. If the CSS doubled I would move it to a file and accept the round trip. I am not inlining on principle, I am inlining while the arithmetic says to.

The JS is larger than the CSS because it holds the calculation engine, which runs entirely in the browser. Nothing about a reader's room dimensions leaves the page. There is no endpoint to send it to.

Diagrams are SVG, illustrations are AVIF

The home page carries 15 inline <svg> elements: wall elevations, plan views, the can and box pictograms, and the room drawing whose walls change colour when you click a swatch. They come out of the same build that renders the HTML, from the same numbers the calculator uses, so a dimension change updates the drawing and the result together.

Inline SVG costs no extra requests and inherits the page's CSS custom properties for colour. The interactive part is DOM manipulation on those elements. No canvas, no chart library, no animation framework.

The illustrations are <picture> elements with an AVIF source and a WebP fallback, three widths each. What the browser actually fetched on a 1440px desktop view was the 480px AVIF files, because that is the size the cards render at:

Asset	Bytes
`calc-paint-480.avif` (what actually loaded)	11,221
`calc-paint-480.webp` (fallback tier)	18,514
`calc-paint-1200.avif`	42,493
`calc-paint-1200.webp`	78,512

I list the fallback numbers because it is easy to quote your largest file and call it your image weight. The file that ships to most readers here is the 11 KB one.

The ad script that does not ask for an ad

The site is being prepared for AdSense. I added the AdSense loader to the head as part of that preparation and deliberately paused ad requests until the ad placements and the consent flow are ready:

<meta name="google-adsense-account" content="ca-pub-XXXXXXXXXXXXXXXX">
<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-XXXXXXXXXXXXXXXX" crossorigin="anonymous"></script>
<script>(adsbygoogle=window.adsbygoogle||[]).pauseAdRequests=1;</script>

pauseAdRequests = 1 is documented by Google as a way to stop ad requests from being made, and setting it back to 0 resumes them. The reason I want it is that the Auto ads setting lives in the account, not in my repository. It can be toggled from a browser I am not looking at, and I would rather the page refuse than trust that nobody does. Ads on this site are going in two places I chose, before the first subheading of a guide and at the end of it, and nowhere else.

What the browser actually does with that markup, from my own network log on the live site: it fetches adsbygoogle.js, that file fetches show_ads_impl_fy2021.js, and nothing further. No /pagead/ads call, no doubleclick host, no gen_204 beacon, no ad iframe. Two requests to one host and zero ad requests, on both the home page and a guide page.

One detail if you try this: the loader always inserts a hidden <ins class="adsbygoogle adsbygoogle-noablate"> into the body, sized 0 by 0 and display-none. It is created by the script, not by my markup, and it issues no request. My build-time check counts ad units in the HTML I generate, so a runtime element does not trip it.

Keeping it from regressing

None of this holds unless something checks it on every build.

A build verifier renders all 17 pages and asserts 98 invariants: no <link> or <script> points at a host outside the site, every image has alt text, every internal link resolves, and the ad unit count on calculators, the home page and the trust pages is zero. The last run walked 470 links across 17 pages with no errors, and the release it validated is recorded as digest 63ee4554 in build-info.json.

A browser smoke suite loads the built site in headless Chromium and records every request, 321 assertions in total, including which third-party hosts are contacted, that no ad request is made, that the calculators produce the expected numbers from typed input, and that no page overflows horizontally at 390px.

A static gate on the ad markup keeps ad units on guide routes only. If an <ins class="adsbygoogle"> appears anywhere else in the generated HTML, or the publisher ID in the markup does not match config, the build fails. Reserved ad space measured between 0 and 0.0103 cumulative layout shift, against 0.006 for the home page that has no ad slots at all.

Releases are signed before they ship

Every release computes a digest over the exact input file set. Approving one means running a signing script with a private key kept outside the repository, which writes a signature for that single digest. A release gate then refuses to publish if what is about to ship has a different digest, or if the signature does not verify.

So the claims in this post are attached to a reviewed input set rather than to a branch name. When the ad markup changed, the gate additionally refused to resume ad requests until a certified consent management platform was recorded in config, because that one is a compliance requirement and not a preference.

What I have not measured

No field data. Every number here comes from the live production build over a normal connection and from a headless browser. There is no analytics on the site, which is the point, and also means I cannot tell you what a slow phone on a bad network sees.

No comparison against a file-based build of the same content. The reasoning about round trips and gzip sizes is arithmetic, not an experiment.

And the ad picture describes a site whose ads are off at three levels. When the units go live behind a consent flow, the third-party rows in that first table change, and the honest version of this post will need a new table.

The point

None of this is a rule. Inlining CSS is wrong for a site with fifty templates and a returning audience. Self-hosting fonts is wrong if your team ships design changes weekly and needs the CDN tooling. Pausing ad requests is pointless once ads are live and consented.

What travels is the habit underneath: measure what each decision costs on your own site, and keep the architecture no larger than the product needs. For three calculators that take three numbers and return a shopping list, that came out as local computation, a low request count, and a build I can reproduce and sign.

If you have made the opposite call on any of these, what number decided it for you? I would rather hear the threshold than the principle.

Sources

Live pages measured, 2026-09-10: https://www.wallmath.com/ and https://www.wallmath.com/guides/bedroom-paint-math-by-hand/
Font files measured directly: https://www.wallmath.com/fonts/fraunces-700-800-latin.woff2 , https://www.wallmath.com/fonts/sourceserif4-400-600-latin.woff2 , https://www.wallmath.com/fonts/sourceserif4-italic-400-latin.woff2
Image variants measured directly: https://www.wallmath.com/illustrations/calc-paint-480.avif and https://www.wallmath.com/illustrations/calc-paint-1200.webp
Build metadata, including release digest and page count: https://www.wallmath.com/build-info.json
Google on pausing ad requests: https://support.google.com/adsense/answer/9183363
HTTP cache partitioning, the reason a shared font CDN cache no longer helps: https://developer.chrome.com/blog/http-cache-partitioning