DEV Community: Digital Craft Workshop

Replaying 10,000 Production Fingerprints Through JSDOM in 30 Seconds

Digital Craft Workshop — Sun, 06 Sep 2026 15:02:51 +0000

Replaying 10,000 Production Fingerprints Through JSDOM in 30 Seconds

I had ten thousand selectors sitting in a Postgres table and I was not sure the code that wrote them was still compatible with the code that read them. Parser strictness, schema renames, scoring algorithm changes. Any of them could have drifted between writer and reader.

Unit tests cannot cover this; fixtures only contain what I remembered to write. The honest move is to replay production data through current code and count what survives.

It took one CSV export and fifty lines of Node, in thirty seconds, to get a clear answer about compatibility over 10,000 records.

The setup

Export the stored fingerprints to a CSV:

COPY (
    SELECT id, fp
    FROM element_fingerprints
    ORDER BY id
    LIMIT 10000
) TO STDOUT WITH CSV HEADER;

Each fp is a JSON blob like:

{
    "Ver": "v3",
    "Txt": "Submit",
    "Sels": [
        { "Sel": "button[type=\"submit\"]", "Prio": 2, "Count": 1, "Offset": 0, "IsStateful": false },
        { "Sel": ".form button",            "Prio": 2, "Count": 3, "Offset": 2, "IsStateful": false }
    ]
}

The question I want to answer: can every stored selector still be parsed by the current code path? Every call ends in document.querySelector(sel), so what I actually need to check is whether the browser's CSS parser accepts the string.

You don't need a browser to answer that. JSDOM ships with a CSS selector engine that implements the same W3C Selectors grammar Chrome uses. That is enough to validate selector strings without booting a browser.

Postgres COPY to CSV to Node and JSDOM, ending in a compatibility tally | Generated with Claude

The script

const fs = require('fs');
const { JSDOM } = require('jsdom');
const doc = new JSDOM('<!DOCTYPE html><body></body>').window.document;

function parseCsv(text) {
    const rows = []; let field = '', row = [], inQuotes = false, i = 0;
    while (i < text.length) {
        const c = text[i];
        if (inQuotes) {
            if (c === "'" && text[i+1] === "'") { field += "'"; i += 2; continue; }
            if (c === "'") { inQuotes = false; i++; continue; }
            field += c; i++; continue;
        }
        if (c === "'") { inQuotes = true; i++; continue; }
        if (c === ',') { row.push(field); field = ''; i++; continue; }
        if (c === '\n') { row.push(field); rows.push(row); row = []; field = ''; i++; continue; }
        if (c === '\r') { i++; continue; }
        field += c; i++;
    }
    if (field || row.length) { row.push(field); rows.push(row); }
    return rows;
}

const rows = parseCsv(fs.readFileSync('./fingerprints.csv', 'utf8'));
rows.shift();

let totalSelectors = 0, invalidSelectors = 0;
let fullyCompatible = 0, partially = 0, allInvalid = 0, emptySels = 0;
const invalidExamples = [];

for (const [id, fpRaw] of rows) {
    if (!fpRaw || fpRaw === 'null') { emptySels++; continue; }
    const fp = JSON.parse(fpRaw);
    if (!Array.isArray(fp.Sels) || fp.Sels.length === 0) { emptySels++; continue; }

    let ok = 0, bad = 0;
    for (const s of fp.Sels) {
        totalSelectors++;
        try { doc.querySelector(s.Sel); ok++; }
        catch { bad++; invalidSelectors++; if (invalidExamples.length < 20) invalidExamples.push(s.Sel); }
    }

    if (ok === 0) allInvalid++;
    else if (bad > 0) partially++;
    else fullyCompatible++;
}

console.log({
    totalRows: rows.length,
    fullyCompatible,
    partially,
    allInvalid,
    emptySels,
    totalSelectors,
    invalidSelectors,
    invalidRatio: (invalidSelectors / totalSelectors * 100).toFixed(3) + '%',
    invalidExamples: invalidExamples.slice(0, 5)
});

Run it:

node validate.js

Output:

{
  totalRows: 10000,
  fullyCompatible: 9956,
  partially: 0,
  allInvalid: 0,
  emptySels: 44,
  totalSelectors: 221693,
  invalidSelectors: 0,
  invalidRatio: '0.000%',
  invalidExamples: []
}

The replay verdict from node validate.js | Generated with Claude

Why this matters more than unit tests

Your unit test suite probably has a dozen selector fixtures. Maybe a hundred. Production has patterns you didn't anticipate:

div[tracker="[object Object]"] — yes, someone's app stringified an object into an attribute
.dark\:border-gray-800 .w-full — escaped Tailwind variant colons
.group-hover\:bg-background-50 — 12 such classes chained together
label[for="mat-mdc-checkbox-10-input"] — Angular Material
label[for="radix-:r7:"] — Radix UI's colon-slug ids (these we filter out at capture, but old data still has them)

Most fixtures I've written are five or six selectors I remembered to type. The replay covered 221,693 stored ones at once.

What JSDOM catches that a type check won't

TypeScript checks the shape of fp.Sels[i] but not whether the string inside is a valid CSS selector. The CSS grammar has its own error modes: unclosed brackets, unknown pseudo-classes, malformed escapes. The only way to catch them cheaply is to run them through a parser.

The parser does a lot of small things you do not notice when you write a fixture. It tokenises the input, checks bracket balance, validates pseudo-class names, and either returns a node or throws. The throw is the only signal I care about here; the node lookup is a side effect.

That is why this loop scales linearly with selector count and not with DOM size. The DOM has one body element. The parser runs the full string-to-AST pipeline on every selector I feed it. On 221,693 selectors that pipeline took about thirty seconds on a laptop, single-threaded, no warm-up.

You might worry about using JSDOM's parser to stand in for the browser's. They're not literally the same implementation, but for CSS selector syntax both implement the W3C grammar. The invalid selectors JSDOM rejects are the ones Chrome will also reject. (If you want certainty, run the same script under puppeteer and call page.evaluate(sel => document.querySelector(sel)) — same result, minutes instead of seconds.)

Sidebar: this kind of "use a cheap tool to validate against reality" move is one of the patterns I keep coming back to as a solo builder. I have a free email series, AI as a Solo Founder's Tool, that walks through more of them.

Making it a CI job

The thirty-second runtime is the interesting part. This isn't a "once a quarter" audit — it's a cheap pre-deploy check you can run on every PR that touches the fingerprint code:

- name: Fingerprint compatibility check
  run: |
    psql -c "COPY (SELECT id, fp FROM fingerprints ORDER BY random() LIMIT 5000) TO STDOUT WITH CSV HEADER" > sample.csv
    node scripts/validate-fingerprints.js sample.csv --fail-on-regression

I take a random sample of 5,000 from the production table and compare it against the baseline (fullyCompatible / totalRows). If the ratio drops by more than 1%, the PR fails. The threshold is tunable; I started at 1% and have not had to change it.

Generalizing the pattern

I use the same loop on more than fingerprints. Any time three things line up, the trick works:

You have stored structured data (selectors, queries, configs, serialized state).
Code consumes that data with a parser somewhere in the path.
The parser can reject inputs the writer thought were valid.

The three conditions that make replay-based validation worth running | Generated with Claude

Whenever that triangle exists, replay-based validation is worth running. A handful of examples from our own codebase:

SQL queries stored for saved reports → run each through EXPLAIN and check for errors
Zod schemas versioned over time → re-validate last month's records against this month's schemas
Mongo aggregation pipelines saved in documents → dry-run them against db.runCommand({aggregate, explain:true})
Regex patterns stored in a rules engine → compile each; anything that throws is a stored record you can't read anymore

It's the cheapest form of backward-compatibility testing you'll ever write, and it's quantitative: instead of "I think it still works," you get "99.56% are fully compatible; the other 44 had empty selector lists I can investigate one at a time." It pairs naturally with a pre-push validation step that watches for the kind of drift this script measures.

External Sources

JSDOM — Node.js DOM implementation used as the parser
W3C Selectors specification — CSS selector grammar
Puppeteer documentation — headless Chrome alternative for browser-grade verification
happy-dom — faster DOM alternative referenced in the post
PostgreSQL COPY command — used to export the fingerprint CSV

Production is the test suite I didn't write

I had a year of production data I had never used as a test. I left mine sitting in Postgres because some half-formed worry told me I could not run real data locally. I could. Thirty seconds and fifty lines of JavaScript. The replay took thirty seconds. I should have done it the first week.

If this kind of cheap reality-check is useful, I write up more of them in a free email series, AI as a Solo Founder's Tool.

I build small tools and kits for solo creators. You can find them here: https://danielrusnok.gumroad.com

My App Returned 403 But My Code Never Did

Digital Craft Workshop — Fri, 04 Sep 2026 15:04:09 +0000

Not a member? Use this friend link to read this story for free.

My Drippery autosaves started returning 403 on one specific email series. I spent the next two hours searching the codebase for a status code my code does not emit.

The hosting platform was rejecting the request before it ever reached my Node process, because the JSON body contained raw HTML.

Here is the debugging trail, the root cause, and the 40-line fix.

The edge WAF blocks the POST before the Node app ever sees it | Generated with Claude

The app and the endpoint that broke

I am building Drippery, a drip email tool for content creators. Users write emails in a rich text editor and the app saves the HTML to PostgreSQL.

The stack is Next.js 16, Clerk auth, Drizzle ORM, PostgreSQL, hosted on Render.com.

The bulk-save endpoint receives every change to an email series in a single POST. A typical payload looks like this.

{
  "sequence": { "name": "My Newsletter Series" },
  "updatedEmails": [
    {
      "id": "abc-123",
      "subject": "Welcome!",
      "html": "<h1>Welcome to the series</h1><p>Here is what you will learn...</p>",
      "textContent": "Welcome to the series...",
      "dayOffset": 0,
      "enabled": true
    }
  ],
  "emailOrder": ["abc-123"]
}

Nothing suspicious. Clean HTML, no script tags, no event handlers. Just formatted email content wrapped in a JSON string.

Saving this payload should have been the most boring operation in the app. It wasn't.

Sidebar: debugging trails like this one live in my Claude Code sessions, and keeping that context between sessions is its own small problem. The Claude Code Memory Starter is a free email series on how I solved it.

A 403 that reproduced every time

One specific series with five emails, about 11 KB of total HTML, failed on every save attempt. The browser console showed the same line three times in a row.

POST /api/series/c91e0a38-.../bulk-save 403 (Forbidden)

Three autosave attempts in a row, every one a 403. The response body was the same every time. I had not yet bothered to open it.

Searching for a 403 that does not exist

My first instinct was to grep the codebase for the status code.

grep -rn "403" src/app/api/
# (no matches)

The bulk-save endpoint only returns 401 for unauthorized requests and 500 for unexpected errors. The 403 I was chasing was nowhere in my own code.

I checked the auth middleware next. The app runs Clerk with auth.protect().

// src/middleware.ts
export default clerkMiddleware(async (auth, req) => {
  if (!isPublicRoute(req)) {
    await auth.protect();
  }
});

I dug into Clerk's source. On API routes auth.protect() hides protected endpoints by returning a 404, not a 403. Clerk was not the source either.

Next.js 16 ships CSRF protection for Server Actions, not for API route handlers, and none of the experimental error-handling flags that could short-circuit a request were enabled in my config. So I added debug logs everywhere.

// bulk-save/route.ts
console.log(`[bulk-save] Request received for sequence ${id}`);
const tenant = await getCurrentTenant();
console.log(`[bulk-save] Tenant ${tenant.id} saving sequence ${id}`);

The logs never appeared. The request was never reaching my application code in the first place.

What the response body actually said

I finally opened the full response body of the 403 in DevTools. It was not JSON.

Your request was blocked by this site's
web application firewall (WAF).

The edge WAF in front of Render was intercepting the POST before it reached my app. The JSON body contained raw HTML — <h1>, <p>, <a href="..."> — and the firewall's pattern matcher flagged it as a potential XSS injection.

Legitimate email content wrapped in a JSON string field had the same shape as an attack payload, as far as the firewall was concerned.

The 403 response body was the WAF block page, not JSON | Generated with Claude

Why this took two hours

The 403 status code sent me the wrong way from the start. My reflex was to grep my own code first. When the code does not produce that status, I start doubting the auth library, then the framework, then anything in between. Infrastructure is the last layer I suspect.

The missing logs reinforced the wrong theory. Because the WAF blocked the request before Node ran, there was nothing in the application log. No exception, no failed request entry. From the app's perspective the call simply did not exist.

I spent an embarrassing amount of time inside Clerk's TypeScript definitions, looking for a branch that could throw a 403 instead of a 401. Then another half hour reading the Next.js 16 changelog for any new CSRF or rate-limit middleware I might have inherited from an upgrade. Both were dead ends, but they felt closer to the code, so they got my attention first.

The minimal repro that finally pinned the blame on the edge was a pair of curl calls. The endpoint accepted a small body with no HTML. Strip the HTML, status 200. Drop a single raw <h1> tag into the same body, status 403. That was the moment the WAF hypothesis stopped feeling speculative.

And it was payload-dependent. Small emails saved fine. The WAF only blocked the request once the HTML content was large enough to match its rule set, so the failure looked like a content-specific bug in my own code, not a piece of infrastructure I had never thought about.

The fix: base64 in transit

The shape of the fix is small. Base64-encode the HTML fields on the client, decode them on the server before writing to Postgres.

The shared encoding helper has to be Unicode-safe, because plain btoa() throws InvalidCharacterError the moment a user pastes an accented character or an emoji.

// src/lib/html-encoding.ts

/** Encode a string to base64 (Unicode-safe) */
export function encodeHtml(html: string): string {
  if (!html) return html;
  const bytes = new TextEncoder().encode(html);
  let binary = '';
  for (let i = 0; i < bytes.length; i++) {
    binary += String.fromCharCode(bytes[i]);
  }
  return btoa(binary);
}

/** Decode a base64 string back to HTML (Unicode-safe) */
export function decodeHtml(encoded: string): string {
  if (!encoded) return encoded;
  const binary = atob(encoded);
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < binary.length; i++) {
    bytes[i] = binary.charCodeAt(i);
  }
  return new TextDecoder().decode(bytes);
}

The TextEncoder dance is the only non-obvious part. It serializes the string into UTF-8 bytes that btoa() can safely process, then reverses the same trip on the way back.

I considered cheaper transformations before reaching for base64. HTML-escaping the angle brackets keeps the body human-readable but still leaves the dangerous substrings the WAF is matching on. URL-encoding shifts the bytes around without changing what the pattern matcher sees. Base64 is the smallest transformation that mangles the patterns enough for the rule set to ignore the body entirely.

On the client, encode every HTML field before sending.

const res = await fetch(`/api/series/${id}/bulk-save`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    newEmails: newEmails.map((e) => ({
      ...e,
      html: encodeHtml(e.html),
      textContent: encodeHtml(e.textContent),
    })),
    updatedEmails: updatedEmails.map((e) => ({
      ...e,
      html: encodeHtml(e.html),
      textContent: encodeHtml(e.textContent),
    })),
  }),
});

On the server, decode before writing to the database.

import { decodeHtml } from '@/lib/html-encoding';

const [created] = await db.insert(emails).values({
  html: decodeHtml(newEmail.html),
  textContent: decodeHtml(newEmail.textContent) || '',
});

await db.update(emails).set({
  html: decodeHtml(updated.html),
  textContent: decodeHtml(updated.textContent),
});

The WAF now sees PGgxPkhlbGxvIFfDtnJsZCE8L2gxPg== instead of <h1>Hello World!</h1>. No HTML patterns in the body, no firewall trigger.

Same request before and after base64 encoding the HTML field | Generated with Claude

Every other endpoint I had to patch

Once I had the root cause I audited every endpoint that accepts HTML in a POST or PATCH body.

/api/series/[id]/bulk-save — POST, html + textContent
/api/series/[id]/emails — POST, html + textContent
/api/series/[id]/emails/[emailId] — PUT, html + textContent
/api/emails/send-test — POST, html + textContent
/api/tenant — PATCH, emailHeader + emailFooter

All of them needed the same encode-on-client, decode-on-server treatment. Bulk-save just happened to trip first because it sends the most HTML in a single request.

Five HTML-accepting endpoints, all routed through one base64 helper | Generated with Claude

This is the same fan-out audit I did when chasing memory leaks in the Next.js crash story. Find the root cause, then assume the rest of the surface area has the same shape.

What I would do differently

The two-line lesson is: read the full response body before searching your codebase. If I had opened the 403 body in DevTools first, I would have seen the WAF page and solved this in minutes.

The deeper lesson is to think in layers. When your application log is empty for a failed request, the request was intercepted upstream by a WAF or a reverse proxy. The absence of a log entry is itself a signal.

A WAF does not understand context. It sees <script> in a POST body and blocks it. It does not know the HTML is a value inside a JSON string field that will be stored in a database and rendered in a completely different context. Base64 is a pragmatic workaround for that context mismatch.

There is a real cost to the workaround. Base64 inflates the payload by about thirty-three percent, and the request body in any proxy log is now opaque, so a support ticket where a user reports broken HTML is harder to reproduce without first running the body through the decoder. I accept that. The alternative was a daily false-positive 403 in production, which was worse.

Render does let you configure rules and disable categories, but turning the WAF off entirely removes protection against actual attacks. Base64 keeps the protection in place for everything else while routing legitimate HTML around the false positive.

Custom WAF rules that allowlist specific paths are another option where the host supports them. Encoding is portable: it works regardless of who runs the firewall in front of your app.

I push every change in Drippery straight to production, so I care about exactly which safety nets are in front of my code. The same logic I use in my pre-deploy script applies here. I want the safety nets. I just want to know which payloads they eat.

External Sources

Render network protection — what sits in front of every Render service by default
OWASP XSS overview — why WAFs aggressively reject raw HTML in request bodies
MDN TextEncoder — the Unicode-safe primitive used in the encode helper
MDN base64 — why btoa alone breaks on non-ASCII input

TL;DR

My SaaS endpoint returned 403 but my code never emits that status.
The full response body was an HTML page from the edge WAF, not JSON.
The WAF flagged raw HTML inside the JSON POST body as potential XSS.
The fix is base64-encoding HTML fields on the client and decoding them on the server.
Audit every endpoint with the same payload shape; they will all eventually trip.

If you want more of this in your inbox, The Claude Code Memory Starter is a free email series on keeping your tooling's context — and your own — between sessions.

I build small tools and kits for solo creators. You can find them here: https://danielrusnok.gumroad.com

Don't Trust AI-Generated Code Without Testing It First

Digital Craft Workshop — Wed, 02 Sep 2026 15:04:07 +0000

I let an AI refactor a database query in my .NET project. The code looked clean. I glanced at it, nodded, committed, and pushed. Then QA pinged me with a stack trace.

The error: InvalidOperationException: Lambda expression used inside Include is not valid.

The AI had used a filtered .Include() with a .Where() clause inside. That syntax shipped in Entity Framework Core 5.0. Our project runs on EF Core 3.1. The AI did not check the version, and on a busy afternoon I did not either.

That moment, staring at the error in the QA environment and knowing I had rubber-stamped AI output without ever running the code, was one of the most embarrassing moments in my recent career. The bug was not complex. I had every tool to catch it and I let it through anyway.

The Task Was Simple

I was fixing an export feature for our Knowledge Base. The original query worked but had a suboptimal structure. It loaded data through ArticleFeedbacks and joined articles on the side. I wanted to flip the approach: start from ArticlesContents, include the related data, and filter feedbacks inline.

The AI rewrote the query into a single LINQ expression with filtered includes:

return await this.database.ArticlesContents
    .Include(a => a.Article).ThenInclude(a => a.Category)
    .Include(a => a.Article).ThenInclude(a => a.ArticlesViewsSimple)
    .Include(a => a.ArticleFeedbacks
        .Where(f =>
            (string.IsNullOrEmpty(source) || f.Source == source) &&
            (!dateFrom.HasValue || f.CreatedAt >= dateFrom.Value) &&
            (!dateTo.HasValue || f.CreatedAt < dateToEndOfDay.Value)))
    .Where(a => a.Article.ProjectId == projectId && !a.IsDeleted && !a.Article.IsDeleted)
    .OrderByDescending(a => a.CreatedAt)
    .ToListAsync();

The filtered Include syntax, where you pass a .Where() lambda inside .Include(), was one of the headline features of EF Core 5.0. It shows up everywhere in modern .NET tutorials and Stack Overflow answers from the last few years.

We are on EF Core 3.1. In 3.1, the only valid argument to .Include() is a simple navigation property expression. No filtering. No logic. Just a => a.ArticleFeedbacks, and the query plan flows from there.

The AI Hallucinated a Newer Framework

AI coding assistants are trained on a lot of code. They have seen millions of EF Core queries, most of them from newer versions. The filtered Include pattern is everywhere in modern .NET content, from official samples to weekend blog posts.

The AI does not open my .csproj file to read the package version. It does not know I have a project pinned to a legacy framework version. It generates what looks correct based on the most common patterns it has learned across the corpus, and most of that corpus assumes a newer EF Core than the one I actually ship against.

The query would compile against a project a few framework versions ahead of mine. In mine, it crashed at runtime as soon as the export endpoint was hit.

I have seen this pattern repeatedly with AI-generated code:

It uses APIs that exist in newer versions of your framework
It imports packages you do not have installed
It uses syntax from a language version your compiler does not support
It assumes configuration or infrastructure that does not exist in your environment

The AI optimizes for code that matches the bulk of its training data. The bulk of that training data sits on newer framework versions than the legacy projects most working developers actually maintain. That mismatch shows up at runtime rather than at compile time, often inside the very request that hits the real database for the first time after the change.

How a version-blind suggestion lands in a legacy project. | Generated with Claude

If you'd rather have the setup that keeps my AI assistant from repeating these mistakes, I put it into The Claude Code Memory Starter — a free email series.

The Real Problem: My Review Process

The AI making a mistake is not where I want to focus. The story is that I did not catch it.

I looked at the code. It made logical sense. The query structure was clean. The filtering was correct. I thought "yeah, that is better than what we had" and moved on.

I did not:

Run the application locally
Hit the export endpoint even once
Write or run a single test against it
Check if filtered Include was supported in our EF Core version

I treated the AI output like code from a senior colleague I trust completely. The AI is no senior colleague. It generates plausible code without knowing my project constraints, and on a quiet afternoon it will hand me a snippet that compiles in a different version of the world.

When QA pinged me, my first reaction was confusion. The query looked fine in the diff. I pulled the branch, ran the export endpoint locally, and got the same stack trace on the first request. The fix took less time than the conversation about the bug.

Load all feedbacks via a plain .Include(a => a.ArticleFeedbacks) and filter them in memory after materialization:

var results = await this.database.ArticlesContents
    .Include(a => a.Article).ThenInclude(a => a.Category)
    .Include(a => a.Article).ThenInclude(a => a.ArticlesViewsSimple)
    .Include(a => a.ArticleFeedbacks)
    .Where(a => a.Article.ProjectId == projectId
        && !a.IsDeleted && !a.Article.IsDeleted)
    .OrderByDescending(a => a.CreatedAt)
    .ToListAsync();

foreach (var content in results)
{
    content.ArticleFeedbacks = content.ArticleFeedbacks
        .Where(f =>
            (string.IsNullOrEmpty(source) || f.Source == source) &&
            (!dateFrom.HasValue || f.CreatedAt >= dateFrom.Value) &&
            (!dateTo.HasValue || f.CreatedAt < dateToEndOfDay.Value))
        .ToList();
}

A 30-second fix for a bug that should never have shipped. Running the code once would have caught it, and one local hit on the export endpoint was the difference between a silent commit and a QA ticket.

This is the same instinct I now put behind every git push. I wrote about wiring a code-reviewer subagent in front of every push to main for exactly this reason. The hook reads the diff before the push actually goes out and flags the kinds of things I would normally only notice during a slow PR review, which gives me a second pair of eyes on every commit even when I am working alone.

The Embarrassment Factor

Let me be honest about why this stung. I have been writing C# and working with Entity Framework for years. If a junior developer on my team had submitted this code in a pull request, I would have caught the filtered Include issue immediately and left a comment on the line.

Because the AI generated it, I treated it differently. There is something about AI-generated code that short-circuits the normal review instinct. The structure is professional. The variable names are sane and the indentation is consistent, so the eye glides over it without ever landing on the lambda inside the Include.

So I let my guard down.

Then QA finds a crash, and I am sitting there explaining that I pushed code I never ran because "the AI wrote it and it looked fine."

That is not a good look for anyone.

It is also not the first time I have had to rethink how I work with AI. I went from treating AI like a faster Google to actually pairing with it on real changes. As my trust grew, the verification gap got bigger instead of smaller. The well-structured looking diffs are the ones I now have to remind myself to actually read, because the polish is what makes them feel safe to skim.

The same diff in my editor and in QA. | Generated with Claude

The AI-as-a-tool workflow behind posts like this is a short email series I run — AI as a Solo Founder’s Tool.

Five Rules I Follow Now

After this incident I changed how I work with AI coding assistants. These are not theoretical guidelines. They are rules I follow because I got burned in QA in front of the whole team and I would prefer not to repeat the experience.

Rule 1: Always run it. No exceptions. If the AI changes a query, I hit that endpoint locally before committing. If it modifies a component, I open the browser and click through the happy path at least once. The minimum bar is that the code runs end-to-end on real data without throwing.

Rule 2: Check version-sensitive APIs. When the AI uses a method or pattern I am not certain about for my current framework version, I verify. A quick search for "EF Core 3.1 filtered include" would have saved me in 30 seconds. The same is true for anything tied to a package version, an SDK version, or a runtime that the AI cannot see from the prompt.

Rule 3: Treat AI output like a PR from a new hire. Smart, probably correct, but worth a second look. I read every line and question the assumptions baked into the diff. If I would push back on a teammate's PR for missing a test on a behavior change, I push back on the AI's output the same way.

Rule 4: Don't let clean code fool you. The most dangerous AI-generated bugs are in code that looks perfect. Syntax errors are easy to catch in review. Version incompatibilities in well-structured code slip through because the reviewer brain says "this looks like what a senior would write" and quietly stops working.

Rule 5: Own the code. The moment I commit it, it is mine. "The AI wrote it" is not an excuse anyone wants to hear in a postmortem. I review the diff like I wrote it, because once it is in the repo, I did.

I treat these like a seatbelt: boring, repeatable, applied even when I am tired and the laptop fan is loud. My AI workflow also changed how I write comments, but these five rules are the ones that actually live in muscle memory now. I do not always remember them at the start of a task. I remember them at the moment my finger hovers over git push, which turns out to be enough.

Faster Is Only Faster If It Ships Clean

AI coding assistants are genuinely useful. I use them every day. They save time on the boilerplate I would otherwise type by hand, and they let me move through a sprint at a pace I could not sustain alongside a side project and a small daughter at home.

Moving faster only counts if I am moving in the right direction. Shipping broken code faster is a liability dressed up as a productivity gain.

The developer community is going through an awkward phase with AI tools. We are past the "wow, it can write code" excitement and not yet at the point where we have built reliable habits for verifying AI output. The tools are good enough to be dangerous, and the workflows around them have not fully caught up to that reality.

Every minute I save by skipping a test of AI-generated code, I pay back with interest when something breaks at runtime, because the AI does not know my project the way I do.

When I weigh the cost of running the code locally against the cost of a stack trace landing in QA the next morning, the local run is always cheaper. So I run it. Then I push.

\→ Get it free: AI as a Solo Founder’s Tool, a 5-part email series.

External Sources

EF Core eager loading docs — official Microsoft docs on what is valid inside .Include() per version.
EF Core 5.0 announcement — Microsoft blog post listing filtered Include as a headline feature.
dotnet/efcore #1833 — the long-running GitHub issue that became filtered Include in EF Core 5.
ASP.NET Core integration tests — official guide to the kind of test that would have caught the bug in one run.

Daniel Rusnok is a solo builder shipping content, SaaS, and games.

If you want that habit as a few short emails instead of a hard afternoon, The Claude Code Memory Starter walks you through it — free.

I build small tools and kits for solo creators. You can find them here: https://danielrusnok.gumroad.com

What Upgrading to Next.js 16 Taught Me About Trusting Framework Defaults

Digital Craft Workshop — Mon, 31 Aug 2026 15:05:54 +0000

I used to think the cost of a framework upgrade was the stuff in the migration guide. The renamed APIs. The deprecated config. The list of things the maintainers tell you to change. You read it, you do the work, you move on.

That is the visible tax. It is not the one that hurts.

The tax that hurts is the convention that still compiles, still looks right, still matches the docs, and quietly does something different than it did in the last major version. No error at upgrade time. No warning in the console. Just a behavior that drifted out from under you while you were not looking. You find it weeks later, in production, when something that always worked stops working and nothing tells you why.

I learned this the slow way when I moved to Next.js 16. One file convention I had trusted for years took down a page, returned a clean 200 status, and gave me almost nothing to debug from. The fix was five lines. Finding it cost an hour. And the hour was the lesson, not the fix.

The convention I trusted

Back in April I shipped a public blog at drippery.app/blog. Brand-new Next.js 16 app, App Router, Turbopack (the bundler that replaced webpack as the Next 16 default), the works. Routes rendered fine in dev. /blog listed posts. /blog/[slug] rendered the article body, the breadcrumb JSON-LD, the FAQ schema, everything I expected.

Then I added a file-based opengraph-image.tsx next to the detail page, the way the docs say to, and the detail page stopped rendering.

A quick recap for anyone who has not used the convention. In the App Router, opengraph-image is one of the special file names that live inside a route segment. You drop a dynamic opengraph-image.tsx next to a page.tsx, export a default function that returns an ImageResponse from next/og, and Next.js evaluates it and injects the matching og:image meta tags into the <head> of every page in that segment. For a blog with dynamic slugs, each post gets its own social card, generated from the post title, with zero manual wiring.

The payoff is link previews. A page without a valid og:image shows up as a bare text link when shared, and I have written before about how much traffic one missing HTML tag can cost you.

So the plan was simple. Add the file, get per-post social cards. That is the workflow the convention promises, and on Next.js 14 it had worked for me exactly that way. I trusted it because it had earned the trust. That is the trap. The conventions you trust most are the ones that bite hardest, because you stop suspecting them.

What "broke" actually looked like

The page did not 500. It returned a 200, but the React tree was missing. The HTML shell came back, the body content did not. In the server logs:

TypeError: Cannot read properties of undefined (reading 'default')
at /app/(marketing)/blog/[slug]/page

The error fired during metadata resolution, not during the page render itself. Turbopack was trying to import the opengraph-image module to compute the <meta> tag, and the dynamic import returned undefined. That crashed the whole metadata pipeline, which then silently bailed out of rendering the page.

Metadata resolution runs as part of serving the page, which is why the symptom is so confusing. When it throws, the page body never renders, even though your page component is perfectly healthy. The file I added for link previews was the thing breaking the page.

The stack trace makes it worse. It points at the page segment, because the import happens inside the framework's metadata machinery for that segment. Nothing in it names opengraph-image.tsx, which is a big part of why I spent the next hour blaming everything except the new file.

Removing the file made everything work again. Adding it back, even with a hello-world export, broke it again. My image code never ran far enough to matter.

This is what a silent breaking change feels like from the inside. The framework did not tell me the convention changed. The page just lied to me with a 200.

Why the upgrade guide will never catch this

Here is the uncomfortable part. There was nothing to read.

A migration guide can document what the maintainers changed on purpose. It cannot document the interaction between a new default bundler, a file convention, and generateMetadata that nobody set out to change and nobody noticed shifted. The Next 16 release notes told me Turbopack was now the default. They did not tell me that a convention I had used since Next 14 would behave differently underneath it, because as far as anyone knew, it would not.

That is the shape of the real upgrade tax. It is not in the changelog. It lives in the gap between what the framework says it does and what it actually does on your specific combination of features. The bigger the framework, the more conventions it ships, the more of those gaps exist. Every convention is a promise the framework makes on your behalf, and a major version is the moment those promises quietly get renegotiated without your signature.

I am not anti-convention. File-based routing, colocated metadata, auto-discovered images — these save real time and I use them every day. But I had been treating them as guarantees, and they are not guarantees. They are conveniences with an implicit asterisk: this works until a default underneath it changes. The upgrade is exactly when that asterisk comes due.

How I narrowed it down

I want to spell out the debugging sequence, because the 200 status code sent me in the wrong direction for a while, and the sequence is reusable on any "silent breakage" problem, not just this one.

My first suspicion was the data layer. The detail page pulls the post from the database by slug, and a missing post would explain an empty page. But the post was there, and the listing page that uses the same query rendered fine. Second suspicion was the structured data. I had added breadcrumb JSON-LD and an FAQ schema to the same page recently, and a malformed script tag can do strange things to hydration. Stripping those out changed nothing.

The browser console was clean the entire time. That is the trap: every signal on the client side says the page is fine, and only the server log contains the actual error. I have been burned by this exact shape before. When our Next.js app crashed every 24 hours, the visible symptom also pointed nowhere near the cause, and the server-side evidence was the only trail worth following. Same when my extension iframes painted solid white over dark-mode sites — the culprit was a CSS color-scheme default that nothing in the symptom hinted at.

Once I read the server log carefully, the stack trace mentioned the page segment, and the only recent change in that segment besides the JSON-LD was the new image file. From there it was a binary search with one variable. Delete opengraph-image.tsx, restart dev, page renders. Recreate it with the simplest possible content — a div with static text inside an ImageResponse — page breaks. At that point there was nothing of mine left in the file to blame.

That test is the one I want you to take away. If a hello-world version of the file reproduces the failure, the failure happens before your code runs. Stop auditing your own logic and start suspecting the convention. That single move is what turns an hour of flailing into a five-minute diagnosis the next time a default betrays you.

If build notes like this are your thing, The Claude Code Memory Starter is a short free email series where I unpack the setup behind them.

The fix: stop trusting the convention, wire it yourself

The lesson translated into a concrete decision. I gave up on the file-based convention for this segment and built a regular route handler instead — the kind of explicit code the framework cannot quietly change underneath me:

// app/api/og/blog/[slug]/route.tsx
import { ImageResponse } from "next/og";
import { getPostBySlug } from "@/lib/blog";

export const runtime = "edge";

export async function GET(
  _req: Request,
  { params }: { params: Promise<{ slug: string }> }
) {
  const { slug } = await params;
  const post = await getPostBySlug(slug);

  if (!post) return new Response("Not found", { status: 404 });

  return new ImageResponse(
    (
      <div>
        {post.title}
        drippery.app
      </div>
    ),
    { width: 1200, height: 630 }
  );
}

This is the same ImageResponse API the convention uses under the hood, the same JSX, the same edge runtime. The file just lives under app/api as a normal route handler, with nothing implicit about it.

Two details trip people up. params has been a Promise since Next 15 (the sync fallback is gone in 16), so await it before reading the slug. And the file needs the .tsx extension because of the JSX. Both are easy to miss when you copy a route handler template from an older project.

The route by itself does nothing for your meta tags. You wire it up in the page's generateMetadata, in the openGraph.images field:

return {
  title: post.seoTitle ?? post.title,
  description: post.metaDescription,
  openGraph: {
    images: [{ url: `/api/og/blog/${slug}`, width: 1200, height: 630 }],
  },
};

The relative URL gets resolved against your metadataBase, the base URL you set once in the root layout metadata, so the rendered tag carries the full absolute address social crawlers need. The only conceptual difference from the convention is that nothing is auto-discovered. I am wiring the URL myself.

There is a real trade-off in that sentence, so let me be fair to the convention. With the file-based approach, the framework keeps the image URL, the alt text, the dimensions, and the content type in sync for you. With the explicit route, those live in two places: the route handler defines the image, and generateMetadata declares it. Rename the route and forget the metadata object, and your og:image points at a 404 with no error to warn you.

I accept that maintenance cost on purpose. The explicit version fails as a broken preview card. The convention failed as a broken page. Those are not the same severity, and I will trade a little duplication for a failure mode I can actually see.

Why I think it happens (and why the cause is not the point)

This is a working theory. I do not have a confirmed root cause, and I want to be honest about that.

My theory is that Turbopack's dynamic import for the file-based metadata convention is not resolved correctly in the module graph when the route segment also exports generateMetadata. The docs say you can use both together, and in Next.js 14 with webpack I did. In this Next.js 16 project, the auto-imported opengraph-image module ends up as { default: undefined } at the moment metadata is resolved, and the framework calls into the missing default export and throws.

The error string has history. The Next.js issue tracker has a closed Next 13 issue with the same TypeError, thrown from React's module-resolution layer, resolveModuleMetaData. The trigger back then was client component navigation, not an image file, but the shape matches: the metadata system imports a module, the module comes back undefined, the page fails to render. That pattern made me more comfortable blaming the resolution machinery than my own code.

I also did not isolate everything. I did not retest the segment with webpack instead of Turbopack, and I did not test the convention in a segment without generateMetadata. If the combination matters the way I think it does, one of those two changes would make the file convention work again. For my project, the API route was cheaper than the experiment.

And honestly, the precise cause is not the point. A convention I trusted broke in a way no upgrade guide warned me about, and the only durable defense was to stop trusting it for this segment. Whether the bug is in Turbopack's module graph or in some interaction three layers down, the engineering response is the same: make the implicit thing explicit and move on.

How to not get burned on the next upgrade

I cannot give you a checklist that catches every silent convention change, because by definition you do not know which convention drifted until something breaks. But the upgrade taught me a handful of habits that turn a lost hour into a quick diagnosis, and they generalize past Next.js.

Suspect the new default first, not last. When a major version ships a new bundler, runtime, or compiler default, treat every "magic" convention layered on top of it as unverified until you have seen it work in your project. The thing the release notes brag about is exactly the thing most likely to have shifted behavior underneath your conventions.

Reproduce with a hello-world before you debug your own code. If replacing your logic with the simplest possible version still fails, the failure is upstream of you. This one move would have saved me most of the hour. It is the fastest way to tell "my bug" from "the framework's bug."

Read the server log, not the browser. Anything that fails during metadata resolution, server rendering, or the build will leave its real evidence server-side while the client reports a clean 200. If the symptom is on the client but the console is empty, your trail is in the server output.

Prefer explicit wiring at the boundaries that matter. I treat file conventions as optional sugar now, not guarantees. For anything load-bearing — SEO tags, social cards, anything a silent failure would cost me real traffic on — I write the explicit route and wire it by hand. Five extra lines buys a failure mode I can see, and a thing the next major version cannot quietly renegotiate.

The migration guide tells you what changed on purpose. These habits are how you survive what changed by accident. The first kind of upgrade tax you pay once, at the top of the changelog. The second kind you pay every time you trust a default a little more than it deserves.

If you want a few more of these in your inbox, The Claude Code Memory Starter walks through one of my setups over a handful of short emails — free.

I build small tools and kits for solo creators. You can find them here: https://danielrusnok.gumroad.com

How I Wired Persistent Memory Into Every Claude Code Session

Digital Craft Workshop — Fri, 24 Jul 2026 15:06:27 +0000

Not a member? Use this link.

A memory you have to remember to use is not memory. It is a database with a search bar.

That was the gap. After eight hours of a day job, on the evening shift where I do my own building, I never remembered the search bar was there. I gave Claude Code that memory last month: a mem0_search tool. Then I spent a month barely using it, because using it meant remembering it existed.

So I spent one evening wiring it into the session lifecycle itself. Now recall happens when a session opens and capture happens when it closes — both without me. Claude walks into every session already knowing what we decided last week, and closes it having written down what we decided today.

I have not typed "search your memory" in a month.

Three hooks do it. Here is the wiring.

TLDR: A Claude Code shell-command hook cannot call an MCP tool. It can only inject text. So my SessionStart hook does not do the recall — it injects an instruction telling Claude to do it, with the tools Claude already has. SessionEnd spawns a detached Python process that extracts the session's decisions with Gemini and writes them to Pinecone, after my terminal is already closed. Three scripts, around 250 lines, zero ongoing effort.

The realization: hooks inject, they don't execute

The first thing I got wrong was assuming a hook could run mem0_search itself and paste the result into context.

It can't — not the kind of hook I am using. A hook that is a shell command, which is what all three of mine are, cannot call an MCP tool. It has no MCP client. The only thing it can hand back is text: a small JSON object with an additionalContext field.

(Newer Claude Code does have an mcp_tool hook type that calls a tool directly. But a blind, unconditional tool call is not what I want here — I want Claude to decide whether and how to recall, with judgment. A command hook that injects an instruction gives me exactly that.)

That sounds like a wall. It is actually the design.

A shell-command hook does not perform the recall. It writes a prompt. It injects an instruction — "before you answer, search your memory for X" — and Claude, seeing that instruction sitting in context, runs the search with the mem0_search tool it already has. The hook is a prompt-writer. Claude is still the one doing the work, with full judgment about how to do it.

Once that clicked, all three hooks got simple. Two of them write recall instructions. One of them captures. None of them touch mem0 directly except the last — and even that one runs outside the session entirely.

Hook 1: recall the moment a session opens

SessionStart fires when I open Claude Code. My hook here is a bash script that does one cheap thing: look at the current directory, and if it is one of my projects, inject a recall instruction scoped to that project.

BASENAME=$(basename "$CWD")
# ...match BASENAME against my known project slugs, set $SLUG...

MSG="[session-context] cwd is project '$SLUG'. Before answering the
first prompt, call mem0_search with query=\"$SLUG\" for past
decisions, preferences, and in-flight work."

jq -nc --arg msg "$MSG" \
  '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $msg}}'

That is the whole mechanism. The JSON goes back to Claude Code, the additionalContext string lands in the session as if it had always been there, and because the instruction is explicit and imperative, Claude runs the search before it answers my first message. By the time I have typed anything, the recall results are already in context.

The scoping is deterministic on purpose. The script matches the folder name against a hard-coded list of my project slugs — no LLM call inside the hook, no latency, no cost. In a project folder it recalls that project. In a random folder it falls back to a generic recall keyed on the folder name. I gave the hook a five-second timeout, and it never comes close to it.

The payoff shows up as a kind of friction quietly disappearing. I no longer re-explain decisions I already made — which database a project uses, why an endpoint is shaped the way it is, the API quirk that cost me an evening last month. The recall puts those back in front of Claude before its first answer, so it builds on them instead of slowly reinventing them.

Side note: if you'd rather have this whole setup broken into a few short, copy-paste steps in your inbox, I turned it into The Claude Code Memory Starter — a free email series. Back to the hooks.

Hook 2: catch the project I name mid-conversation

SessionStart covers where I am sitting. But half my prompts mention a different project than the folder I am in — "wait, how did I handle inbound email in subhook?"

So the second hook runs on UserPromptSubmit, before each message reaches Claude. It reads the prompt text, lowercases it, and scans for any known project slug as a whole word.

for s in $HUB_SLUGS; do
  if echo "$PROMPT_LC" | grep -qE "(^|[^a-z0-9])$s([^a-z0-9]|\$)"; then
    MATCHED="$MATCHED $s"
  fi
done

The whole-word boundary in that regex is load-bearing. Without it, a short slug matches inside longer unrelated words and ordinary prompts trigger recalls all day. With it, only a real mention counts.

If a slug matches, the hook injects the same kind of recall instruction — pull context for that project before answering. If nothing matches, the hook exits silently and adds nothing at all. Most prompts hit the silent path.

This is the part I notice most in daily use. I name a project and Claude already has its history before it responds, even when that repo is three directories away from where I am actually working.

Hook 3: capture without making me wait

The first two hooks are reads. Reads are easy — they are fast, and a few hundred milliseconds at session start is invisible.

The third hook is the write, and writes are where this got ugly.

SessionEnd fires when I close a session. The work it wants to do is not fast: read the whole transcript, send it to an LLM to extract what actually mattered, dedupe each item against the vector store, write the survivors. That is several seconds of work. If the hook does it inline, my terminal hangs for several seconds every single time I close it. Not acceptable.

So the SessionEnd hook does almost nothing itself. It spawns a detached background process and returns immediately:

(
  "$PYTHON_BIN" "$SCRIPT_PATH" \
    "$TRANSCRIPT_PATH" "$SESSION_ID" "$HOOK_EVENT" "$CWD" \
    </dev/null > "$LOG_FILE" 2>&1 &
  disown
) >/dev/null 2>&1

The extraction runs after my terminal is already gone. I find out whether it worked by reading a log file later, never by waiting on it.

Three things bit me here. They are the reason this section is the longest one.

Parallel runs. At the end of an evening I close three or four sessions in a burst. Without a lock, that is three or four extractors hammering the vector store at once.

(My last memory article had a footnote about a "helpful" hook that once spawned seven parallel Claude instances. I have held a grudge against unguarded hooks ever since.) The fix is two locks: a global one created with mkdir — atomic because the filesystem either creates the directory or fails, with no gap between the check and the create, unlike testing for a lockfile and then writing it — plus a per-session lock with a 120-second cooldown so one session cannot double-fire.

Inherited environment. The extractor is a plain Python script, but spawned from inside Claude Code it inherits Claude Code's entire environment — ANTHROPIC_BASE_URL, an OAuth token, a dozen CLAUDE_CODE_* variables. That environment makes the subprocess behave as if it is still running inside Claude. The fix is one unset block before the Python runs, clearing every inherited Claude variable. This one cost me a confused hour.

Key source. The extractor needs API keys. I could hard-code them into the script. Instead it reads them straight out of ~/.claude.json — the same file the live mem0 MCP server already reads its own keys from. One source of truth. When I rotate a key I rotate it in one place, and both the hook and the server pick it up.

What the extractor actually keeps

The background script sends the transcript to Gemini 2.5 Flash Lite with a tight extraction prompt: keep architectural decisions and their reasoning, keep preferences, keep root causes of bugs, keep project-specific facts. Skip transient state, skip routine procedure. Flash Lite sits on the free tier, so a chatty day of building costs nothing — and transcript extraction is genuinely not a job that needs a frontier model. A small OpenAI model is wired in as a fallback for the days Gemini fails.

Each surviving item comes back as structured JSON — the fact, a project scope, and a category like decision or learning. In practice a memory looks like one short sentence: "subhook uses Postmark inbound for subdomain mail because Cloudflare Email Routing only forwards the apex on the free plan," tagged {project: subhook, category: decision}. Before writing anything, the script searches the vector store for that exact text and skips it if something already sits above 0.88 cosine similarity. That dedupe is the line between a memory that compounds and a memory that fills up with a hundred near-identical entries.

What survives gets written to Pinecone with infer=False — store the text verbatim. The extraction already happened, in the Gemini step. I do not want the vector store re-paraphrasing facts I already shaped into the form I wanted them in.

If you copy one idea from this

Not the project-slug list. Not Pinecone, not Gemini. Those are my plumbing, and yours will be different.

Copy this: a hook that injects an instruction beats a hook that runs a command. A hook that runs git status and returns the output hands Claude a fact. A hook that injects "before answering, check X and recall Y" hands Claude a task — carried out with the full toolset and judgment Claude already has. The first is static. The second is behavior.

Once I started seeing shell-command hooks as a place to write prompts instead of a place to run scripts, the memory wiring stopped looking like a hack and started looking like the obvious shape. Recall on the way in. Capture on the way out. And an evening-tired version of me who never has to think about either one.

If you want the layer this builds on, the same lifecycle thinking shows up in how I put a code reviewer in front of every git push with a Claude Code subagent — another small piece of glue that runs without me thinking about it.

External Sources

Claude Code hooks reference — official lifecycle event and JSON schema docs
mem0 on GitHub — the memory layer this builds on
Pinecone documentation — managed vector database getting-started guide
Gemini API documentation — Google's developer docs for Gemini models
Gemini cookbook — examples and guides for the Gemini API

If you want the starter version of this to land in your inbox, The Claude Code Memory Starter walks you through it over a few short emails — free. The memory layer this one builds on is the earlier article on adding persistent semantic memory to Claude Code.

Target publication: Generative AI (~50K followers) [PRIMARY for the AI/Claude Code angle] · Level Up Coding (~60K followers) [SECONDARY]

Tags: Claude Code · AI · Developer Tools · Programming · Productivity

I build small tools and kits for solo creators. You can find them here: https://danielrusnok.gumroad.com

How to Make Chrome Extension Iframes Transparent on Dark-Mode Sites (CSS color-scheme Fix)

Digital Craft Workshop — Wed, 22 Jul 2026 15:15:31 +0000

A customer of ours emailed: "Your Chrome extension shows me a blank white page on our dashboard." I checked. His site uses color-scheme: dark\. Ours doesn't set it. Our iframe was painting a solid white rectangle over his entire viewport — and I had no idea, because every site I test on is light-themed.

Same iframe, same transparent body — only the host's color-scheme differs.

The white rectangle nobody sees

Drop an iframe into a customer's page. Set background: transparent\ on its <body>\, its <html>\, even #root\. Check DevTools — every layer reports background-color: rgba(0, 0, 0, 0)\. The iframe should be see-through.

On most sites, it is.

On any site that sets color-scheme: dark\ on its <html>\ element, the iframe paints a solid white rectangle over everything underneath. Your transparent body is sitting on top of a white backdrop you didn't ask for and can't see in the computed styles panel.

---

Why Chrome does this

The CSS property responsible is color-scheme\. It tells the browser what theme a document expects — light\, dark\, or normal\. The browser uses this to pick the right shade for form controls, scrollbars, and a system color called Canvas.

Canvas\ is the default backdrop the browser paints behind any element with a transparent background. In light mode it's white. In dark mode it's near-black.

The spec detail that matters: color-scheme\ does not propagate across iframe document boundaries. Every iframe document defaults to color-scheme: normal\ (which resolves to light) regardless of what the parent page declares.

The CSS Color Adjustment spec calls this a color-scheme mismatch. The spec requires the user agent to substitute an opaque Canvas color matching the iframe document's resolved color scheme — light, in this case, which means white. Your transparent body is then composited on top of that opaque white backdrop, not on top of the dark parent page.

In practice, this means the browser inserts an opaque layer between your iframe document and the parent page before any of your own CSS gets a chance to run. There is no DOM node you can inspect for it. The computed background-color on every element in your iframe still reports rgba(0, 0, 0, 0)\. The Elements panel will not show you a white rectangle, because the white rectangle is not in the DOM — it is the user agent's substitute Canvas, painted by the compositor.

This is documented in Chromium issue 40157837 and the CSSWG drafts discussion. It is intentional, it is spec-compliant, and it has been breaking iframe overlays for years — one missing HTML tag has been killing social media traffic the same way for just as long. The web is full of these tiny spec gotchas.

Four layers — only the user agent's substitute Canvas is visible to the eye, and only when the parent is dark.

---

The two-line CSS fix

Tell the iframe element explicitly what color scheme to use, and make sure its body is transparent:

iframe.my-overlay {
    color-scheme: light;
    background: transparent;
}

That's it. color-scheme: light\ on the iframe element in the parent document tells Chrome "the iframe wants light scheme, same as you would assume by default." No mismatch, no Canvas backdrop. background: transparent\ makes sure the element itself doesn't paint either.

If you control the iframe document too, also add this in its CSS so it's transparent even before the inline style is parsed:

html, body, #root {
    background: transparent !important;
    color-scheme: light !important;
}

!important\ matters because some CSS resets and base layers (including configurations that add a body background) override your plain rule.

Small fixes like this are the kind of thing I collect in The Claude Code Memory Starter — a free email series you can join in one click.

---

The reusable React component

If you have one iframe, do the CSS-only fix. If you have ten — which is what I had across our flow editor — you need a wrapper so nobody can add an iframe and forget the rule.

import { forwardRef, IframeHTMLAttributes } from 'react';

export const SafeIframe = forwardRef<HTMLIFrameElement, IframeHTMLAttributes<HTMLIFrameElement>>(
    function SafeIframe({ style, ...rest }, ref) {
        return (
            <iframe
                ref={ref}
                {...rest}
                style={{
                    background: 'transparent',
                    colorScheme: 'light',
                    ...style,
                }}
            />
        );
    }
);

Two things to notice. The wrapper uses forwardRef\ so callers can still attach refs (you'll need that for getBoundingClientRect()\ and postMessage\ patterns common in overlay UIs). And the default style spread comes before ...style\, so any caller-provided style overrides the defaults — including setting colorScheme: 'dark'\ for the rare iframe that actually wants the dark backdrop.

Then a sed\ pass replaces native iframes with the wrapper:

for f in src/components/**/*.tsx; do
  sed -i '' 's|<iframe|<SafeIframe|g; s|</iframe>|</SafeIframe>|g' "$f"
done

Add the import in each touched file. Done. Every future iframe added to the project is transparent-by-default unless somebody actively opts out.

One sed pass plus four imports — sixteen iframes become one wrapper.

---

Make the iframe document transparent too

The wrapper fixes the iframe element. The CSS above fixes the iframe document. You want both, because each protects against a different failure mode.

The element-level fix breaks if a caller passes an explicit style={{ colorScheme: 'dark' }}\ override. The document-level fix breaks if the iframe is created somewhere outside your wrapper (a third-party library, a manual document.createElement('iframe')\).

Add the document-level CSS to your iframe app's root stylesheet:

html, body, #root {
    background: transparent !important;
    color-scheme: light !important;
}

If your iframe app is React-based and uses Tailwind, put this after @tailwind base\ so it overrides preflight defaults.

---

Why this bug is invisible on light-themed sites

If you don't test on a dark-themed host, you will never see this bug. The white Canvas blends into a light parent page — you see what looks like a transparent overlay, but it's actually a white rectangle on top of a white page.

The bug is identical on light and dark hosts. Only the visibility changes. My dev environment is light. The marketing site is light. Most customer playground apps are light. The bug existed for months, and nobody on the team saw it because the entire test surface looked clean. The customer who reported it ran a security product with a dark dashboard — as soon as the white rectangle had something to contrast against, the "blank page" complaints started. (Same shape as our Next.js app that crashed every 24 hours — silent production bug only outsiders ever noticed.)

---

How to test for it before customers do

Add this to your release checklist:

Open any of your iframe overlays on a host page that sets color-scheme: dark\ on its <html>\.
If you don't have such a customer, force it for testing: in DevTools, find the <html>\ of any site you're testing on, add style="color-scheme: dark"\ inline. The bug will appear immediately if it's there.
Or open Chrome DevTools → Rendering tab → set "Emulate CSS media feature prefers-color-scheme" to dark, then visit any site whose CSS respects the system preference.

If your overlay paints a visible rectangle, you have the bug. The fix is the two-line CSS rule above.

In DevTools the rectangle is solid white, the exact Canvas\ light-mode color — not off-white, not semi-transparent. It appears the instant the iframe element gets a layout box, before any of your iframe document's own CSS runs, so there is no flash-of-transparent-content moment to catch. To verify the fix is working, apply it, hard-reload the host page, and confirm the iframe area composites cleanly against the dark parent background with no white edge anywhere along its bounding box.

Force-trigger the bug from DevTools — Rendering panel emulates dark scheme on any site.

---

What we shipped

In our codebase, the fix touched four files, replaced sixteen native <iframe>\ elements with one SafeIframe\ wrapper component, added one CSS rule to the global stylesheet, and deleted around twenty inline colorScheme: 'light'\ hot-patches that I had been sprinkling around while hunting the bug.

The wrapper component is fifteen lines. The CSS rule is three lines. The entire fix is shorter than this paragraph.

The bug had no console error, no DevTools warning, no broken selector. I only found it because a customer's screen didn't match mine.

If you inject UI into customer pages, set up a dark-themed test host. I found mine had been broken on dark customers for months.

---

If this saved you a dark-mode debugging session, The Claude Code Memory Starter is a free email series where I share more fixes like it — one short email at a time.

How I Put a Code Reviewer in Front of Every git push to Main with a Claude Code Subagent

Digital Craft Workshop — Mon, 20 Jul 2026 15:09:48 +0000

Three Wednesdays ago I shipped a regression to production. The diff looked fine. CI was green. I ran the dev server, clicked through the happy path, pushed, and went to bed.

The next morning a real user emailed me to say my landing-page signup button did nothing.

The bug was obvious in hindsight. The AI had quietly removed an await from an analytics call, the call threw inside a try block, and the catch swallowed it along with the rest of the handler. Three minutes to revert. Took the rest of the morning to feel okay about it again.

I'm a solo builder. No senior engineer reads my PRs. Nothing sits between my keyboard and main. I let Claude Code write most of my code now — which means most of what hits main was written by something that doesn't know it shouldn't swallow exceptions.

Sidebar: this story is one piece of how I think about AI as a solo founder's tool — I have a 5-email series on the broader pattern if you want the bigger picture.

So I built the second pair of eyes. One Claude Code subagent, one 30-line pre-push hook, shared across every repo I own. It runs on every push to main, takes about 20 seconds, and has caught real bugs four times in three weeks.

Here's how it works.

The architecture

Three pieces, nothing exotic.

A subagent definition — a markdown file that tells Claude how to act when invoked as a reviewer. Lives in .claude/agents/code-reviewer.md.

A pre-push git hook — bash script that gathers the diff, fires up a headless Claude Code instance pointed at the subagent, and prints the verdict.

A .shared/ folder + symlinks — both files live once at the top of my foundary-tools/ monorepo and symlink into each child repo's .claude/ and .git/hooks/. One install script wires everything.

Three pieces because each one owns a different lifetime. The subagent definition is the slowest-changing — I edit it maybe once a week as I learn what false positives look like. The hook is the contract with git — set it up once, leave it alone. The symlinks are infrastructure — wired during install-hooks.sh and forgotten. Bundling them into one script would mean re-installing across nine repos every time I tweak a prompt rule. Keeping them separate means the prompt edits live in version control and propagate for free.

The reviewer only fires on pushes to main. Feature branches push freely. The cost is one Opus call per release-shaped push — pennies — and the upside is a 20-second sanity check before a regression goes live.

The whole thing fits in three files — and the most important one isn't the hook.

The subagent definition

The subagent is a plain markdown file with frontmatter. Claude Code reads the description, knows when to dispatch to it, and uses the body as the system prompt.

---
name: code-reviewer
description: "Reviews staged commits before push. Flags"
regressions, swallowed errors, removed awaits, broken
invariants, leaked secrets, and missing migrations.
model: opus

tools: Read, Grep, Glob, Bash

You are reviewing a diff that is about to land on main\.

Output exactly one of:

"APPROVE: "
"BLOCK: \n"

Block only for things that will break production or leak
secrets. Style nits, naming preferences, and "could be cleaner"
notes do not block. The author is a solo builder shipping
fast; assume they accepted any trade-off that isn't a bug.

Always check:

Removed await\ on async calls
New catch\ blocks that swallow without logging
Hard-coded URLs that look like prod endpoints
.env\ keys printed to logs
Schema changes without a matching migration file
console.log\ of request bodies (usually leaks PII)

The output contract is one line. No essay, no "great work, here are some thoughts." Either APPROVE: ... or BLOCK: .... The hook script greps for the prefix and acts on it.

The subagent commits to a verdict instead of hedging. Without this contract, every review came back as a four-paragraph essay that ended with "but ultimately, this is your call."

The block criteria are narrow. I don't want the reviewer to lecture me about my variable names or suggest I add comments. I want it to catch things that will page me in the morning.

The solo builder shipping fast line in the prompt is load-bearing. Without it, the reviewer was blocking pushes for things like "consider extracting this into a helper" — which is exactly the kind of advice I added the reviewer to ignore.

If you've ever fought with Claude over getting it to follow a strict output format, the same lesson applies here: give the model a verdict to commit to, not an essay to write.

The pre-push hook

The hook is a bash script at .git/hooks/pre-push. Git invokes it before talking to the remote and aborts the push if the script exits non-zero.

!/usr/bin/env bash

set -euo pipefail

REMOTE_BRANCH="$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "")"
[[ "$REMOTE_BRANCH" == */main ]] || exit 0

DIFF="$(git log --stat origin/main..HEAD; git diff origin/main..HEAD)"
[[ -n "$DIFF" ]] || exit 0

echo "Running code-reviewer subagent..."
VERDICT="$(echo "$DIFF" | claude \
--dangerously-skip-permissions \
--print \
--agent code-reviewer 2>&1)"

echo "---"
echo "$VERDICT"
echo "---"

if [[ "$VERDICT" == BLOCK:* ]]; then
printf "Override? [y/N] "
read -r REPLY </dev/tty
[[ "$REPLY" =~ ^[Yy]$ ]] || exit 1
fi

It only runs for pushes whose upstream tracks main. A push to a feature branch returns early. That's the difference between 20 seconds added to every push and 20 seconds added to releases.

Side note: if you're wiring Claude Code deeper into your own workflow, I put the setup I lean on into a short, free email series — The Claude Code Memory Starter — one small lesson at a time.

The script ignores git's ref-list stdin and recomputes the diff from origin/main..HEAD. The combination of git log --stat and git diff gives the reviewer commit messages plus the actual hunks — messages help it figure out intent when judging whether a deletion was deliberate.

--dangerously-skip-permissions is fine here because the subagent has read-only tools (Read, Grep, Glob, Bash). It can't edit anything or push.

The read -r REPLY </dev/tty is the one tricky line. Pre-push hooks get git's ref list on stdin, so you have to redirect from the controlling TTY to read the user. Without this, the prompt prints and immediately accepts an empty answer.

**One hook, one repo. The next part is how it became one hook across nine.**

Sharing one config across every repo

I have nine repositories in ~/foundary-tools/. I'm not going to copy a hook and a subagent definition into each one and then forget which is the canonical version after the third edit.

The fix is a .shared/ folder at the top of the monorepo.

foundary-tools/
├── .shared/
│ ├── agents/code-reviewer.md
│ ├── hooks/pre-push
│ └── install-hooks.sh
├── drippery/
├── article-forge/
├── grownote/
└── ...

install-hooks.sh walks every direct child directory and creates two symlinks per repo.

!/usr/bin/env bash

set -euo pipefail
SHARED="$(cd "$(dirname "$0")" && pwd)"

for repo in "$SHARED/.."/*/; do
[[ -d "$repo/.git" ]] || continue
mkdir -p "$repo/.claude/agents"
ln -sf "$SHARED/agents/code-reviewer.md" \
"$repo/.claude/agents/code-reviewer.md"
ln -sf "$SHARED/hooks/pre-push" \
"$repo/.git/hooks/pre-push"
chmod +x "$repo/.git/hooks/pre-push"
echo "wired: $(basename "$repo")"
done

**Run it once. Edit** `code-reviewer.md` **later and every repo picks up the change on the next push.** No copy, no drift.

If you have one repo, the symlink trick is overkill — just put the files directly in .claude/agents/ and .git/hooks/. The subagent and the hook are the part doing the work.

The harder problem isn't sharing the rule. It's making myself willing to obey it.

Soft warning, not hard block (and `--no-verify` still works)

The first version of the hook used exit 1 on BLOCK: and forced me to amend or escape-hatch. I rewrote it within a day.

I push during moments where stopping is expensive — the kid wakes up, the evening ends, the meeting starts in eight minutes. A hard block on a false positive doesn't help anyone; it just teaches me to disable the hook.

The soft warning works because it changes the default. Default is don't push. Pressing Enter aborts; pressing y proceeds.

I read the verdict, decide in two seconds, and either fix or override. Four times in three weeks, the verdict was right and I went back to fix. Roughly ten times the verdict was wrong and I pressed y and shipped.

If I had set hard block, I'd have disabled the hook by week two. The override is what keeps the hook installed.

This is the same lesson I learned with my pre-deploy script that refuses to add a staging environment: I keep using the tools that make the safe path easy without locking the risky path away.

git push --no-verify bypasses every git hook, including this one. I don't try to "fix" that. If I need to ship a hotfix at 11pm and the reviewer is hallucinating about a deleted file, I want one well-known flag to skip the check, not a fight with my own tooling.

The reviewer is a default-on layer. It's not a security gate. Security gates belong in CI, where I can't --no-verify past them. The reviewer's job is to catch the bugs I'd catch myself if I weren't tired.

What I deliberately do not ask the reviewer

I tried adding more checks at first. I removed most of them.

The first version flagged every function over 30 lines for "consider extracting a helper." By the third push it had blocked a 45-line tenant migration that I had no intention of splitting — the SQL was inherently sequential. I deleted that rule the same evening. Same story with "magic numbers" — the reviewer kept flagging timezone offsets and HTTP status codes. Out.

The reviewer does not:

Run tests (CI does)
Run the type checker (CI does)
Check formatting (prettier --check does)
Look for style violations (taste, not bugs)
Suggest refactors (different mode of work)

It checks the things a human reviewer would catch in a hurried PR scan — swallowed exceptions, dropped awaits, schema drift, leaked secrets — and stays out of everything else. That narrow scope is why it runs in 20 seconds and why I trust the verdict enough to act on it.

If it flags everything I stop reading it.

What this gets you

Three weeks in, the receipts:

Four real catches (two dropped awaits, one swallowed error, one debug console.log of a JWT)
Roughly ten false positives, all dismissed by pressing y
Zero "I disabled the hook because it was annoying" moments
A single canonical config across nine repos
About $0.40 in Opus calls

The JWT one was the closest to a real incident. I'd added a console.log(req.headers) while debugging a webhook signature mismatch, forgot to remove it, and went to push. The reviewer flagged the leaked token in five seconds. That alone earned the next year of the reviewer's existence.

The .shared/ symlink trick stops mattering when you only have one repo, but the subagent and the hook still work — just live in the repo directly.

If you're already using Claude Code, the whole setup is one subagent file, one hook script, and an install-hooks.sh if you have more than one repo. About 30 minutes from cold to first wired push.

This is the third Claude Code workflow I've shipped this month that ends up being a short script. The other two — a skill that turns an hour of project setup into 90 seconds and a memory layer that survives between sessions — follow the same pattern. Most of my wins lately are thirty lines of glue around something Claude Code already ships.

If this was useful, you might also like The Claude Code Memory Starter — a short, free email series on getting Claude Code to remember what matters between sessions.

My Own Content Pipeline Didn’t Have My Own Content. Here’s the Backfill That Fixed It.

Digital Craft Workshop — Sat, 18 Jul 2026 15:07:51 +0000

My Own Content Pipeline Didn’t Have My Own Content. Here’s the Backfill That Fixed It.

Three platforms, three different integration battles — and a parser bug that silently ate three of my articles.

Three platforms, three different ways to hand you back your own history. | Generated with ChatGPT

Not a member? Use this link.

60 articles lived in my analytics dashboard. 0 of them had actual content.

I built Article Forge to manage everything I publish — drafts, section-scoped AI edits, cross-posting from Medium to dev.to, analytics from all three platforms in one place.

The whole point is that my content lives in my own tool. But for months, only the posts I’d drafted inside Article Forge had their body text stored. Everything written before the tool existed was just a row in article_analytics with a URL and zero context.

One evening, I sat down to backfill. I expected one script. I wrote three.

Architecture diagram showing Article Forge | Generated with Claude

Dev.to — the platform that just works

Dev.to has a clean REST API. /api/articles/me/published paginates through everything you've ever shipped. The catch: the list endpoint returns metadata only. To get body_markdown, you fetch each article individually via /api/articles/{id}.

The script is twenty lines of “list, then loop and fetch detail.” I wrote a dedupe by publishedUrl so re-runs are safe, and linked to each new articles row back to the corresponding article_analytics row by externalId.

Twenty articles inserted, twenty analytics linked, zero failures. Five minutes of actual work.

This is the version of “content backfill” that fits in a tweet. Then there’s Substack and Medium.

Substack — the platform that wants your cookie

Substack doesn’t have a public published-list API for owners. Or rather, it does, but it’s behind cookie auth. The dashboard hits an endpoint called post_management/published that returns a paginated list of your posts, including drafts. It accepts your substack.sid cookie as the auth token.

I already had this plumbing — the analytics sync uses the same endpoint to read view/open counts. The backfill enumeration was free. What was missing was the post body. For that, you call https://{your-subdomain}.substack.com/api/v1/posts/{slug}, again with the cookie, and you get back full body_html, cover image, subtitle.

Ten new articles inserted, nine linked to existing analytics rows, seven skipped because they already existed in the DB.

The auth model is honest. You don’t pretend a cookie is an API key. It is what it is — a session, scoped to your account, that you paste into your tool’s settings page. Once you accept that, the API surface is decent.

Side-by-side comparison of three platform integration approaches | Generated with Claude

If you like reading about the small tools I build for my own workflow, I turned one of them into The Claude Code Memory Starter — a free email series you can follow along with.

Medium — the platform that hands you a zip file

Medium has no API for reading your own historical articles. You can pull the latest ten from the public RSS feed, and that’s it. If you want everything, you go to Settings → Security and apps → Download your information, wait for an email, click a link, and download a zip of HTML files.

I downloaded the zip. Eighty-eight HTML files. Three drafts (filenames start with draft_), about thirty short "responses" (Medium's name for comments — stored as posts in the export), and the rest were real articles.

I added node-html-parser as a dependency and wrote a parser. The Medium export structure is consistent — every file is an <article class="h-entry"> with <h1 class="p-name"> for the title, <section data-field="subtitle"> for the subtitle, <section data-field="body"> for the body, and <time class="dt-published"> for the date.

Dry-run reported: 53 articles to insert, 29 short responses skipped, 3 unparseable.

Three? On a stable, well-formed export format? With a parser I’d just verified worked on the other 53?

The silent bug

I opened one of the three files. The HTML was fine. Tag balance was fine. <article class="h-entry"> was right where I expected it. I dropped into a one-line node REPL:

const root = parse(html);  
console.log(root.querySelectorAll('article').length);  // 0  
console.log(root.querySelectorAll('h1.p-name').length); // 1

Zero articles. One title.

The title element is inside the article element. If the parser found one, it should find the other. Unless the parser thinks the article closed before the title.

I scanned for what might trip a permissive HTML parser. The three “broken” files all had something in common: code blocks. Long **<pre>** blocks containing JavaScript with template literals, comparison operators, JSX-ish snippets — all the things that produce raw < characters inside what should be opaque text.

node-html-parser doesn't fully escape < inside <pre>. When it scans, it sees what looks like a tag, applies its auto-closing rules, and silently decides that the wrapping **<article>** ended way earlier than it actually did. Outer selectors miss. Inner selectors that don't depend on the wrapping element still work.

The fix is one line. Instead of:

const article = root.querySelector("article.h-entry");  
const title = article?.querySelector("h1.p-name");

Do:

const title = root.querySelector("h1.p-name");

Query from the document root. Don’t assume the wrapping element is reliably reachable just because the source HTML is valid.

Re-ran the script. Three “unparseable” files dropped to zero. One was new content (got inserted), two were already in Article Forge as drafts and matched my title-fallback dedupe.

Simulated terminal output showing the dry-run results | Generated with Claude

The deduplication logic that saved me twice

I mentioned dedupe by publishedUrl earlier. That's the primary key — if a URL already exists in the articles table, skip it. Works for dev.to and Substack, where every published post has a stable URL.

Medium broke this assumption. I had eight articles already drafted in Article Forge before the backfill. They had no publishedUrl yet because they were still drafts. The ZIP export didn't know about my internal drafts, and my internal drafts didn't have Medium URLs.

The fallback: normalized title matching. Strip punctuation, lowercase, compare. It caught all eight. Not elegant, but it prevented eight duplicate rows that would have confused every downstream query.

If you’re building any kind of content sync, plan for the case where the same content exists on both sides with no shared identifier. URL-only dedupe works until it doesn’t.

What the unified data actually unlocked

Eighty-something rows added across three platforms in a few hours. The row count isn’t the point. Every analytics row now has a corresponding article row with the actual content sitting next to the view count.

The “related articles” feature in my AI-powered optimizer can finally see my entire archive instead of just the things I drafted in-tool. When I’m writing about background jobs, it knows I already published a deep dive on Inngest and can suggest an internal link.

The Medium → dev.to cross-post sync now has the full Medium body to compare against, not a 200-character RSS snippet. Drift detection between platforms actually works.

And the simplest win: I can search my own articles by content, not just by title. “Which article mentioned Promise.allSettled?" is now a database query, not a manual hunt across three browser tabs.

Three things I’ll keep doing

1. APIs aren’t the only data source. A zip of HTML is a perfectly good integration if it’s the only thing the platform offers. Write a parser, handle edge cases, and move on.

2. Dedupe by URL with a title fallback. URL-only dedupe missed eight Medium drafts that hadn’t been published yet. A normalized-title fallback caught them all. Two layers of matching cost almost nothing and prevent real problems.

3. When a permissive parser disagrees with the source, look at what’s inside the elements. Code blocks with raw < will lie to your parser long before the parser admits it's confused.

The next thing on the list: backfilling Medium’s external_url mismatch so analytics rows actually link correctly. But that's a different evening.

External Sources

node-html-parser — the fast HTML parser that tripped on raw < in pre blocks (GitHub)
Forem API v1 — the dev.to REST API used for the cleanest backfill
Medium data export — official guide for downloading your information

If you want more of this in your inbox, The Claude Code Memory Starter is a short, free email series where I walk through setups like this one.

Our Next.js App Crashed Every 24 Hours. Here Are the Six Memory Fixes.

Digital Craft Workshop — Thu, 16 Jul 2026 15:08:29 +0000

I opened the Render dashboard on Monday morning and saw the same thing I had seen every day for a week. Memory at 100%, service restarting. Our Next.js app was eating all 512MB within ~24 hours, then OOM-killing itself.

I spent a day digging through the codebase with process.memoryUsage() logs and Render's built-in metrics. I found six separate problems. One of them cut memory usage by more than half in a single deploy.

Here is every fix, in order of impact.

The Stack

Next.js 16 (App Router) with Drizzle ORM, PostgreSQL, Clerk auth, Stripe payments, Resend for transactional email, and Inngest for background jobs. I covered the full background job setup in a previous post — five functions, one route, $0/month.

Hosting: Render.com Starter plan — 512MB RAM, $7/month.

The symptom: no sudden spikes. Just a steady upward line on the Render memory graph that ended in an OOM-kill roughly every 24 hours.

The Fix That Cut Memory in Half

The Resend email SDK was being created with new Resend(apiKey) inside 10 different files. API routes, Inngest functions, utility helpers. Every request spun up a new client with its own HTTP connections, event listeners, and internal buffers. None of them got cleaned up between requests.

This is what it looked like:

// ❌ In 10 different files
export async function POST(req: Request) {
  const resend = new Resend(process.env.RESEND_API_KEY);
  await resend.emails.send({ ... });
}

And the fix — a lazy singleton in one file:

// ✅ lib/resend.ts
let instance: Resend | null = null;

export function getResend(): Resend {
  if (!instance) {
    instance = new Resend(process.env.RESEND_API_KEY!);
  }
  return instance;
}

Every handler now calls getResend(). One instance for the entire process lifetime. I already had this pattern for Stripe and Anthropic — Resend slipped through because it was added later, in a hurry, across multiple files.

Memory dropped from ~93% to ~35% immediately after deploy. This single change was responsible for more than half of the total improvement.

V8 Knows Your Container Limit. It Still Overallocates.

Node.js 20+ reads cgroup limits and auto-sizes the V8 heap based on your container's available memory. So in theory, it should know about the 512MB limit. In practice, the auto-detected heap still leaves too little room for everything else — non-heap memory, native buffers, connection pools, and the OS itself.

On my 512MB container, V8's auto-detected heap was larger than what the process could safely use. Memory would climb slowly — not because of a leak, but because V8 was not running GC aggressively enough for the remaining headroom.

The fix is one flag:

node --max-old-space-size=384 server.js

Setting it to ~75% of the container limit gives V8 a tighter budget. It starts garbage collecting earlier, well before the container runs out.

One gotcha I hit: I initially set NODE_OPTIONS=--max-old-space-size=384 as a Render environment variable. That applies to the build step too. The TypeScript compiler also runs under Node — and it crashed at 384MB during the build.

The fix: set the flag only in the start command, not as a global env var.

// Render start command (not an env var)
node --max-old-space-size=384 .next/standalone/server.js

After the singleton fix brought memory down to ~35%, this flag is what prevented it from slowly climbing back up.

If you would rather get my solo-dev build-and-debug notes broken into a few short, copy-paste steps in your inbox, I put the essentials into The Claude Code Memory Starter — a free email series.

Four More Leaks I Found

Clerk Admin SDK — Same Bug, Different Package

Same pattern as Resend, smaller scale. createClerkClient() was called inside request handlers in 3 files instead of being a singleton. Same lazy-init fix: one **getClerkAdmin()** function, one file, one instance.

Unbounded In-Memory Rate Limiter

My /api/track analytics endpoint used a global Map for rate limiting. Cleanup only kicked in when the map exceeded 1,000 entries. On a 512MB container, 1,000 entries of IP strings plus timestamps and counters adds up.

Fix: hard cap at 500 entries with LRU-style eviction, plus a setInterval cleanup every 2 minutes.

const cleanup = setInterval(() => {
  const now = Date.now();
  for (const [key, entry] of rateLimitMap) {
    if (now - entry.timestamp > 120_000) {
      rateLimitMap.delete(key);
    }
  }
}, 120_000);
cleanup.unref();

The .unref() call matters. Without it, the interval keeps the Node process alive and it will not exit cleanly during deploys or restarts.

Cron Jobs Loading Everything Into Memory

Two Inngest cron functions had memory problems:

Analytics cleanup used Drizzle's .returning({ id }) on a bulk DELETE. This loaded every deleted row ID into an array before returning. On a table with thousands of expired rows, that array gets big. Fixed with raw SQL that returns only **rowCount**.

Orphan image cleanup listed the entire Cloudflare R2 bucket three separate times — once per context (sequences, emails, subscribers). Fixed to list the bucket once and filter in memory. Three API calls became one.

Database Pool With a Silent Zero-Timeout Default

The PostgreSQL connection pool was created with new Pool({ connectionString }) and nothing else. Most defaults are fine — max: 10, idleTimeoutMillis: 10_000. But one default is dangerous: **connectionTimeoutMillis** defaults to 0, which means "wait forever."

If a connection attempt hangs — slow DNS, unresponsive database, network hiccup — the request sits there holding memory and a pool slot indefinitely. On a 512MB container, one stuck connection is all it takes to start a cascade.

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 10,
  idleTimeoutMillis: 10_000,
  connectionTimeoutMillis: 5_000,
});

Adding connectionTimeoutMillis: 5_000 means a stuck attempt fails fast instead of waiting forever. I would not have found this without reading the node-postgres docs during the debugging session.

Results

Metric	Before	After
Baseline memory	~93% (475MB)	~35% (180MB)
Time to OOM	~24 hours	Stable (no crash)
Memory after 24h	OOM crash	~45% plateau

The Resend singleton was the biggest single win — more than half of the total improvement in one deploy. The --max-old-space-size flag prevented the slow climb back up by giving V8 a tighter GC budget.

The Checklist

If you are running Next.js on a memory-constrained container, check for these:

SDK clients (new Client()) created inside request handlers instead of module-level singletons
Missing **--max-old-space-size** — even on Node 20+ where cgroup detection works, an explicit cap gives V8 a tighter GC budget
**--max-old-space-size** set as env var instead of start command only (breaks builds)
Unbounded **Map** / **Set** / **Array** at module level without eviction or size cap
**.returning()** on bulk DELETE/UPDATE loading all results into memory
Database pool with default connectionTimeoutMillis: 0 — set an explicit timeout

Most of these take 5–10 minutes to fix once you know what to look for.

What I Took Away From This

Most Node.js memory issues on small containers are not traditional memory leaks. They are per-request allocations that should be singletons, combined with V8 not running GC aggressively enough for the available headroom.

Fix those two patterns and you will likely be fine on 512MB. I have been running stable for weeks on Render's cheapest plan — no crashes, no restarts, memory plateaus at ~45%.

If you want more of how I build and ship as a solo developer landing in your inbox, The Claude Code Memory Starter walks you through the setup over a few short emails — free.

External Sources

Node.js CLI docs — --max-old-space-size — the official V8 heap limit flag documentation
Resend Node.js SDK — the email SDK referenced in this article
Drizzle ORM — TypeScript-first SQL ORM used in the stack
Inngest — background job platform for the cron functions
node-postgres Pool API — connection pool configuration and defaults

Daniel Rusnok is a software developer and solo maker building Drippery — a dead-simple drip email tool for creators. He writes about TypeScript, Next.js, and the realities of shipping software alone.

I automated away an hour of project setup with a Claude Code skill

Digital Craft Workshop — Tue, 14 Jul 2026 15:05:36 +0000

Not a member? Use this link.

Every new SaaS project I start used to eat an hour of clicking — GitHub repo, npx create-next-app, copy-paste the DB config from my last project, walk through the Render dashboard, paste env vars, wait for the first deploy to fail because I forgot node server.js.

I did this three times in a row for three sibling projects. Then I automated the whole thing into a 90-second command.

The setup tax

I keep a folder called foundary-tools where each subdirectory is a separate SaaS or internal tool. Three projects in, every new sibling shares 90% of the same scaffolding.

Same Next.js 16 + React 19 skeleton. Same Drizzle + postgres-js setup. Same Tailwind v4 config. Same server.js that binds IPv4 explicitly because Render's port scanner doesn't see IPv6-only processes. Same .gitignore. Same tsconfig.json. Even the background job architecture is shared.

The only thing that changes between projects is the domain logic — about 5% of the initial commit.

So the other 95% was me, manually, every single time:

gh repo create danielrusnok/<name> --private
Copy a Next.js skeleton from the last project
Rename "name" in package.json, update CLAUDE.md, update the metadata in layout.tsx
Wire Drizzle against the shared Postgres, pick a unique pgSchema name
Paste the specific server.js with the 0.0.0.0 bind trick
Open dashboard.render.com, click New → Web Service, connect repo, fill in build/start commands, paste DATABASE_URL
Commit, push, wait 3 minutes, watch the first deploy fail because I typed something wrong
Fix, push again, wait another 3 minutes

An hour, easily. And at least twice I deployed a project that was silently missing an env var because I was tired and skipped a step.

How Claude Code skills work

If you use Claude Code, a "skill" is a procedural playbook Claude loads from **~/.claude/skills/**. Each skill is a directory with a SKILL.md — frontmatter describing when to trigger (natural-language phrases), plus step-by-step instructions for Claude to follow.

Skills can include helper scripts. You delegate judgment to the LLM and deterministic work to scripts. I leaned into this split even harder when I added persistent memory to Claude Code — same principle, different tool.

The division I landed on:

Claude handles: asking the user for inputs, confirming destructive actions, interpreting errors from gh / npm / the Render API, deciding whether to retry or escalate.
Python handles: walking a template directory, substituting placeholders, reading env vars from sibling projects, POSTing to Render's REST API.

Don't make the LLM do regex on **package.json**. Don't make the script decide whether to retry a failed network call. Each does what it's good at.

Nine steps, three approval gates

I named the skill foundary-new-project. It triggers on phrases like "nový foundary projekt" or "new foundary project" — same natural-language entry point as every other skill I use.

The workflow is nine steps, three of which require my explicit approval:

Validate & read secrets from sibling .env files
Scaffold the template into ~/foundary-tools/<name>/
Run npm install
Smoke-build with npm run build — fail fast before anything external happens
git init + first commit
Approval gate: create GitHub repo, push
Fetch Render owner ID (cached after the first run)
Approval gate: create Render web-service via API
Update CLAUDE.md with the Render service ID and print a recap

The approval gates exist because my intent changes between runs. Sometimes I want to scaffold locally and push later. Sometimes the name I picked collides with an existing Render service. A hard confirmation before external state changes is cheap insurance.

The scaffold script

scaffold.py is the least interesting part, which is how it should be:

def copy_template(target, name, schema, description):
    for src_root, dirs, files in os.walk(TEMPLATE_DIR):
        src_root_p = Path(src_root)
        rel = src_root_p.relative_to(TEMPLATE_DIR)
        dst_root = target / rel
        dst_root.mkdir(parents=True, exist_ok=True)
        for fname in files:
            src = src_root_p / fname
            dst = dst_root / fname
            raw = src.read_bytes()
            try:
                text = raw.decode("utf-8")
            except UnicodeDecodeError:
                dst.write_bytes(raw)
                continue
            dst.write_text(substitute(text, name, schema, description))

Three placeholders: __NAME__, __SCHEMA__, __DESCRIPTION__. The schema is the project name with hyphens swapped for underscores (SQL identifier rules).

I don't have a keychain integration. I don't maintain a separate secrets file. I read **DATABASE_URL** from **~/foundary-tools/drippery/.env.production** and RENDER_API_TOKEN from ~/foundary-tools/framelock/.env.local.

Why? Because those projects are already configured. The files exist. Permissions are already set to 0600. My adjacent project is my secret store by construction.

The new project's .env.local gets written with chmod 600 and added to a .gitignore that blocks .env*. Normal hygiene.

The Render API call

Render has a clean v1 REST API where POST /v1/services creates a web-service with the config baked in.

create_body = {
    "type": "web_service",
    "name": args.name,
    "ownerId": args.owner_id,
    "repo": args.repo,
    "autoDeploy": "yes",
    "branch": "main",
    "serviceDetails": {
        "plan": "free",
        "region": "oregon",
        "env": "node",
        "envSpecificDetails": {
            "buildCommand": "npm ci && npm run build",
            "startCommand": "node server.js",
        },
    },
    "envVars": [
        {"key": "DATABASE_URL", "value": args.database_url},
    ],
}

The owner ID is cached after the first run in ~/.claude/skills/foundary-new-project/.render-owner-id, so subsequent scaffolds skip a round-trip.

The whole script is about 80 lines of urllib.request — no SDK, no extra dependency. If the POST returns 409 or 400, Python exits with the error text and Claude reads it, tells me, and asks what to do.

That loop — script fails loud, LLM interprets, human decides — is why I reach for skills instead of **set -e** bash scripts.

If you'd rather get this kind of solo-builder setup broken into a few short, copy-paste steps in your inbox, I turned the essentials into The Claude Code Memory Starter — a free email series.

Template, not generator

The template/ directory is a real Next.js skeleton I can open and edit. When the stack evolves — new Next.js version, Tailwind upgrade, a server.js tweak — I edit the template files directly and the next scaffold picks up the change.

No code generator to maintain. No AST rewrites. Just files with three placeholders.

The template has 15 files: app/{layout,page,globals}, lib/db/{index,schema}, lib/env.ts, server.js, drizzle.config.ts, next.config.ts, postcss.config.mjs, tsconfig.json, .gitignore, .env.example, AGENTS.md, CLAUDE.md, README.md, package.json. Every one is either identical across projects or differs only by name/description.

The landing page is deliberately dumb — a hero with the project name and a "Coming soon" line. No DB calls, no auth, nothing that could break the first deploy. The first deploy's only job is to prove the pipeline works. I push every change straight to production anyway — this just makes sure the wiring is correct before real code lands.

90 seconds, zero dashboard clicks

From "I want a new project called X" to "a private GitHub repo exists, a free Render service is deploying from main, and npm run dev works locally" — about 90 seconds of wall time. Most of that is npm install and the initial next build.

Three approvals. Zero clicks in the Render dashboard. Zero copy-paste from old projects. Zero chance I forgot to rename something in package.json.

Compared to an hour of manual work where I screwed up half the steps — worth it.

Three things worth stealing

Skills beat shell scripts for anything with branching logic. A bash script with set -e exits on any failure. An LLM-driven skill reads the error, decides whether to retry, rephrase, or ask the human. The difference shows up the first time gh auth status is expired or the Render API rate-limits you — the bash script dies, the skill adapts.

Approval gates before external state changes. Local filesystem mutations and git commit are cheap to undo. GitHub repo creation, Render API calls, git push — those leak state outside my machine. A hard [y/N] confirmation before each one is the right trade-off.

Read secrets from adjacent projects. I was about to overthink secret storage — keychain, 1Password CLI, encrypted env file. My sibling projects' .env.local files are already provisioned and protected. One less system to maintain.

What's next

The skill is globally installed at ~/.claude/skills/foundary-new-project/, so it triggers in any Claude Code session regardless of working directory. The scripts hard-code paths into ~/foundary-tools/, which keeps the scope tight.

Next thing I'm automating: the shutdown flow. When a project turns out to be a dead end, I want "archive the repo, delete the Render service, drop the pgSchema, move the folder to ~/foundary-tools/.graveyard/" as one command. Same skill pattern, reversed.

If you run a portfolio of similar side projects as a solo builder, this is the best automation I've set up this year. The real win is the marginal cost: I can spin up a new experiment at 9:47 PM on a Tuesday and have it deploying by 9:49.

External Sources

Claude Code Skills — official docs on building and installing skills
Render API — Create Service — the POST /v1/services endpoint used here
Drizzle ORM — TypeScript ORM with schema-per-project support
Next.js — the React framework powering the template

If you want more patterns like this landing in your inbox, The Claude Code Memory Starter walks you through the setup over a few short emails — free.

How I Taught My AI Coding Assistant to Remember — and You Can Too

Digital Craft Workshop — Sun, 12 Jul 2026 15:07:06 +0000

Every developer who uses AI coding assistants hits the same wall: you explain something once, and next conversation, it's forgotten. You correct a mistake, and three sessions later, the same mistake appears. It's like working with a brilliant colleague who has amnesia.

Today, I want to share a workflow I've been using with Claude Code that fundamentally changes this dynamic. Instead of repeating myself, I tell Claude to write down what it learns — and it actually sticks.

The Problem: Groundhog Day Development

Here's a real scenario from my codebase. I'm building a team-based access control feature in a .NET + React application. During our first session, Claude:

Added comments to every file (I don't want comments)
Created EF Core migrations (we use raw SQL scripts)
Added unnecessary using statements
Used pricing flags instead of feature flags
Forgot to add database GRANT permissions for new tables

Every single one of these mistakes would repeat in the next conversation. I'd have to re-explain the same rules over and over.

The Solution: Two Persistence Mechanisms

Claude Code has two built-in mechanisms for persistent context that survive across conversations.

1. CLAUDE.md — Project Rules

CLAUDE.md sits in your project root and acts as a set of instructions Claude reads at the start of every conversation. Think of it as a .editorconfig for AI behavior.

Here's what mine looks like after a day of working together:

## Code Style Rules
- No comments in code. Code should be self-explanatory.
- No unnecessary usings. Every using must be actually needed.

## Database Rules
- Never create EF Core migrations. Always deliver raw PostgreSQL scripts.
- Always add GRANT SELECT, INSERT, UPDATE, DELETE for application-dev user.

The key insight: I didn't write these rules upfront. They emerged organically from corrections during our work session. When I said "stop adding comments," I followed up with "write that down so you remember next time." Claude added the rule to CLAUDE.md, and the behavior stopped — permanently.

2. Memory Files — Contextual Knowledge

The second mechanism is Claude's memory system — markdown files stored in .claude/projects/.../memory/. Unlike CLAUDE.md (which holds rules), memory files store contextual knowledge that helps Claude make better decisions.

For example, after I explained how feature flags work in our codebase (frontend hooks, backend services, sysadmin razor pages), I told Claude to save that knowledge. It created a reference file covering:

Which hook to use for feature flags vs pricing flags
Where the sysadmin flag editor lives
The naming convention for flags

Next time Claude needs to add a feature flag, it won't use a pricing flag by mistake. It won't forget to add the checkbox in the sysadmin razor page. The knowledge is there, indexed and searchable.

If you'd rather have this whole setup broken into a few short, copy-paste steps in your inbox, I turned it into The Claude Code Memory Starter — a free email series.

The Workflow: Correct Once, Remember Forever

The pattern is simple:

Claude makes a mistake (or you notice a pattern worth preserving)
You correct it — "don't do X" or "always do Y"
You tell Claude to save it — "write that down" or "remember this for next time"
Claude persists it — either as a CLAUDE.md rule or a memory file
Future conversations benefit — the rule or context is loaded automatically

This turns every correction into a permanent improvement. Your AI assistant gets smarter with every session — not through model updates, but through accumulated project-specific knowledge.

What Goes Where?

Not everything belongs in the same place:

CLAUDE.md is for actionable rules:

Code style preferences
Workflow constraints (no migrations, always run tests)
Project-specific patterns to follow or avoid

Memory files are for contextual knowledge:

How systems work (feature flags, auth, deployment)
Project goals and motivations
References to external resources
Team member roles and responsibilities

Neither should contain things derivable from code (architecture, file paths) or git history (recent changes, who did what).

Real Impact

After one working session with this approach, my Claude Code setup knows:

Never add comments to code
Always provide raw SQL with GRANT statements for new database objects
How feature flags work across three layers (frontend, backend, sysadmin)
The full requirements spec for the feature we're building
That tms_accs is a feature flag, not a pricing flag

Tomorrow, when I start a new conversation to continue this feature, none of this context will be lost. I won't waste the first 10 minutes re-explaining constraints. Claude will just... know.

Getting Started

If you're using Claude Code, you can start right now:

Create a CLAUDE.md in your project root
Next time you correct Claude, add: "and write that down so you remember"
Watch as your AI assistant accumulates project knowledge over time

The best part? These files are just markdown. You can review them, edit them, commit them to your repo (CLAUDE.md), or keep them local (memory files). Your team members can benefit from the same rules, or each developer can have their own memory layer.

It's not about having a smarter model. It's about building a smarter working relationship — one correction at a time.

If you want the starter version of this to land in your inbox, The Claude Code Memory Starter walks you through it over a few short emails — free.

From .NET Architect to Frontend Developer — What Surprised Me, What I Miss, and What I Had to…

Digital Craft Workshop — Fri, 10 Jul 2026 15:03:05 +0000

From .NET Architect to Frontend Developer — What Surprised Me, What I Miss, and What I Had to Unlearn

You may remember me from the days when I wrote about CQRS, DDD, and .NET. It’s been three years — I’ve crossed the bridge to the other side.

Bridge between backend and frontend (chatGPT generated)

I burned out at my previous job three years ago and started looking for new opportunities. Along with a new company came the chance to fill a missing role on the front-end team. I took the opportunity and gradually transitioned from full-stack to fully front-end focused. And just like that, my entire scope changed.

Why the sudden shift?

I’ve always wanted to work on something more visible. My creativity was getting thirstier by the day, and the backend started to feel dull.

In the backend world, I satisfied my creative itch through architecture — from individual projects and services to entire application structures. Now, I express that creativity through layout design, animation choices, and collaboration with UX designers.

How do I feel about React?

React clicked with me right away. Its component-based structure is exactly my kind of fun. Finding the sweet spot between generic reusability and the Single Responsibility Principle is what drives me most.

What surprised me about front end?

📈 The Progress

Before React, my last encounter with HTML, CSS, and JavaScript (mainly jQuery) was about ten years ago — and mostly just minor tweaks. Today, I work on entire websites and complex features. The front end has come a long way. With React, TypeScript, Node.js, and Styled Components, it feels like an entirely different kind of programming.

🛠 Tooling

I expected chaos but got a surprisingly mature ecosystem. Prettier and ESLint help keep the codebase nice and tidy. Visual Studio Code is a pleasant, lightweight environment, and although Microsoft has made good progress with the performance of Visual Studio, it still feels bulky to me.

📦 Bundle size matters

In the backend, I’d happily install any NuGet package — service size wasn’t usually an issue (unless you were deploying in some expensive cloud). In front end, bundle size affects load speed, so you tend to write utilities yourself rather than pulling in a bloated library just for two functions.

What do I miss from the backend?

❌ Clean compiler errors

Maybe it’s just our internal tooling, but deciphering cryptic error messages and not being able to click straight to the offending file still feels frustrating. Visual Studio spoiled me.

🧪 Unit testing

Side note: if you like reading about the craft of crossing between backend and frontend, I share short, free lessons like that in The Claude Code Memory Starter, a tiny email series you can join in one click.

Sure, there’s Jest, but unit-testing React components doesn’t spark joy for me. It makes sense in design systems and shared libraries. But if you’ve got a QA engineer automating tests via Playwright, I honestly don’t see much benefit. On the backend, I often used TDD. On the front end, I haven’t even thought of it.

📚 Third-party libraries

Every dependency needs to have a healthy community and a small footprint. You can’t just grab the first thing that pops up in a search — you need to do at least some due diligence.

What I Had to Unlearn

🧠 OOP Principles — used rarely

I barely use object-oriented principles these days. Inheritance appears only thanks to TypeScript, mainly for models and component interfaces. Encapsulation? Only when a component is used exclusively in one file.

And the only kind of polymorphism I can think of is when children are passed into a React component — allowing it to take on different shapes or content.

🧱 Monolithic thinking

I no longer need to think in terms of big code blocks — modules, domains, layers, orchestration.

Frontend forced me to think in much finer granularity — small components that snap together like Lego bricks.

⚙️ Abstraction

On the backend, I used to spend hours building the perfect abstraction. On the front end, I rarely feel the need — and often don’t even see the room for it.

In closing

I’ve missed writing, and this post is my attempt to start something new.

I’d love to write blog posts from the perspective of someone standing between the backend and front end worlds — or from a backend developer trying to build good frontend code.

Thanks for reading.

Have any of you made a similar transition? What surprised you the most?

If this resonated, you might also enjoy The Claude Code Memory Starter — a short free email series, one bite-sized lesson at a time.

DEV Community: Digital Craft Workshop

Replaying 10,000 Production Fingerprints Through JSDOM in 30 Seconds

Replaying 10,000 Production Fingerprints Through JSDOM in 30 Seconds

The setup

The script

Why this matters more than unit tests

What JSDOM catches that a type check won't

Making it a CI job

Generalizing the pattern

External Sources

Production is the test suite I didn't write

My App Returned 403 But My Code Never Did

The app and the endpoint that broke

A 403 that reproduced every time

Searching for a 403 that does not exist

What the response body actually said

Why this took two hours

The fix: base64 in transit

Every other endpoint I had to patch

What I would do differently

External Sources

TL;DR

Don't Trust AI-Generated Code Without Testing It First

The Task Was Simple

The AI Hallucinated a Newer Framework

The Real Problem: My Review Process

The Embarrassment Factor

Five Rules I Follow Now

Faster Is Only Faster If It Ships Clean

External Sources

What Upgrading to Next.js 16 Taught Me About Trusting Framework Defaults

The convention I trusted

What "broke" actually looked like

Why the upgrade guide will never catch this

How I narrowed it down

The fix: stop trusting the convention, wire it yourself

Why I think it happens (and why the cause is not the point)

How to not get burned on the next upgrade

How I Wired Persistent Memory Into Every Claude Code Session

The realization: hooks inject, they don't execute

Hook 1: recall the moment a session opens

Hook 2: catch the project I name mid-conversation

Hook 3: capture without making me wait

What the extractor actually keeps

If you copy one idea from this

External Sources

How to Make Chrome Extension Iframes Transparent on Dark-Mode Sites (CSS color-scheme Fix)

The white rectangle nobody sees

Why Chrome does this

The two-line CSS fix

The reusable React component

Make the iframe document transparent too

Why this bug is invisible on light-themed sites

How to test for it before customers do

What we shipped

How I Put a Code Reviewer in Front of Every git push to Main with a Claude Code Subagent

The architecture

The subagent definition

tools: Read, Grep, Glob, Bash

The pre-push hook

!/usr/bin/env bash

Sharing one config across every repo

!/usr/bin/env bash

Soft warning, not hard block (and --no-verify still works)

What I deliberately do not ask the reviewer

What this gets you

My Own Content Pipeline Didn’t Have My Own Content. Here’s the Backfill That Fixed It.

My Own Content Pipeline Didn’t Have My Own Content. Here’s the Backfill That Fixed It.

Three platforms, three different integration battles — and a parser bug that silently ate three of my articles.

Dev.to — the platform that just works

Substack — the platform that wants your cookie

Medium — the platform that hands you a zip file

The silent bug

The deduplication logic that saved me twice

What the unified data actually unlocked

Three things I’ll keep doing

External Sources

Our Next.js App Crashed Every 24 Hours. Here Are the Six Memory Fixes.

The Stack

The Fix That Cut Memory in Half

Soft warning, not hard block (and `--no-verify` still works)