DEV Community: Isaiah Kim

I turned on error tracking. Most of it was Outlook.

Isaiah Kim — Mon, 17 Aug 2026 14:27:01 +0000

A weekly report landed on August 17th telling me my sites had thrown 363 exceptions, up 156 percent from the week before, with crash-free sessions at 94.29 percent. That is the kind of number that reorganises a day. Something is broken badly enough that roughly one visit in eighteen hits it, and I have no idea which page.

333 of those 363 were not my code. Not a subtle bug in my code, not a dependency of my code. Two browser artifacts and a dev server.

What was actually in there

The products involved have nothing to do with each other. AgentWire is a curation lane for agentic developer tooling, MCP servers and coding-agent harnesses, and its site is a 1:1 reflection of what the accounts actually posted. KitGrade is a directory of SaaS starter kits scored from measured facts, where every kit is labelled hands-on or documented and the label records whether the kit was cloned onto a machine and built. Different data, different stacks underneath, different everything. The only thing they share is the analytics snippet.

327 of the 363 were this string:

Non-Error promise rejection captured with value: Object Not Found Matching Id:N,
MethodName:update, ParamCount:4

That is not from any code I wrote. It comes from the wrapper Microsoft puts around links opened out of Outlook, running inside the page it just opened. Which is why it fired on AgentWire and KitGrade and everything else at the same moment: an error that appears simultaneously across products sharing no code is not coming from any of them. That simultaneity is the only tell you get, and you only get it if you have more than one site reporting into the same place.

6 more were ResizeObserver loop completed with undelivered notifications, which is the notice a browser emits when a layout observer runs long. Nothing is on fire. Nobody sees anything.

The remaining 30 were mine, in the least useful sense. They were a dev server on http://localhost:3737 reporting compile errors into the production project while I was mid-edit: PAD_X is not defined, SelectedWork is not defined. Errors I had already fixed before the report was written, filed alongside real ones.

The part that generalises

Turning on browser exception capture is one boolean now. In posthog-js, which I am on at 1.407.5, it is capture_exceptions: true next to the pageview settings. You add a line, you deploy, and a week later you have a health metric.

The metric is wrong out of the box, and it is wrong in the direction that costs you the most. It reads worse than reality, so the first thing it makes you do is go looking for a crash that is not there. Then, once you have learned that the report is noise, it reads as noise forever, and the first real one arrives in a mail that looks exactly like the previous four.

The dev server half is worth its own sentence. The project key lives in the client bundle, so it is the same key on localhost, on a preview URL and in production. Every environment reports into one place unless you tell it not to.

The gate

posthog-js has a before_send hook that runs in the browser and drops the event when you return null. I put the filter there rather than in the dashboard, because a dropped event costs nothing and a filtered one still has to be sent, stored and then excluded from every view forever after.

before_send: (event) => {
  if (!event || event.event !== '$exception') return event;
  try {
    const host = window.location.host.split(':')[0].toLowerCase();
    if (host === 'localhost' || host.endsWith('.localhost') || /^[\d.]+$/.test(host) || host.endsWith('.vercel.app')) return null;
    const v = JSON.stringify(event.properties?.$exception_values ?? '');
    if (/Object Not Found Matching Id:\d+/.test(v)) return null;
    if (/ResizeObserver loop/.test(v)) return null;
  } catch {
    // a noise gate must never be the thing that breaks a page
  }
  return event;
},

Three details in there I would keep if I wrote it again.

The first line checks event.event !== '$exception' and returns early. before_send sees everything, including pageviews and clicks, so a filter written loosely here quietly eats your entire analytics feed instead of your error feed.

The host check drops localhost, any .localhost subdomain, bare IP addresses and preview deployments. That is the environment split I did not get for free.

And the catch is the one I care about most. This function runs inside the page, on every event, before anything is sent. If it throws, it throws in front of the visitor. A filter that exists to protect a dashboard is not allowed to be the reason a page stops working, so it fails open and lets the event through.

The two regexes are the least durable part of this. They match strings that a browser vendor can change without telling anyone, and when that happens the noise comes back and I will have to read a digest carefully to notice. I would rather that than a filter loose enough to swallow something real.

The number I get now is 30 exceptions smaller and it is entirely mine. That is the point of the exercise: not a better crash rate, a crash rate that is about my software.

https://agentwire.kynth.studio/?utm_source=founder-devto&utm_medium=social

I shipped a download that iOS turned into a navigation

Isaiah Kim — Fri, 14 Aug 2026 14:51:58 +0000

I read a session from an iPhone where the visitor pressed an export button four times, and $pageleave fired about 150 milliseconds after each press, with a reset page when they came back. Those four departures were the export itself.

WebKit does not honour the download attribute on a blob: URL. On iOS and iPadOS, where every browser is WebKit underneath regardless of what it says on the icon, a.download pointed at a blob is ignored and the click becomes a navigation to that blob. The page unloads. Whatever state produced the file goes with it.

That pattern is everywhere in my code, so I went and fixed the place where it costs the most.

What the page was holding

PartsProof is a Cyber Resilience Act tool I'm building under Kynth, and its free surface is an SBOM generator. You give it a public GitHub repo and an email, and it returns a CycloneDX 1.5 document you can download.

The work behind that is not cheap. src/app/api/sbom/route.ts resolves the repo and its default branch, pulls the full recursive tree, filters that down to dependency manifests, then fetches and parses up to thirty of them. MAX_MANIFESTS is 30, so the whole run is as many as thirty-two GitHub round-trips before a single component is counted.

Because it takes real time, the route streams NDJSON and fires a stage as each piece finishes, with the measured elapsed per stage. The five ids live in one file, src/lib/stages.ts, with a note on top I put there for myself:

/* ⛔ Adding a label here does not create a stage. A stage exists when the route fires it. */
export type StageId = "repo" | "tree" | "manifests" | "bom" | "lead";

So on a phone, the sequence was: wait through thirty-two round-trips, watch five stages report, get told how many distinct components came back, press download, and land on a blob viewer with the whole result gone. Pressing back gives you an empty form. The only way to see the number again is to run all of it again.

The branch, and the iPad that says it is a Mac

The fix in src/components/Lookup.tsx is small. On WebKit mobile, stop pretending the anchor is a download and let it be what WebKit is going to make it anyway: a navigation, but into its own tab, where the document opens with a share sheet instead of destroying the page that produced it.

const ua = typeof navigator === 'undefined' ? '' : navigator.userAgent || '';
const webkitMobile =
  /iP(hone|od|ad)/.test(ua) ||
  (navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1);
if (webkitMobile) {
  aEl.target = '_blank'; aEl.rel = 'noopener';
}
document.body.appendChild(aEl); aEl.click(); aEl.remove();

The second clause of that test is the one I would have missed. An iPad running iPadOS reports navigator.platform as MacIntel and sends a desktop user agent string with no iPad in it, so the regex alone reads it as a laptop and leaves it broken. maxTouchPoints > 1 is what separates the iPad from an actual MacIntel machine, and a Mac with a trackpad reports 0. It is a sniff, and I do not love that it is a sniff, but there is no feature query for "this browser ignores an attribute".

I also considered the File System Access API and skipping the anchor entirely. Safari does not implement showSaveFilePicker, so the fallback path is this same anchor, and adding a branch that only ever runs on the browsers already working buys nothing.

Revoking on the next line

The other half of that commit is a bug that had been sitting there the whole time and would have been much harder to see.

document.body.appendChild(aEl); aEl.click(); aEl.remove();
URL.revokeObjectURL(url);   // ← this

click() starts a save. It does not finish one. Revoking the object URL on the very next statement pulls the blob out from under a transfer that has only just been handed to the browser. On desktop with a small JSON body it wins the race essentially always, which is exactly why it survives review: it looks like tidy cleanup and it behaves like tidy cleanup right up until the document is large or the device is slow or the save goes through a share sheet.

It now reads:

// Revoking on the next line races the save the click just started; give it a window.
setTimeout(() => URL.revokeObjectURL(url), 60_000);

Sixty seconds of one blob held in memory is not a leak worth optimising against a file that sometimes does not arrive.

Saying "downloaded" when nothing downloaded

There was one more thing wrong, and it took a second pass to notice. The success message was a single template string:

setSbomMsg(`downloaded ${repoName}-sbom.cdx.json.`);

On the WebKit path that sentence is false. Nothing landed in a downloads folder. The document opened in its own tab and is waiting for the reader to press Share. Telling someone a file was saved when it was not is the specific failure this panel exists to avoid, since the whole product is about producing a document you can hand to somebody.

setSbomMsg(
  webkitMobile
    ? `${repoName}-sbom.cdx.json opened in a new tab — use Share to save it.`
    : `downloaded ${repoName}-sbom.cdx.json.`,
);

The branch that changes behaviour and the branch that describes it have to be the same branch. Fixing the navigation without fixing the sentence would have left the tool confidently reporting a save on the one platform where it never performs one.

None of this showed up in a build, a type check, or any gate I run against the deployed page. Blob downloads are one of the last things in a web app that no automated check I have will exercise, because the interesting part happens after the click, in the browser's own plumbing, on a platform I was not testing on. The telemetry found it, and it found it as four unexplained departures rather than as an error.

https://partsproof.kynth.studio/?utm_source=founder-devto&utm_medium=social

I built a Playwright gate that cried wolf 889 times

Isaiah Kim — Tue, 11 Aug 2026 14:28:35 +0000

On August 2nd I shipped a landing page whose headline was in the DOM at the right size, the right colour and the right position, and invisible. StoreReady's data-animate="17g0wbg" resolved against motion data from a different capture, so the h1 held its start frame, opacity 0.001, permanently. Every gate I had passed the build.

They passed because they all read source. icons-gate greps the icon set, mark-gate greps the lockup, workbench check hashes the vendored files. All of them are decidable without a renderer, and there is no string to grep for a pixel that never got painted.

So I wrote one that never reads a file. ops/qa/render-gate.mjs in the workbench repo takes a URL, drives real Chrome, and asks six questions a screenshot answers: effective opacity down the whole ancestor chain, WCAG against the computed background, horizontal scroll from 320 to 1920, control labels breaking to a second line, headline and CTA above the fold at 1280x800, and content trapped past the start edge of its own scroll container. Each product's scripts/deploy.sh runs it after the deploy, against the live host, and a failure is hard.

The first sweep reported 889 invisible elements

Essentially all of them were scroll-reveal sections below the fold, sitting at opacity 0 because nothing had asked them to appear yet. A gate that cries wolf 889 times is not a gate.

The part I want to keep from that run is why I did not see it coming. My own shell's entrance runtime reveals on mount rather than on intersection, so the sites already on it scored honestly by accident, which is the worst way to be right. Pointing the same measurement at pages with intersection-driven reveals is what exposed the model.

The fix is that the gate judges only what is on screen. It walks the page, probes at each stop, and merges by element plus text keeping the best reading of each one. An element off-screen at opacity 0 is not a defect. An element in front of the reader at opacity 0 is the StoreReady bug. One scroll position cannot tell those apart.

Per-stop settle is 750ms, long enough for a reveal to finish rather than merely to start. At 320ms it kept catching FetchDue's sections at opacity 0.061, mid-fade, which reads as a defect and is not one.

Two ways the walk still lied

The first was arithmetic. The stops stepped a fixed 0.75 viewport down from the top and then took .slice(0, 14) for the time budget, so on anything taller than about 9,450px at a 900px viewport the sweep just stopped and everything below was never judged at all.

const h = Math.max(document.body.scrollHeight, document.documentElement.scrollHeight);
const MAX = 14; // 14 stops at 750ms is the time budget
const step = Math.max(Math.round(innerHeight * 0.75), Math.ceil(h / MAX));
const out = [];
for (let y = 0; y < h; y += step) out.push(y);

Spreading the same budget over the real height means density degrades on a very long page instead of coverage vanishing. A missed defect in the last third is worse than a coarser walk.

The second is the interesting one. On a long page an element can be in front of the reader at exactly one stop. If that stop catches it entering at the bottom edge, or partway through a stagger, then the best-reading merge has only the bad reading to keep. The finding looks real, reproduces across runs, and describes nothing anyone would ever see. On QuorumFile that condemned three cells of a seventeen-row table, all three at opacity 1 the moment you scroll to them.

Look at it again, on purpose

Anything the walk condemns now gets one more measurement, taken deliberately.

const condemned = text.filter((t) => t.opacity < OPACITY_FLOOR && !t.decorative && !t.clipped);
for (const t of condemned) {
  await page.evaluate((top) => scrollTo(0, Math.max(0, top - innerHeight / 2)), t.top);
  await page.waitForTimeout(1400);
  const fresh = await page.evaluate(probeText);
  const better = fresh.find((f) => f.sel === t.sel && f.text === t.text && f.inFold);
  if (better && better.opacity > t.opacity) Object.assign(t, better, { pxRatio: undefined });
}

OPACITY_FLOOR is 0.08. Two details in there cost me something. Only condemned runs are re-measured, so a clean page pays nothing for this, which is what makes a 1400ms settle affordable at all. And the fresh reading replaces the stale one whole, rather than just its opacity. A reading taken while an element was at opacity 0 also carries the contrast it had against whatever was behind it, which is 1:1 because no ink was painted. Adopting the opacity alone clears the visibility finding and hands that dead 1:1 straight to the contrast check. One false finding becomes a different false finding.

A finding that survives being scrolled to and stared at for a second is the real bug. One that does not was never a bug.

What it caught

On August 8th, on a QuorumFile deploy, it failed on the pricing block's document preview: painted at opacity 0, and not marked decorative.

The cause was not in the pricing block. ScrollReveals collects auto-fade candidates from main.page > * and walks down, so any element added to any section inherits a 0-opacity start state whether it asked for one or not. Mine carried no data-reveal and got one anyway. The fix was to put it in the runtime's skip list next to .header, for the same reason the header is there.

const SKIP = ".header, .trail, .nav-list, .nav-dropdown-list, .sheet-overlay, .kd-artefact-link";

The gate cannot decide this on its own, and it does not try. My footers carry a brand wordmark at opacity 0.07, which is a watermark and correct. StoreReady's hero sat at 0.001, which was a bug and shipped. Measured, those are the same observation, so the rule is that text below the floor has to declare itself with aria-hidden="true" or it counts as a failure. A heading is never decoration.

I had opened that pricing block in a browser more than once before the deploy. The gate found it, I did not.

The early return that shipped a false all-clear

Isaiah Kim — Sun, 09 Aug 2026 14:25:28 +0000

I typed the word "construction" into my own lookup tool and it answered:

All 200 qualifying contracts under null have an approved Affidavit of Wages Paid on file.

Two things wrong in one sentence, and the more interesting one is that nothing had been checked against the affidavit file at all. The route had returned before it got there.

The product is HeldBack, a free retainage blocker check I'm building under Kynth. You give it a company name or a 9-digit UBI, and it reads two of Washington's published Socrata files live: the Statements of Intent a contractor files before a public works job, and the Affidavits of Wages Paid filed after. A job with an intent and no matching approved affidavit is a job whose retainage, capped at 5% under RCW 60.28.011, is likely still sitting with the awarding agency.

The floors are most of the logic

The naive version of this is a set difference: intents minus affidavits. That version is wrong in a way that destroys the product's credibility on first contact, because a job that started six months ago has no affidavit for the boring reason that the work isn't finished. Report that as frozen money and you've told a contractor something they know to be false about a job they remember clearly.

So src/app/api/lookup/route.ts filters before it compares:

const MIN_CONTRACT = 5000;
const MIN_AGE_MONTHS = 24;

const priced = intents.filter(
  (r) => Number(r.cntrct_amt) >= MIN_CONTRACT && !tooRecentOrUndated(r.expected_start_dt),
);

At or under $5,000 the affidavit is folded into the combined intent form and never appears separately, so those rows are false positives by construction. Undated rows can't be aged at all, so tooRecentOrUndated returns true for them and they drop out too.

Both floors are correct. The bug was what happens when they eat everything.

The return that skipped the comparison

if (priced.length === 0) {
  return NextResponse.json({ term, company: null, rows: [], searched: intents.length });
}

searched is the number the UI prints back. Everywhere else in the file it means "contracts we actually compared against the affidavit file". Here it meant "rows the first query returned", because at the moment I wrote the line those felt like the same quantity.

They're the same quantity right up until a search term is generic. The intents query is capped at $limit: '200', and a common word matches far more than 200 filings across the whole state, none of them one company. Nearly all of them fail the $5,000 floor or the 24-month floor. priced comes back empty, the route returns here, and the client is handed searched: 200 with an empty rows array. The panel reads that as 200 contracts checked and zero blocked.

The null in the sentence has the same root. Company name is resolved as priced[0]?.companyname, and on this path priced is empty.

The fix splits the count into two:

if (priced.length === 0) {
  /* `searched` IS THE QUALIFYING COUNT, NOT THE FILING COUNT, and this line used to return
   * `intents.length` for it. [...] `found` is the honest count for this case: filings
   * located, none of them judgeable. */
  return {
    payload: {
      term,
      company: intents[0]?.companyname ?? null,
      rows: [],
      searched: 0,
      found: intents.length,
      cleared: 0,
      totalHeld: 0,
    },
  };
}

searched: 0 is now literally true. Nothing was searched against the affidavit file.

Two branches for three outcomes

The other half was in src/components/HeroLookup.tsx, which had an empty state and a clear state and nothing else. Any result with rows.length === 0 fell into "nothing appears to be blocked". There was no way to express "we found filings and none of them can be judged yet", so that case borrowed the reassuring one.

{(result.found ?? 0) === 0
  ? 'No public works contracts found under that name.'
  : result.searched === 0
    ? 'Nothing here can be judged yet.'
    : 'Nothing appears to be blocked.'}

The middle branch explains itself in the body copy: every match is under $5,000 or started inside the last 24 months, a job that recent has no affidavit because the work is not finished, and search the exact legal entity name or the UBI to narrow it. That last part matters more than the correction does. The person who typed a generic term wanted an answer about a company, and now the panel tells them how to get one.

The same short-circuit, one component away

The wait panel streams NDJSON and fires a stage as each of the route's four real pieces of work finishes, with the measured elapsed printed per stage. On a real company that reads 587ms, 587ms, 756ms, 757ms, and the third line says "53 of 74 have an approved Affidavit on file". Two of the four stages are live network calls, which is where the seconds go.

The orb at the head of that panel spun forever on the short-circuit path, because it asked whether all four stages were done. On an early return two of them never fire, so the answer is permanently no, and the orb kept spinning next to a finished answer.

const running = steps.some((s) => s.state === "running");
const phase = idle ? "idle" : failed ? "failed" : running ? "running" : "done";

What the orb reports is whether anything is still happening, not whether every stage reported.

Neither of these turned up in reading. I found both by typing a word into the live thing and looking at the sentence it gave back, which is also the exact sentence a first-time visitor would be most likely to see, since a generic term is what you type before you know what the tool wants.

I paged a table with no ORDER BY and lost 2,797 rows

Isaiah Kim — Fri, 07 Aug 2026 14:24:14 +0000

I ran a verification pass over 22,313 rows, it reported 22,313 rows, and I read that number as proof it had checked all of them. It had checked about 19,500 and looked at some of those twice.

The product is BlockDex, an item-level index of public shadcn registries I'm building under Kynth. Every item page can render a Live preview — an iframe of the component's own docs page — under a caption that says this is the component running, not a screenshot of it. Nothing checked that claim. preview_url was a URL shape learned once per registry from a single sample item name, accepted on status === 200 && text.length > 500, then stamped onto every item in that registry.

Two things went wrong with that. The last docs pattern tried is {origin}/r/{name}, which on a large class of registries is the registry-item JSON route — the same route the install command reads. A 4KB JSON body clears a length test, the request sent accept: 'text/html,*/*' so the */* forced nothing, and an API route sends no X-Frame-Options, so the framability check returned true and marked that registry the most embeddable kind there is. One registry framed its own JSON and Chrome rendered its JSON viewer inside the panel. Separately, a shape learned from one item name does not hold for 7,794 items, so most of the rest resolved to the registry's 404.

I fetched all 22,313 stored preview URLs. 7,382 were not component pages: 4,704 hard 404s, 1,588 JSON documents, 691 soft 404s, 399 server errors.

The count that matched

ops/verify-previews.mjs pulls its work list through a paging helper that walks a table with limit/offset — 23 pages at a thousand rows each. The query had no ORDER BY.

An offset over an unordered query is not a stable window. Postgres is free to return the rows in a different order for each page, so between page 4 and page 5 a row can shift across the offset boundary and be handed to you twice while another row slides the other way and never arrives. The totals still add up, because you asked for 23 slices of a thousand and got them.

I found it the slow way. After the pass finished and wrote its updates, shadcn-io/area-interactive still had a Live preview panel mounted over a 404. Its row was in the set the paging skipped.

// ⛔ `order=id.asc` IS LOAD BEARING. `selectAll` pages with limit/offset, and an offset over a
// query with no ORDER BY is not a stable window — Postgres is free to return the rows in a
// different order for each of the 23 pages, so a row can arrive twice and another never arrive
// at all. The first full run pulled exactly 22,313 rows, which looked like complete coverage
// and was not.
const rows = await store.selectAll(
  'blockdex_items',
  `select=id,registry_slug,name,preview_url,preview_embeddable,docs_url,status&preview_url=not.is.null&order=id.asc${filter}`,
);

The second pass with the sort key found 17,728 rows still carrying a preview URL where 14,931 were expected, and unpublished 1,603 more. A third pass agreed with the second: 16,121 of 16,125 verified, the remaining four a transient 502.

The fan-out that wasn't doing anything

The same file had a second bug I'd have shrugged at if I hadn't been staring at it. Global concurrency is 40. The real limiter is a per-host cap of 3, which is what keeps a registry running on one small deployment from getting hammered. And rows come back from PostgREST grouped by registry.

shadcn-io is 7,794 contiguous rows on one host. So all 40 workers picked up shadcn.io items, 37 of them parked on that host's semaphore, and the other 127 hosts in the corpus sat idle. The run did 1,500 items in eleven minutes and was on course for about three hours.

const byHost = new Map();
for (const row of rows) {
  const host = URL.parse?.(row.preview_url)?.host ?? row.registry_slug;
  if (!byHost.has(host)) byHost.set(host, []);
  byHost.get(host).push(row);
}
const queues = [...byHost.values()];
const work = [];
for (let i = 0; work.length < rows.length; i++) {
  for (const q of queues) if (i < q.length) work.push(q[i]);
}

Round-robin by host, then hand that array to the pool. Wall clock becomes the slowest single host instead of the sum of all of them.

What counts as a missing page

The check itself, in ops/lib/preview.mjs, is deliberately narrow. My first version read the first 4KB of the body looking for not-found markers, and on a 400-URL sample it condemned two real, rendering component pages that happened to carry the string 404 in a nav and an inlined script. Deleting a working item from the index is the worse outcome, because a 404 that slips through is visible on the page and a missing item is not. So the test only reads <title>, which is the one place a framework's not-found page reliably announces itself — fumadocs writes "Component not found", Next writes "404".

A failure clears docs_url alongside preview_url, too. Downgrading a dead frame to a "See it running" link is the same claim in smaller type.

Final state: 11,502 items carry a verified Live preview, 2,369 a verified link, 45,343 neither, 8,985 unpublished. The order=id.asc has a comment sitting on top of it, because the version without it doesn't fail — it returns a number that matches the table.

I rewrote 1.2M Postgres rows a run to change nothing

Isaiah Kim — Wed, 05 Aug 2026 14:25:17 +0000

I went looking for why one Supabase project kept draining its Disk IO Budget, and the answer was a Python script rewriting 1,206,313 rows to change nothing.

The product is GoodStanding, a free EIN diagnostic I'm building under Kynth. You type in a nonprofit's EIN and it tells you whether that org is on the IRS Auto-Revocation List or on California's "May Not Operate or Solicit" list. The table behind it, gs_orgs, is fed by ops/src/ingest-registries.py, which pulls two files: the IRS bulk revocation zip, and the CA AG CSV that refreshes on the 1st and 3rd Wednesday.

Both feeds republish their entire corpus every cycle. A few thousand rows actually move. The ingest didn't know that, so every run it upserted all 1.2 million.

Measured against the stats reset on May 22, that one script was the largest consumer of disk IO on the whole project: 24,721 upsert statements, 10.2 GB read from disk, 3h17m of database time.

Fingerprint the row, not the feed

The obvious fix is to diff against what's already in the table, but reading 1.2M rows back to decide whether to write 1.2M rows is the same IO with extra steps. What made a cheaper option available is a property of this particular table: ingest-registries.py is the only writer to gs_orgs. Nothing else touches it. So a local record of what the script last wrote is authoritative, and no read is needed at all.

def fingerprint(row):
    """Stable 16-hex digest of the columns we actually write."""
    blob = '\x1f'.join('' if row.get(c) is None else str(row[c]) for c in COLUMNS)
    return hashlib.blake2b(blob.encode(), digest_size=8).hexdigest()

Hashing COLUMNS and not the parsed source record matters. The feeds carry fields the table doesn't store, and a whitespace change in one of those would otherwise flag a row as changed and buy back the write I'm trying to avoid.

The selection is then four lines:

fresh = {ein: fingerprint(r) for ein, r in merged.items()}
if args.full:
    rows = list(merged.values())
else:
    seen = load_fingerprints()
    rows = [r for ein, r in merged.items() if seen.get(ein) != fresh[ein]]

Two things about the cache file are deliberate. Missing it isn't an error — load_fingerprints() swallows FileNotFoundError and returns {}, every row mismatches, and you get a full rewrite. The degraded state is the old behaviour, which is slow and correct. And it's written once, after the last batch lands:

# Written only after every batch landed: a crash mid-run leaves the cache
# untouched so the next run retries the same rows.
save_fingerprints(fresh)

Saving per batch would have been the natural thing to write, and it's the version where a timeout halfway through convinces the next run that rows it never wrote are already durable.

Run against that day's corpus: 0 of 1,206,313 rows flagged as changed.

The indexes nobody had ever used

While I was in the stats I checked which indexes on gs_orgs had been scanned. Three had a scan count of zero: gs_orgs_name_trgm, gs_orgs_posting_idx, gs_orgs_ca_status_idx. Never once, and maintained on every one of those upserts.

gs_orgs_name_trgm is the one worth sitting with. Despite the name it wasn't a trigram index at all — it was a btree on lower(name) text_pattern_ops. The name search the app actually issues is in src/app/api/lookup/route.ts:65:

rows = await sb(`gs_orgs?name=ilike.*${encodeURIComponent(safe)}*&...&limit=8`);

Leading wildcard. A text_pattern_ops btree can serve a prefix match and nothing else, so that query had been sequential-scanning the whole table since the day it shipped, next to an index named as though it were handling it. Dropping all three took the table's index footprint from 198 MB to 72 MB.

The write was the smaller problem

The next day I made the bigger call, and it went the other way from where I started. The project had been moved onto its own Supabase instance for blast-radius isolation, at $10/month. For one product that isn't a trade worth making — so instead of paying to keep 1.2M rows somewhere safe, I asked what the product can actually do with them.

An org revoked in 2013 is looking at a full 1023 re-application. GoodStanding sells a reinstatement Cure Pack; that org isn't a buyer, and its row is heap, index and WAL on a database the rest of the estate shares. California is different — AB 488 blocks a listed org's donation pages regardless of how old the listing is.

def worth_keeping(r):
    if r.get('ca_reg_no') or r.get('ca_registry_status'):
        return True                      # CA-listed: AB 488 buyer at any age
    if r.get('reinstatement_date'):
        return False                     # back in good standing; "clear" is correct
    return (r.get('revocation_date') or '') >= keep_since \
        or (r.get('revocation_posting_date') or '') >= keep_since

331,377 rows of 1,206,313. 261 MB down to 81 MB, back on the shared database, and the outreach delta came through unchanged: 716 IRS postings in the last 45 days, 8,219 CA delinquent or suspended.

There's a trap in that, and it's the reason the comment block above worth_keeping is longer than the function. /api/lookup reads "no row" as clear — the table only ever holds orgs that are on a list, so absence is the good answer. Drop a still-revoked 2013 org and the tool tells that nonprofit it's fine.

So the cutoff is load-bearing on a claim in the UI, and the two are now written down together. GS_KEEP_REVOKED_SINCE defaults to 2020-01-01, the route file carries a retention warning at the top, and the clear-state copy in EinLookup.tsx says "No IRS auto-revocation posted since 2020" rather than the unqualified all-clear it used to say. Widening the cutoff means widening that sentence.

What I'd been treating as a performance problem had a correctness statement buried in it. The rows I was paying to rewrite twice a month were also the rows that decided what the product was allowed to promise, and I only found that by going looking for the disk IO.

unstable_cache stored my outage for a full hour

Isaiah Kim — Sun, 02 Aug 2026 14:22:41 +0000

I shipped a directory page that told visitors there were zero listings while rendering a grid of 48 of them. Fixed it. Then, about nine hours later, shipped a different bug with the exact same symptom, in the exact same function, for a completely unrelated reason.

The product is SkillWorks, a scored directory of Claude Code skills, subagents, plugins and marketplace repos I'm building under Kynth. It reads from Supabase over PostgREST, and it needs a lot of row counts: total listings, counts per kind, how many are broken, how many have tracked installs. Counting rows without pulling them is the one thing PostgREST makes genuinely cheap — ask for Prefer: count=exact with Range: 0-0 and the total comes back in the Content-Range response header. No rows in the body at all.

That header is where both bugs live.

The first zero: the header didn't survive the cache

Original version, in src/lib/db.ts:

async function countRows(table: string, query: string, col = 'id'): Promise<number> {
  const res = await fetch(`${URL}/rest/v1/${table}?${query}&select=${col}&limit=1`, {
    headers: { apikey: KEY, Authorization: `Bearer ${KEY}`, Prefer: 'count=exact', Range: '0-0' },
    next: { revalidate: REVALIDATE },
  });
  const range = res.headers.get('content-range');
  return range ? Number(range.split('/')[1]) || 0 : 0;
}

Next's fetch cache stores the response body. On a cache hit it hands you back a Response assembled with a synthetic header set, and content-range is not in it. So every cache hit read null and fell through to 0.

What kept this hidden for a while is that statically prerendered routes were fine. Their one fetch happens at build time and is always a miss, so the real header is right there. Only routes rendering at runtime hit the cache, and those were the ones shipping "0 indexed" next to a full grid. /marketplaces read "None of the 0 marketplaces".

The fix is to stop caching a thing whose value lives outside the cached payload. Make the fetch cache: 'no-store' and wrap the whole function in unstable_cache, which memoises the return value instead. Still one request an hour, but now what's stored is a parsed number, which survives being stored.

The second zero: a failed read stored as an answer

That was August 1st, early afternoon. That evening Supabase had an outage, and I watched /skills render "Search all 0 listings" above cards that looked completely normal.

The cards were fine because they come from Next's fetch cache and it still had them. The counts came through the new uncached path, hit a dead index, and returned 0 — which is the last line of the function above, doing exactly what it was written to do. And unstable_cache dutifully stored that 0 for the full REVALIDATE window, which is 3600 seconds.

That's the part that actually bothered me. The outage was maybe twenty minutes. The wrong number would have outlived it by forty. The database could be answering perfectly and the site would still be advertising zero listings, with no error, no degraded state, nothing to look at. A directory that confidently reports emptiness is worse off than one that's visibly broken, because nobody goes looking.

The || 0 was defensive code from the first bug that quietly became the second one. Returning a fallback and memoising a fallback are different operations, and one function was doing both.

Throw inside the cache, degrade outside it

const countRows = async (table: string, query: string, col = 'id'): Promise<number> => {
  try {
    return await unstable_cache(
      async () => {
        const res = await fetch(/* … */, { cache: 'no-store' });
        const range = res.headers.get('content-range');
        // THROW rather than return 0 when the index cannot be reached.
        // `unstable_cache` stores whatever the function RETURNS, for a full hour.
        if (!res.ok || !range) throw new Error(`count ${table}: ${res.status}`);
        const total = Number(range.split('/')[1]);
        if (!Number.isFinite(total)) throw new Error(`count ${table}: unparseable content-range`);
        return total;
      },
      ['count', table, query, col],
      { revalidate: REVALIDATE },
    )();
  } catch {
    // 0 is still what the caller gets — a directory page that 500s over a stat line is worse
    // than one that under-reports for a few seconds. The difference is this 0 is NOT cached.
    return 0;
  }
};

The caller still gets 0. A browse page shouldn't throw a 500 because a stat line in a search placeholder couldn't be computed. But the fallback now lives outside the memo, so nothing gets written, the next request re-reads, and the wrong number lasts exactly as long as the outage does and not one second longer.

The same weekend, in a different product, I hit the same shape from the other direction. ListRun has pages where the row is the page — a directory detail, a run, a paid receipt — and they all called a helper that returned null on any failed read, then called notFound(). Which means a slow database told a buyer their run does not exist, and on a cached render it baked that 404 in. The fix there was apiRequired in src/lib/site.ts: return null only on an actual 404 from the route, throw on anything else, so notFound() is always a statement about the row.

Both are the same mistake. A read that fails and a read that legitimately returns nothing produce the same value, and then something downstream — a cache, a router — treats that value as established fact and keeps it around. The failure gets laundered into data on the way out.

I've stopped trusting any fallback that sits inside a memo boundary. If a function can be wrong and can be stored, those two facts need to be separated by a throw.

Custom element FOUC: the rule that hid nothing

Isaiah Kim — Fri, 31 Jul 2026 14:21:44 +0000

I shipped a CSS rule that could not possibly do its job, looked at the page, saw the flash still happening, and spent longer than I want to admit tuning the wrong thing.

The product is Tearline, a small zero-dependency web component I'm building under Kynth. You wrap any HTML in one tag and it renders as a thermal receipt you can export as a PNG:

<tear-line barcode="047320260726">
  <h1>MERIDIAN</h1>
  <p>Coffee &amp; Provisions</p>
</tear-line>

Custom elements have a well-known ugly window. Until customElements.define runs, those children are just ordinary HTML sitting in the page: a bare <h1> and some <p>s in whatever the host's body font is, at a completely different height to the receipt that eventually replaces them. On a cold load that's visible long enough to read, and then the layout jumps.

The standard fix is :not(:defined). :defined only starts matching once the element upgrades, so hiding on :not(:defined) is exactly the window you want to cover.

Where I put it, and why that was wrong

I didn't want every consumer of the component to have to remember a stylesheet rule. So I had tearline.js inject it:

// src/tearline.js — what I shipped first
if (typeof document !== 'undefined' && !document.getElementById('tear-line-fouc')) {
  const s = document.createElement('style');
  s.id = 'tear-line-fouc';
  s.textContent = 'tear-line:not(:defined){visibility:hidden}';
  document.head.append(s);
}

customElements.define('tear-line', TearLine);

There was a second reason I liked this, and it's a real one: if the script never loads at all, the rule never lands either, so the content stays visible instead of being hidden forever by a stylesheet with nothing left to reveal it. Failure mode handled. Nice.

Except the whole thing is inert. That script running is the exact moment :not(:defined) stops matching. The rule and the definition arrive in the same tick, so the rule only ever exists after the window it was written to cover. It hid nothing during the only period that mattered.

I found this by throttling tearline.js to a 1.2s delay in devtools, which made the unstyled window long enough to actually stare at. Before that I'd been reading the rule, agreeing with the rule, and assuming the flash was coming from somewhere else.

The rule has to be present on the first frame

Which means it has to be in the page's stylesheet, not in the component. It's now in src/app/template.css:

.js tear-line:not(:defined) {
  visibility: hidden;
}

The .js prefix is how I keep the property I liked about self-injection. An inline script in <head> (src/app/layout.tsx:70) does one thing:

document.documentElement.classList.add('js')

It's inline and synchronous, so the class is on <html> before anything can match against it. If scripting is off or the bundle dies, the class is never stamped, the rule never applies, and you get the raw markup rather than a permanently blank box. Same guarantee, moved to a place that's actually there on the first paint.

This was the second time on this project I'd hit the same shape. The landing page's scroll reveals had it too: ScrollReveals was setting each element's hidden opacity from a useEffect, which runs after hydration, which is after the browser has already painted the server HTML fully visible. Every load was doing paint the whole page, blank the parts that reveal, fade them back in. No amount of tuning the IntersectionObserver fixes that, because the wrong frame has already been shown by the time the JS exists. Hidden state belongs in CSS; the runtime should only ever move things toward visible, which is a direction it can't be late for.

Hiding is only half of the flash

Once nothing was visible during the upgrade, the page still moved on arrival, because reserving zero space and then dropping in a full receipt is its own layout shift. Two more pieces:

.panel-result,
.tl-stage {
  min-height: 260px;
}

tear-line[data-ready] {
  animation: tl-arrive 0.4s cubic-bezier(0.22, 1, 0.36, 1) both;
}

260px is a guess. Being roughly right and stable beats being exactly right one frame late.

The data-ready attribute took one more correction. My first version set it at the top of the render path, and the receipt faded in half-drawn: paper present, tear and barcode not yet. The clip path and the barcode are both built from the same seeded stream and get applied later in the same method, so "ready" had to mean after all three:

// The host page fades in on [data-ready]. Set on the next frame, after the
// paper, the tear and the barcode are all in place.
if (!this.hasAttribute('data-ready')) {
  requestAnimationFrame(() => this.setAttribute('data-ready', ''));
}

The attribute is only set once, so re-renders (changing seed, changing width) don't re-trigger the entrance animation. And the whole thing is dropped under prefers-reduced-motion: reduce.

Verified the same way I found it: throttle the script to 1.2s, watch the whole pre-upgrade window. Hidden throughout, no unstyled text at any point, no shift when it arrives.

The part I'd keep from this: a rule whose job is to cover the window before a script runs cannot be delivered by that script. That sounds obvious written down. It did not look obvious in the diff, because the code was correct, well-commented, and answering a question about a completely different failure than the one I had.

Ranking a dashboard by funnel depth, not counts

Isaiah Kim — Mon, 27 Jul 2026 14:21:10 +0000

I had a metrics page that told me nothing. Page views per host, signups, a couple of Stripe lines, all rendered as cards in a grid. Every morning I'd look at it, feel vaguely informed, and then go build whatever I'd already decided to build the night before. That's the tell: if the dashboard never changes what you do next, it isn't a dashboard, it's decoration.

So I rewrote it around one question — how far do people actually get — and let that ordering decide what I see first.

The ordering is the product

Kynth Studios ships a lot of separate products on separate hosts: FetchDue chasing overdue invoices for agencies, BenchFile doing NYC Local Law 84 filings, CertScope determining CPSC scope per SKU, ParseRail for developers integrating against the API. They don't share a funnel shape in any interesting way, but they do share a funnel depth: someone lands, someone starts the demo, someone finishes the guided run, someone starts signup, someone finishes it, someone activates.

Depth is the only axis where those products are comparable. A traffic number tells me a host got attention. A depth number tells me where attention stopped.

So the model is a stage list plus a rollup per product:

// stages are ordered; index IS the depth
const STAGES = [
  'demo_start',
  'demo_complete',
  'signup_start',
  'signup_complete',
  'activated',
] as const

type Stage = (typeof STAGES)[number]

type ProductFunnel = {
  slug: string
  counts: Record<Stage, number>
}

// deepest stage a product has ANY reach into
function depth(f: ProductFunnel): number {
  for (let i = STAGES.length - 1; i >= 0; i--) {
    if (f.counts[STAGES[i]] > 0) return i
  }
  return -1
}

// the first stage that eats everything
function stall(f: ProductFunnel): Stage | null {
  for (let i = 1; i < STAGES.length; i++) {
    const prev = f.counts[STAGES[i - 1]]
    if (prev > 0 && f.counts[STAGES[i]] === 0) return STAGES[i]
  }
  return null
}

depth sorts the list. stall is the label on each row. Everything else on the page is subordinate to those two functions.

Vanity metrics are the ones with no stage below them

The rule I ended up with for what stays on the page: a metric earns its spot if there's a next stage it's supposed to feed. Page views feed demo starts. Demo starts feed completions. Completions feed signup starts.

Page views on their own feed nothing I control, so they came off. Same with a top-level "total events" number, which mostly moved when I deployed something. Anything that only ever goes up and never implies an action is a metric you can watch forever without learning anything.

The one that hurt to cut was a combined cross-product total. It looked healthy. It was healthy — it just averaged a product where people finish the demo together with one where nobody gets past the landing page, and the average was never the thing I needed to know. Now every row is per-product and the sort does the summarizing.

Keep the data engine away from the rendering

The part I'd do again on any dashboard: the thing that computes stages, predicates, sorts and rollups is framework-agnostic and knows nothing about React. It takes events, returns ProductFunnel[] sorted by depth. The components take that array and draw it.

That split has paid off more than once. When a number looks wrong, the first question is which half is wrong — and because the contract between them is a plain typed object, I can answer it by calling the rollup in a test and reading the output. A rendering bug costs nothing on the engine side. A rollup bug is visible without a browser.

It also means the same rollup feeds a morning summary that isn't a web page at all. Same functions, different renderer.

What the page actually looks like now

One list. Products sorted deepest-first, each row showing its stall stage and the counts on either side of it. FetchDue near the top because there's a one-click live demo with no signup form in front of it, so people reach the guided run. The compliance products — BenchFile, GoodStanding, DoseTrace — sit lower, because a done-for-you filing service has a different entry shape and the interesting stage is further along.

That ordering is doing real work. Last week it put a product at the bottom of the list whose landing page I thought was fine, with a stall at demo_start — plenty of people arriving, nobody starting. That's a specific bug in a specific place, which is more than the old grid ever gave me.

FetchDue has no customers yet and the dashboard says so; the honest zero is on the page next to a link to the live product and a recorded run. I'd rather look at a zero I can locate than a total I can't.

The bit I'd tell someone rebuilding theirs

Pick the axis before you pick the charts. I spent longer than I should have arranging cards, and none of that time mattered, because the layout question and the ranking question are different questions and only one of them changes what you build tomorrow.

Sorting by depth also has a property I didn't expect: the top of the list is the least urgent thing. The products getting people deepest need the least attention. Reading the page bottom-up is the actual workflow, which means the sort could arguably be reversed — I've left it deepest-first because I want the ceiling visible, and I go to the bottom on purpose.

Seek-safe animation: one paused timeline, scrubbed

Isaiah Kim — Sat, 25 Jul 2026 14:21:58 +0000

I've been building HyperFrames, the animation engine behind the product demo videos I make at Kynth. It renders video from HTML: a composition is an HTML file whose DOM declares its own timing with data-* attributes, and the renderer turns that into frames. The same pipeline cuts the walkthroughs for FetchDue, CertScope and DoseTrace, alongside the Playwright harness that drives a real browser through each product and the edge-tts narration track.

The whole design collapses into one requirement: same input time → same pixels. Everything below is what that requirement cost.

Why does a render pipeline need a paused timeline instead of playback?

Because there is no playback. The renderer doesn't watch an animation run and grab screenshots — it takes a time value, seeks the page to it, and reads a pixel buffer. Frames can be sampled out of order, and they can be sampled in parallel across workers. Nothing is allowed to depend on having arrived at this frame through the previous one.

That kills a whole category of normal web animation. requestAnimationFrame loops accumulate state. setTimeout chains assume wall-clock progression. Scroll and hover listeners never fire, because the renderer has no input events. If a visual only looks right after the browser has been sitting there for two seconds, it will never look right in a render.

So every composition registers exactly one paused GSAP timeline, built synchronously at page load, keyed by the composition's own id:

// index.html — built at load, never played
const tl = gsap.timeline({ paused: true });

tl.from("#headline", { y: 24, opacity: 0, duration: 0.6, ease: "power2.out" })
  .from("#rows .row", { y: 12, opacity: 0, duration: 0.4, stagger: 0.08 }, "-=0.2");

window.__timelines["invoice-scene"] = tl;

The key has to match data-composition-id on the root element exactly. No -mount or -host suffix, which I know because I spent real time staring at a blank frame that previewed perfectly.

The rule that makes the rest fall out

Build the timeline synchronously. Not inside async, not in a Promise.then, not in a setTimeout. The renderer can seek before an async builder finishes, and when it does you get a frame of the static HTML with none of the motion applied — and no error, because nothing failed. It's just early.

Once that rule holds, seeking is a one-liner (tl.seek(t)), and the interesting work moves to everything that isn't the timeline.

What actually breaks determinism in practice?

Clocks and randomness are the obvious ones, and they're the easy ones to lint. Date.now(), performance.now(), unseeded Math.random() — banned outright for anything that affects visual state. If you want random-looking placement, seed a PRNG so the scatter is identical on every run.

The subtler ones:

Infinite loops. repeat: -1 has no defined state at time t in a parallel sampler. Compute a finite count from the clip's duration instead:

const repeats = Math.max(0, Math.floor(duration / cycleDuration) - 1);

floor, not ceil. ceil overshoots the declared duration, and Math.max(0, …) stops a short clip from producing -1 — which is infinite again, by the back door.

Two timelines touching the same property. GSAP's overwrite behavior is order-dependent. If two tweens both animate opacity on the same element in the same window, which one wins depends on evaluation order, and that can flip between renders. This one is nasty because it usually looks fine and then produces one wrong frame in the middle of a delivered video.

Never measure the DOM at tween time

getBoundingClientRect() inside a tween callback is the desync I hit most while building scene templates. It reads fine in preview, where frames arrive in order. Under a parallel renderer, the element you're measuring may be in a different state than you assumed, so the number you get back depends on sampling order.

The fix is boring: compute layout constants once at composition setup and reuse them. Same for text — for anything dynamic, measure through the framework's own text helpers (fitTextFontSize, or the pretext measurement layer under it) rather than reflowing the DOM per frame.

There's an allowlist for what can be animated at all: opacity, x, y, scale, rotation, color, backgroundColor, borderRadius, transforms. Never display, never raw visibility, and never width/height/top/left for layout changes. Transforms compose predictably at an arbitrary time; layout properties trigger reflow and take their neighbors with them.

How do you seek a runtime that isn't GSAP?

You make each runtime publish something the engine can address by time, and you give the engine one adapter per runtime. GSAP covers most motion work, but a composition can mix runtimes, and each one seeks differently:

Lottie — every player registers itself on window.__hfLottie, and the adapter calls goToAndStop(timeMs, false) on lottie-web instances, or the frame/percentage API on dotLottie.
Web Animations API — the adapter walks document.getAnimations(), sets each currentTime to HyperFrames time in milliseconds, then pauses it. Author with fill: "both" so seeked states persist past their active window.
CSS keyframes — the adapter finds elements with a computed animation-name, seeks their Animation handles when the browser exposes them, and otherwise falls back to pausing with a negative animation-delay. Use animation-fill-mode: both.
Three.js — the adapter deliberately does not own your scene. It sets window.__hfThreeTime and dispatches hf-seek, and your composition renders that exact time:

window.addEventListener("hf-seek", (event) => {
  const t = event.detail.time;
  mixer.setTime(t);           // authored clips
  camera.position.z = 8 - t;  // pure function of time
  renderer.render(scene, camera);
});

The shape is the same every time: time in, frame out, no memory of the previous call.

Duration turned out to be a separate problem from seeking

This surprised me. The render engine needs a positive total duration before it captures a single frame, or capture fails outright. A GSAP timeline reports its own length, so that case is free. The others aren't.

CSS duration is inferred from the longest animation-delay + duration × finite iteration count. WAAPI comes from the longest effect's getComputedTiming().endTime. Lottie reads the asset's native length, which is finite even when loop: true. And Three.js is not inferable at all — the adapter only forwards time, it doesn't inspect your scene for an AnimationClip. So a Three.js composition must declare data-duration on its root, and the linter errors when it doesn't.

Two capabilities that felt like one: where am I on the timeline and how long is the timeline. Every adapter answers the first. Only some can answer the second.

How do you catch a desync before it reaches a delivered video?

Sample the frames a human would never scrub to. Three passes, in order of cost:

npx hyperframes check                      # lint, runtime, layout, motion, contrast
npx hyperframes snapshot --at 2.4,6.1,9.8  # eyeball the seams, not the beats
npx hyperframes render                     # only after the frames look right

check catches the mechanical violations — a missing duration source, a repeat that overshoots, a set on a clip from a later scene. Snapshots catch the silent class: a transformed element that's still inline and therefore invisible, a full-screen background painted on the root instead of a full-bleed child (which previews correctly and renders black), a pulsing decorative that clears its neighbor at rest and collides at peak scale.

There's also an audit script that walks every registered timeline, enumerates the tweens, samples bounding boxes and writes an animation map — useful for finding dead zones and inconsistent stagger after the fact.

Almost every bug that survived to a delivered frame had the same signature: preview looked right, render didn't. Preview plays forward, in order, in one process. The renderer doesn't do any of those three things. Anything you validate only by pressing play, you haven't validated.

Why a CSS diff reads right and renders wrong

Isaiah Kim — Thu, 23 Jul 2026 14:21:40 +0000

I shipped a mobile fix for one of our tenant sites last week — coi-tracking, the first real app we stood back up after the catalog teardown. The change was small: restore some breakpoint rules that had gone missing in a port, and un-hide a few elements that only exist once on desktop. Reading the diff, every line was obviously correct. Reading the site at 390px before the fix, it was obviously broken. Those two facts had been true at the same time for a while.

That gap — a change that reads right in the diff and wrong in the browser — is the thing I've spent the most effort building a habit around, because I'm one person and there is no second pair of eyes between my editor and production.

Why does a CSS diff read right and render wrong?

Because a diff shows you the rule you changed, and the browser shows you the rule that won. Those are different questions, and only one of them is answered by the text in front of you.

A media query block is a self-contained, readable thing. When it's present, it reads as deliberate. When it's absent, it reads as nothing at all — there's no line to notice. Deletions in CSS are silent in a way deletions in TypeScript are not. Remove a function and something fails to compile. Remove a @media (max-width: 768px) block and the desktop layout stays pixel-identical, the build passes, and the site is broken at a width you weren't looking at.

The coi-tracking landing came through our Framer→Next capture-and-own pipeline — we license a template, capture the live rendered DOM and CSS, and port it into code we own so it's ours to change forever. That pipeline is great, and it is also exactly the kind of transform where breakpoint blocks and display toggles get dropped one at a time without any of the surviving lines looking wrong.

The three shapes that keep doing this

Missing breakpoint blocks. Desktop unaffected, mobile stacked wrong. Zero signal in the diff.

Orphaned display: none. An element hidden at one width on the assumption that a different element covers that case — and then the covering element gets removed or renamed. Now nothing renders there at all. The diff shows a deletion of "unused" markup.

Reveal-on-scroll that never reveals. The element is in the DOM, present in view-source, passes any test that queries for it, and is invisible to a human forever because its opacity never got animated to 1.

That third one is the meanest, so it's worth taking apart.

How do you keep a scroll reveal from leaving content invisible?

Make the failure mode "shows too early" instead of "never shows," and add a hard failsafe that ignores your own logic.

IntersectionObserver reveals fail in three ways I now check for by reflex:

A negative bottom rootMargin shrinks the observation box, so the callback fires after the element is already visible to the reader — the animation plays late, or looks like a flicker. A positive margin fires early, which is what you actually want.

A large hide-transform (translateY(80px), a big scale) means the rect the observer measures is the post-transform rect. If your transform pushes the element far enough, the observer's geometry and the layout geometry disagree, and the intersection can simply never happen.

And anything above the fold on first paint may never trigger a scroll event at all.

Every one of those leaves content permanently invisible, which is the worst possible outcome for a marketing page — worse than an ugly animation, worse than no animation.

// reveal.ts — the version I ship now
export function observeReveal(el: HTMLElement) {
  // Above the fold on load: reveal immediately, never wait for a scroll.
  if (el.getBoundingClientRect().top < window.innerHeight) {
    el.dataset.revealed = "true";
    return;
  }

  const io = new IntersectionObserver(
    ([entry]) => {
      if (!entry.isIntersecting) return;
      el.dataset.revealed = "true";
      io.disconnect();
    },
    // Positive margin: fire BEFORE it enters view, not after.
    { rootMargin: "0px 0px 15% 0px", threshold: 0 }
  );

  io.observe(el);

  // Failsafe: whatever the observer thinks, this content becomes
  // visible. A broken animation beats a blank section.
  setTimeout(() => {
    el.dataset.revealed = "true";
    io.disconnect();
  }, 3000);
}

The hide state pairs with a small transform — 16px, not 80 — so layout and observer geometry stay in agreement:

[data-reveal] { opacity: 0; transform: translateY(16px); }
[data-reveal][data-revealed="true"] { opacity: 1; transform: none; }

The setTimeout is the part I'd have argued against a year ago as sloppy. I don't anymore. It converts an entire class of invisible-content bugs into a mild timing artifact, and it costs three lines.

What does a browser check look like when there's no QA team?

It's a script that opens real Chrome at the widths you actually ship at and saves a screenshot of each one, and you look at them.

I already had this lying around for a different reason. Our demo recordings are driven by Playwright — a real browser walking the full product flow with no human in the loop, which I wrote up separately. Once you have a harness that can drive a live page and wait for it to settle deterministically instead of guessing at timeouts, pointing it at a landing page across breakpoints is a ten-line job.

const WIDTHS = [390, 768, 1280, 1728];

for (const width of WIDTHS) {
  const page = await browser.newPage({ viewport: { width, height: 900 } });
  await page.goto(url, { waitUntil: "networkidle" });
  await page.screenshot({ path: `shots/${width}.png`, fullPage: true });
}

That's it. No pixel diffing, no baselines to maintain, no flaky visual-regression suite that I'd start ignoring within two weeks. Four images I look at with my eyes.

What I'm actually looking for

Large blocks of empty vertical space — that's an element that failed to render or is sitting at opacity 0. A section that appears at 1280 and vanishes at 768 without a mobile counterpart taking its place. Text that wraps to five lines in a container built for two. And any image slot that's a blank rectangle, which is the failure mode after an asset purge.

That last one is worth calling out. I recently stripped a pile of unused Framer template images and the dead <img> refs pointing at them, and deleted the orphaned components that came with them. On paper that's the safest kind of change — removing code nothing uses. In practice "nothing uses it" is a claim about the whole render tree at every viewport, and the diff can only show you the deletion.

Which changes get a browser check and which don't?

Anything that touches a breakpoint, toggles visibility, deletes an asset, or moves a route. Everything else I merge on the diff.

That's a deliberately narrow list, because a rule I apply to every change is a rule I'll stop applying. Backend logic, schema changes, agent prompts, API routes — I trust tests and the diff. But the four categories above share a property: their failure is invisible in text and obvious in a browser.

Route moves earned their spot recently. I folded apps/landing into the Artemis app so the marketing site and the builder live in one place — landing at the root, builder at /create. Every individual file move was correct. Whether the combination of moves left a working site is not a question source code answers. Our deploy.sh verify step checks real URLs after deploy, including accepting the post-teardown redirects from the retired catalog, and it's the only thing that actually knows.

What about bugs that only exist in a browser at all?

Some errors have no source-code representation, and hydration is the clearest example.

Artemis had a hydration mismatch I could not see anywhere in the code, because it wasn't in the code — it came from the DOM being modified before React hydrated, in a real browser with real extensions installed. Server HTML and client HTML disagreed for reasons no file in the repo mentioned. The fix was pinning a vendored dependency to a known-good version and gating the injected case explicitly. No amount of diff-reading would have found it; it needed a browser with the extension installed, which is to say, a normal user's browser.

This is the same principle underneath all of it, and it's why Kynth Apollo — our capabilities layer, where every hard problem gets solved once and reused — holds the browser harness alongside everything else. Artemis assembles apps out of those finished pieces. A piece that renders correctly at one width and disappears at another isn't finished, and there's exactly one place you can find that out.

Open the browser. Four widths. Look at the pictures.

Recording product demos with Playwright and no human

Isaiah Kim — Tue, 21 Jul 2026 14:21:06 +0000

I record full product demos with no human touching the keyboard — a real Chrome instance drives the app end to end, clicks through the flow, and a recorder captures every frame. The interesting part turned out not to be the clicking. It was deciding when the page was actually ready for the next step, and realizing the thing I'd built was a state machine wearing a recorder's clothes.

Here's what I learned building it for Kynth, where the demos have to look hand-driven even though nobody's there.

Why do fixed timeouts break automated demos?

Fixed timeouts break because they encode a guess about the network and the machine, and both change under you. The classic version is await page.waitForTimeout(2000) after a navigation. On my laptop with a warm cache, 2000ms is 1500ms of dead air on camera. On a cold CI runner rendering the same page, 2000ms is 400ms short and I capture a spinner mid-flight — a demo that pauses awkwardly, then jump-cuts into a half-loaded dashboard.

You can't win this by tuning the number. A bigger timeout wastes screen time on every fast run; a smaller one flakes on every slow one. The number is wrong in both directions at once because it's answering the wrong question. I don't care that 2 seconds passed. I care that the page stopped changing.

So the whole recorder is built around one idea: settle-detection. Instead of waiting a duration, wait for the DOM to go quiet.

What "settled" actually means

A page is settled when nothing meaningful has mutated for a short quiet window. I watch the DOM with a MutationObserver injected into the page, reset a timer on every mutation batch, and consider the page ready when the timer survives, say, 350ms untouched — plus network idle, because a settled DOM that's still waiting on an XHR is about to un-settle.

// runs inside the page via page.evaluate
async function waitForSettled(quietMs = 350, maxMs = 8000) {
  return new Promise<void>((resolve) => {
    let last = performance.now();
    const obs = new MutationObserver(() => { last = performance.now(); });
    obs.observe(document.body, {
      childList: true, subtree: true,
      attributes: true, characterData: true,
    });

    const started = performance.now();
    const tick = () => {
      const now = performance.now();
      if (now - last >= quietMs) { obs.disconnect(); resolve(); }
      else if (now - started >= maxMs) { obs.disconnect(); resolve(); } // hard ceiling
      else requestAnimationFrame(tick);
    };
    requestAnimationFrame(tick);
  });
}

The maxMs ceiling matters more than it looks. Some pages never fully go quiet — a looping CSS animation, a polling badge, an SSE connection nudging a counter. Without the ceiling, settle-detection waits forever for a page that's never going to be still. So it's settle-with-a-deadline: quiet wins if it can, the clock wins if it can't. That single fallback is the difference between a recorder that's robust and one that hangs on a <marquee>.

Why is a demo recorder really a state machine?

A recorder is a state machine because every step depends entirely on the exact state the last step left the app in, and the hard bugs all live in the transitions, not the actions. I didn't set out to build one. I started with a flat script — click, wait, click, wait — and it worked until it didn't, and every time it broke it was because step N assumed a screen that step N-1 didn't actually produce.

Once I named the states, the failures got legible. The recorder moves through explicit nodes — boot, landing, demo-open, flow-step-k, result, teardown — and each transition has three parts: an action (the click), a settle (wait for quiet), and an assertion (prove we landed where we meant to). If the assertion fails, I don't blindly continue into a black recording. I know exactly which edge broke.

The assertion is the part people skip

The temptation is to trust that clicking a button lands you on the next screen. It usually does. But "usually" is how you get a 90-second video where seconds 40 through 55 are a modal that failed to open, recorded in full confidence. So every transition ends by asserting the target state exists before the camera is allowed to move on:

async function transition(page, edge) {
  await edge.act(page);            // e.g. click "Run demo"
  await settle(page);              // DOM quiet + network idle
  const ok = await edge.assert(page);  // target state visible?
  if (!ok) throw new StateError(edge.from, edge.to);
  return edge.to;
}

Modeling it as a machine also gave me retries for free. A flaky edge — a cold Supabase connection that 500s the first time, an auth redirect that resolves a beat late — can retry just that transition from a known state, instead of tearing down and re-recording the whole demo from boot. When you're rendering these for real, re-running one edge versus the whole flow is the difference between a 3-second recovery and starting over.

How do you keep an automated flow from looking robotic?

You add human-shaped pacing back in on purpose, after settle-detection has removed the accidental pauses. This felt backwards at first. I spent all this effort deleting dead air, then deliberately put some back — but the two kinds of waiting are different. Settle-detection removes the pauses that come from not knowing the page is ready. Then I add small, intentional dwell before a click so a viewer's eye can land on the button before it depresses.

The rule I settled on: settle to zero, then dwell to taste. Settle-detection guarantees the floor — we're never recording a spinner. The dwell is a fixed, small, deliberate beat layered on top, and because it sits on a known-quiet page it reads as a person deciding, not a script stalling. Crucially the dwell is constant across machines; the settle absorbs all the variance. Fast runner or slow, the rhythm of the final video is identical, which is the whole point when these get cut together.

Settle-detection is a recording primitive, not a test trick

The waiting strategy that makes a good recorder is the same one that makes a good end-to-end test, which is why this generalizes past demos. A test that waits for settle instead of a timeout is a test that doesn't flake and doesn't waste minutes of CI on padding. The demo harness and the test harness want the identical thing: proof that the app reached a state, not proof that time passed.

That overlap is why the recorder lives next to the app in the Turborepo monorepo rather than in some separate video project. It drives the real Next 16 app against real Supabase and Stripe — the same stack a user hits. When FetchDue went live the weekend of July 18, the recorded run that proves it works — a real reply classified, a real answer drafted, a real email delivered — came out of this exact harness driving the live product. No mock, no staged screen. The camera watched Chrome do the thing a customer does.

What I'd tell someone building this

Stop tuning the timeout and start watching the DOM. Almost every flaky wait in an automated flow is a fixed duration standing in for a state you could have observed directly. Replace it with settle-with-a-deadline — quiet window plus a hard ceiling — and the whole class of "worked on my machine, flaked in CI" problems goes away, because you stopped guessing at time and started measuring readiness.

The state-machine framing is the other half. The moment you write down the states and make each transition assert its target, your failures tell you which edge broke instead of leaving you a black video and a shrug. And you get per-edge retries as a bonus, which is what makes recording against a real backend — where a cold connection occasionally hiccups — tolerable instead of maddening.

This recorder is one of the pieces inside Kynth Apollo, the layer where I solve a hard problem once and never solve it again. Every demo, every product screenshot, every proof-it-works run pulls from the same harness now. That's the quiet luxury of building this way: the second time you need a driven browser, you're not building — you're composing.