DEV Community: Digital Craft Workshop

Meter Your AI Features Before the Call, Not After It

Digital Craft Workshop — Fri, 18 Sep 2026 15:02:05 +0000

Ten to thirty seconds. That is how long a streamed AI call leaves a quota unenforced if the counter goes up when the stream closes, which is the obvious place to put it and the place I nearly put it.

I have wired a usage quota in front of four things now: Claude API calls, video renders, outbound email batches, and one cached lookup that barely deserved one. Every one came down to one small decision. Does the counter go up before the work, or after it comes back?

I wrote the underlying bug up in March, back when it was still a surprise to me. The postmortem is published, so this is what came after it.

The short version: for metered work, increment before the work happens. What decides it is duration. A ten-second call needs the counter in front of it; so does a ten-second render.

Only the write can move

Every metered feature has the same skeleton. Read the counter, compare it against the plan limit, do the work, write the counter back. The write is the only one of the four I can slide.

checkPlanLimits() is the boring part. It looks up the tenant and reads the usage row for the current calendar month, keyed by a plain string like "2026-03". A new month creates a new row on the first call and the old one stays behind as history, so nothing has to be reset on a schedule.

Put the write last and you get the version that reads as fair, because only successful work gets charged.

const limits = await checkPlanLimits(tenant.id);
if (limits.aiUsage.used >= limits.aiUsage.limit) return tooManyRequests();

const response = await anthropic.messages.create({ ... });
await incrementAiUsage(tenant.id);   // count after

Put the write before the work and you get the version I ship.

const limits = await checkPlanLimits(tenant.id);
if (limits.aiUsage.used >= limits.aiUsage.limit) return tooManyRequests();

await incrementAiUsage(tenant.id);   // count first
const response = await anthropic.messages.create({ ... });

Two lines swapped. In Drippery, the drip email tool I build, those two lines sit in the route handler behind AI email generation, capped at ten prompts a month on the Starter plan.

tooManyRequests() returns a 429 with a short JSON body, and the client turns that into a counter in the UI reading five of ten used this month. Both versions return the same 429 and render an identical usage counter. The only difference is which side of the model call the write lands on.

Counting last opens a gap between the read and the write. Anything arriving inside that gap reads a stale number and starts work it should not have been allowed to start. How wide the gap gets depends entirely on how long the work runs.

For the non-streaming call that builds a whole email sequence, the work runs five to fifteen seconds. For a streamed generation, the response object stays open until the last token lands, and the natural place to put the increment is the point where the stream closes.

for await (const event of stream) {
  if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
    const data = JSON.stringify({ text: event.delta.text });
    controller.enqueue(encoder.encode(`data: ${data}\n\n`));
  }
}
controller.close();
// counting here puts the write 10-30 seconds after the read

Ten to thirty seconds is a long time to leave a paid endpoint unguarded. It is also long enough that nobody has to be malicious to walk through it. A user who clicks generate and then, seeing nothing happen, clicks again has already done it.

Most rate-limiting advice was written for CRUD endpoints. A form submission finishes in forty milliseconds, so hitting the gap takes a deliberately timed second request rather than an impatient second click. A model call finishes in twenty seconds. That leaves enough time for a second click to land inside the gap without anyone trying.

The race window is the whole span between the check and the increment. | Generated with Claude

The cheaper mistake is the one with a ceiling

Counting first has an obvious cost. When the model call fails, the user has spent a prompt and received nothing back. I sat on that one for a while before shipping it.

Then I put numbers on both sides of it. Anthropic API errors show up in my logs at well under one percent of calls. When one lands, a Starter user has nine prompts left for the month instead of ten, and if they write to me about it I add one back by hand.

I have never automated that refund. It happens rarely enough that a hand-written reply is cheaper than the code to avoid it. People also seem to like getting an actual reply.

The error on the other side has no ceiling. Someone firing requests faster than the work completes gets as many paid generations as they can queue inside the window, and I pay Anthropic for every one of them.

A generated email runs a few thousand tokens, so one call costs me somewhere around four cents at the tier I use. Ten of those a month come to forty cents against a nine-dollar subscription, which is why I could price the quota generously in the first place. Without a working quota, there is no ceiling except how fast a user can click.

I keep running into this shape of decision, where the only honest question is which mistake I would rather absorb. I wrote up the way I think about it as a free email series, Good-Enough Engineering.

Card processors settled this argument decades ago. The authorization hold goes on the card before the warehouse picks the item, and it is captured or released once the outcome is known. Same bet here. Stripe releases the hold automatically; I do it by editing a row by hand.

Both orders make a mistake; only one of them has a ceiling. | Generated with Claude

The second race is still in there

Moving the increment forward closes the wide race. A smaller one is still in there, inside the increment function.

export async function incrementAiUsage(tenantId: string): Promise<void> {
  const month = getCurrentMonth();
  const existing = await db.select().from(aiUsage).where(
    and(eq(aiUsage.tenantId, tenantId), eq(aiUsage.month, month))
  );

  if (existing.length > 0) {
    await db.update(aiUsage)
      .set({ promptCount: existing[0].promptCount + 1, updatedAt: new Date() })
      .where(and(eq(aiUsage.tenantId, tenantId), eq(aiUsage.month, month)));
  } else {
    await db.insert(aiUsage).values({ tenantId, month, promptCount: 1 });
  }
}

Two concurrent calls can both select a count of four. Both then write five, and the tenant gets a free prompt out of the arithmetic.

Postgres will collapse the read and the write into one statement whenever I decide it matters. The unique index on tenant and month is already in the schema, which is the only thing ON CONFLICT needs to key on.

INSERT INTO drippery_ai_usage (tenant_id, month, prompt_count)
VALUES ($1, $2, 1)
ON CONFLICT (tenant_id, month)
DO UPDATE SET prompt_count = drippery_ai_usage.prompt_count + 1;

That statement buys less than it sounds like. It removes the lost update between the SELECT and the UPDATE. It does not cap the counter, because the quota comparison is a separate read further up the route, so prompt_count will still go from ten to eleven if the handler asks it to. The March piece said the rewrite left "no race window at all", which was too strong.

The other option was to wrap the select and the update in a transaction with SELECT ... FOR UPDATE, which holds the row until the transaction commits. That closes the lost update, but it still needs a retry for the first call of a new month, when there is no row to lock yet and both inserts race the unique index. It is also more code than the single statement above, so if I am going to touch this at all I would rather touch it once.

I have not shipped it either way. The window here is one database round trip rather than thirty seconds of streaming, and Drippery serves a few dozen AI requests a day, so two of them colliding inside a couple of milliseconds has never appeared in the logs. I ran those numbers here too and got the opposite answer.

Two reads of four both write five, and one prompt goes unbilled. | Generated with Claude

Three of my four quotas count first

The rule is not universal, and the four quotas I run do not all land the same way.

Claude API calls. Count first. The work takes seconds, and it costs money on someone else's meter. Once the request is out I cannot un-spend it.

Video renders. Count first. The job is queued long before the GPU picks it up, so the counter goes up at enqueue. A render sits in a queue for minutes before it starts and then occupies a single graphics card for several more. Counting at completion would leave a window measured in minutes, and the queue is allowed to get long.

Outbound email batches. Count first, at enqueue. Sent email is the least reversible thing on this list. A batch that goes out twice is a deliverability problem I get to explain to a mail provider, and that one I cannot absorb quietly.

A cached lookup. Count after, and honestly it barely matters. The work is a local read that finishes in single-digit milliseconds. Charging a user for a lookup that errored would be the more annoying of the two mistakes, so this is the one case where counting after is the correct call.

A four-cent API call and a render on hardware I already own leave the same window open if they both take thirty seconds. Which is why the cache and the render queue land on opposite sides despite costing me nothing but electricity.

Only the cache finishes fast enough that counting after stays safe. | Generated with Claude

The render queue is the one that surprised me. I had it counting on completion for a while, on the reasoning that a render that crashes halfway through a scene should not cost anybody anything. Then I watched the queue back up and realised I was measuring the wrong span. The window is queue wait plus render time, which on a busy night is most of an hour.

The Drippery code has not changed since I wrote that first piece. The decision takes me about thirty seconds now instead of an evening. Any time I put a quota in front of something that runs longer than a database write, the counter goes up before the slow thing starts, and I move on to the interesting half of the feature.

External Sources

Anthropic streaming docs — the delta types the streaming loop has to guard on
PostgreSQL INSERT reference — ON CONFLICT DO UPDATE semantics
Stripe on authorization holds — the hold-then-capture pattern
MDN on Server-Sent Events — the streaming transport itself

Nearby: getting Claude to return strict JSON without drift, from the tool that publishes these posts, and the $0/month background job architecture behind the email side of Drippery.

I build Drippery in public and write up the decisions as they happen. If the trade-off in this piece is the part you want more of, Good-Enough Engineering is a free five-email series on making that call.

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

I Taught My Articles To Make Their Own Reels

Digital Craft Workshop — Wed, 16 Sep 2026 15:02:34 +0000

TL;DR

I spent one evening building a pipeline that turns any published article into a 9:16 Reel. It is narrated in my cloned voice, captioned with karaoke-style word highlights, branded with Digital Craft Workshop colors, and uploaded to Cloudflare R2 ready to post on Instagram or YouTube Shorts.

The whole thing lives behind a single button in Article Forge. Regenerating a reel costs zero API credits, because the scenario and audio are cached per article.

Why I Bothered

I write one article a week. Sometimes more. Each one already takes hours.

Cutting a vertical video on top of that with the usual tools means opening Premiere, writing a script, recording a voice over, and syncing captions by hand. That is enough friction that I never do it.

But Reels and Shorts feed the algorithm. A 30-second hook with my voice out-performs a static link share by a wide margin, and I was leaving all of that on the table for one dumb reason: the editing tax.

So I built the friction out.

The Pipeline, End to End

A single POST request to /api/articles/[id]/video kicks off the whole thing. The render runs in the background; the editor UI polls and shows a preview when the MP4 is ready.

Under the hood it runs ten coordinated steps:

Postgres and Drizzle track the render job through its states — queued, then processing, then done.
Cloudflare R2 stores the final MP4 and the audio assets.
Claude Haiku 4.5 turns the article into a 3-to-5 scene script with a hook, body beats, and a closing call to action.
node-html-parser scrapes the cover and diagram images from the published Substack post, so the reel reuses the brand-styled diagrams I already shipped instead of generic stock art.
ElevenLabs narrates each scene in my cloned voice on the $5/month Starter plan. The /with-timestamps endpoint returns per-word alignment, which the captions need later.
sharp and SVG render each scene as three PNG layers: the background image, the static chrome (header plus progress dots), and the foreground content overlay.
FFmpeg assembles the per-scene MP4 with a Ken Burns zoom on the background, a fade-in on the content, and a 0.4-second silent pause between scenes so the ear can land before the next narration starts.
libass burns in the ASS karaoke captions, turning each word red as it is spoken and locking the line to a fixed bottom anchor so it never jumps as scene lengths change.
Loudnorm at -14 LUFS matches the reel to Instagram and Shorts feed loudness. Skip this and the reel plays quieter than everything around it in the feed.
An R2 upload publishes the final MP4, and the UI panel renders it inline with a download link.

The ten stages that turn a published article into a captioned 9:16 Reel. | Generated with Claude

The whole thing takes 45 to 60 seconds per reel.

I broke this build down one stage at a time in a free email series, Reel Pipeline Series, if you want the version with the actual prompts and config.

The Hardest Part Was Not What I Expected

The hardest part wasn't the AI. It was the captions.

ASS subtitles need libass, and Homebrew's stock FFmpeg formula ships without it. Generic FFmpeg overlay filters handle static images fine, but they blow up exponentially once you try to layer 30 word-level frame overlays for karaoke timing.

I spent a frustrating hour on that before the fix clicked: uninstall the stock formula, install homebrew-ffmpeg/ffmpeg/ffmpeg from the dedicated tap, and libass comes along for free.

The second caption problem was the line jumping. ASS bottom-anchor alignment plus a variable number of lines means a one-line caption sits at a different height than a two-line caption. I fixed it by pinning every dialogue event with an explicit \pos(540,1800) override — same anchor, every scene, no jumping.

The Surprise Win Was Caching

I added per-article caching on the second iteration, after noticing that every "regenerate" was re-calling Haiku and re-running six ElevenLabs synthesis requests. Each regeneration was burning roughly $0.10 of credits, which does not sound like much until you are iterating on a visual tweak for the tenth time.

Now the scenario JSON and the per-scene audio buffers live in Postgres and R2. The next time I click "Generate Reel" for the same article, the render reuses both and only re-runs FFmpeg.

Zero API calls. Zero credits spent. I can iterate on visual tweaks — a different brand color, a different motion variant — without paying for any of it.

If I want a genuinely fresh take, I hit POST /api/articles/[id]/video?fresh=1 and the pipeline goes all the way back to Haiku.

What I'd Build Next

Three things sit on the wishlist.

Swap Haiku for gpt-4o-mini for the script step — same JSON output, cheaper per call. It is on the list, just not done.
A "Post to Instagram" button on the panel that pushes the MP4 straight through the Graph API, so I stop downloading and re-uploading by hand.
AI-generated background images per scene for the beats that don't have a Substack diagram to reuse, using a cheap fast model like Flux Schnell.

None of these are blocking. The pipeline already does the job I built it for, and I would rather ship reels than polish the tool that ships reels.

The Real Lesson

The pipeline is not impressive for any single component. What matters is that the gap between "I published an article" and "I have a Reel" is now thirty seconds of clicking.

That changes my behavior. I post the reel. The algorithm rewards the post. The next reel gets a little more reach, and the flywheel keeps turning.

This is the part of building in public that took me longest to accept. The build is the easy half. Being public consistently is the hard half, and the only way I stay consistent is to delete every excuse not to post before it can talk me out of it.

This pipeline deletes one of them.

External Sources

ElevenLabs API — voice cloning and per-word timestamps
FFmpeg — per-scene assembly and Ken Burns motion
libass — ASS subtitle rendering for karaoke captions
sharp — SVG-to-PNG scene layer compositing
Cloudflare R2 — object storage for the finished MP4

One More Thing

— Daniel

P.S. If you want the whole build as a step-by-step log, I packaged it as a free email series, Reel Pipeline Series, one email per stage.

I turn articles like this one into short vertical videos with my own pipeline. The free playbook is here: https://danielrusnok.gumroad.com/l/article-to-reel-playbook

My app records its own tutorials now

Digital Craft Workshop — Mon, 14 Sep 2026 15:06:21 +0000

A couple of evenings ago I sat down to make tutorial videos for the Reel Pipeline Kit. Eight of them, one per part of the app. And I hit the same wall I always do: I don't want to be on camera, and I don't want to hand-narrate eight screen recordings at nine in the evening.

So I didn't. I built a thing that records the app for me.

The wall

The kit has about eight areas a buyer needs to understand: install and keys, fetching an article, the scenario editor, voice, music, animated clips, branding, and the final render. Each one deserves its own short, detailed walkthrough. Faceless, the same look as the demo videos already on the product page.

Doing that by hand is death by a thousand takes. Open the app, click the thing, fumble the mouse, re-record, line up the voiceover, cut the captions. Then do it seven more times. On top of that, my hand shakes on the mouse and my narration drifts out of sync, so the eight videos never quite match each other. I'd rather write the pipeline once and let it run while I make tea.

The shape of it

Here is how it works. A headless Chrome drives the real app on localhost. It clicks through the actual UI, real buttons, not a mock. While it drives, it captures the screen frame by frame. My cloned voice reads a script I wrote. Captions light up word by word underneath. A small Digital Craft Workshop card opens each video with a whoosh.

The obvious route is a desktop screen grabber, OBS or something like it. I tried that first and got a black rectangle. A screen recorder launched over SSH has no desktop to point a camera at: no monitor, no compositor, nothing painted to a screen for it to see. So instead I let Chrome film itself. It streams its own frames over the debugging protocol, one image per repaint, lossless, and ffmpeg stitches them into a 1080p video afterward. The browser is both the thing being recorded and the camera holding still in front of it.

Chrome films its own frames over the debugging protocol, no desktop required. | Generated with Claude

The cursor is fake too. Headless Chrome has no pointer to record, so I draw one on the page myself. It is a small element that slides between the buttons the script is about to press, and it flashes red for the fraction of a second it clicks. Without it the videos felt haunted, buttons depressing on their own with nothing moving toward them. The fake cursor is the cheapest trick in the whole pipeline and it does more for the "a person did this" feeling than anything else.

The voice is ElevenLabs with a clone of mine. When it returns the audio it also hands back the timing of every word, where each one starts and ends in the clip. That timing is what makes the captions land on the beat instead of drifting a syllable behind the whole way down the video.

The fifteen-line map

The first pass looked fine and read wrong. The captions said exactly what I said out loud.

When the voiceover says "localhost three thousand" so my cloned voice pronounces it properly, I don't want the caption to read "localhost three thousand." I want localhost:3000. Same with data/settings.json, which I say as "data settings json," and Node 20. A developer watching a developer tool notices that kind of thing right away, and once they notice it the whole video reads as amateur.

The spoken form maps back to how you would actually write it. | Generated with Claude

So there is a small map. I spell each term out the long way for the voice, and the caption swaps it back to how you would actually write it. That is the whole trick. It is maybe fifteen lines of code, and it is also the difference between something that looks like a tool and something that looks like a toy. The same word-level caption timing I wrote about for the reels earns its keep here too.

If you want this whole machine broken down stage by stage, I wrote it up as a free email series, one part a week: the Reel Pipeline Series.

Don't touch my setup

One more thing I care about. The recorder pokes my live config while it films. It clicks the voice provider, types a key into a field, toggles animation on a scene, opens the branding panel. Those are my real settings on my real machine, and the whole point of filming is to show them being used.

So it puts everything back. It types a fake key, films the moment, clears the field before anything saves. It flips a radio to show the option, then flips it back to what it was. Nothing the recording does survives the recording. A tutorial recording has no business quietly changing my own configuration.

What came out

Eight episodes. One per feature, one to three minutes each, 1080p, my voice, red captions, the DCW mark on the front. They are all up on the Digital Craft Workshop channel:

Eight episodes ride the same pipeline; the ninth is barely any work. | Generated with Claude

My favorite part is the ninth episode, the one I haven't made yet. It would barely be work: a script and a short recipe of which buttons to press, run through the same pipeline. The expensive part was building the first one. Everything after that rides rails that are already there.

The honest bit

It isn't spotless. The render episode shows the app producing a real reel, and the same machine is grinding through my production render queue while it films. So the render list is noisy with other jobs, and a thumbnail or two comes up black in headless Chrome. In that episode I play the finished reel from history instead of watching a progress bar crawl for ten minutes. Good enough for a walkthrough. I would rather ship eight honest videos than polish one forever, and that is a trade I keep making on purpose.

The kit is on the bench, the tutorials record themselves now, and I got my evening back.

The reel pipeline behind these tutorials is its own free email series, one part a week: the Reel Pipeline Series.

External Sources

ElevenLabs — cloned voice with per-word timings
Chrome DevTools Protocol — headless frame capture
FFmpeg — stitches frames into video
Wan 2.2 — image-to-video for animated clips

The kit itself: Reel Pipeline Kit — turn any article into a narrated, captioned 9:16 reel, locally, on your own keys.

I skipped RAG for my AI app's voice. Static markdown won.

Digital Craft Workshop — Sat, 12 Sep 2026 15:03:35 +0000

I was one commit away from putting a vector database behind my AI's voice. I deleted that plan and used a single markdown file instead. The drafts got better, and the context now costs me $0 a month.

The feature is a Note drafter I built into my Substack growth dashboard. You give it a prompt like "build-in-public milestone, 3 variants" and it returns three Substack notes that sound like me. What made it worth writing up was where the complexity actually belonged, which turned out to be somewhere much simpler than I first assumed.

The first design I sketched stored every published note and every voice decision in a vector database, and let the model retrieve the relevant pieces per draft. Embeddings and a similarity search in front of the model, the standard RAG pipeline. That setup is built for fetching knowledge on demand, which sounded right until I looked at what voice actually needs.

What voice actually is

Voice for an AI assistant is a stable identity: who you are and what tone you use. It is the part that should come out the same every single time you draft.

Knowledge changes by query. What happened recently in this project, or what a term means: that kind of context shifts per question and benefits from retrieval.

For a Note drafter specifically, consistency is most of the value. The whole point of the feature is that three drafts in a row read like the same person wrote them, and that the person is me. If the voice drifts between drafts, I have to rewrite them by hand, which defeats the reason I built the tool. So the register is the one thing I cannot let move.

RAG is a knowledge tool. When you bolt it onto a voice problem, a few things break, and they all push the output in the same wrong direction.

The context stops being consistent. Two adjacent prompts pull different chunks, the model sees different priors, and the voice wanders between drafts. One note sounds like me, the next sounds like a press release.

The retrieval also pulls in irrelevant hits. A query about a "build-in-public note" matches old project facts and architecture decisions. None of that is voice. It is noise, and the model folds it in, dragging the register toward generic blog post.

And you pay for all of it. Each generation turns into a vector search call plus an LLM call. For voice, the search half adds latency and cost and returns nothing you needed.

RAG pulls different chunks each query; a voice baseline stays constant. | Generated with Claude

What I did instead

The voice lives in a 500 to 1000 token markdown file in the database, edited from a settings page. Nothing clever. It looks roughly like this:

# Voice profile

## Tone
- Specific, no fluff. Short sentences.
- Czech directness in English. Admit uncertainty when present.

## No-go phrases
- "In today's fast-paced world"
- "Game-changer", "Unlock", "Mind-blown"
- Em-dashes used as a drama device

## Good note examples
[3 actual high-performing notes pasted in]

## Bad note examples (and why)
[1-2 generic AI-sounding notes pasted in]

On top of that file I inject the last 10 published notes from the app's own database as a register reference. They are not retrieved by similarity. They are the trailing window: the last 10 published notes, always that same set, pulled without any search step.

Assembling that window is a plain SQL query. The dashboard already stores every note I publish, so the drafter just selects the ten most recent rows ordered by publish date and pastes their text into the prompt. There is no embedding step and no index to keep warm. The query runs in a few milliseconds and the result is the same for every prompt in a given moment, so it stays cheap no matter how many drafts I ask for.

That trailing window matters more than it looks. It keeps the model anchored to how I have actually been writing lately, not how I wrote six months ago, and it updates on its own as I publish. The file holds the rules, and the window keeps showing the model how I write right now.

Editing it is just as boring, which is the point. When a draft comes out wrong, I open the settings page, add the offending phrase to the no-go list or paste in a better example, and save. No re-indexing, no pipeline to babysit. The next draft picks up the change immediately.

The whole prompt lands at about 2k tokens in and 300 out, on Gemini 2.5 Flash Lite. That works out to roughly $0.0003 per draft, or about five cents for a month of five drafts a day.

The 80% comes from the examples

The strongest thing I took from this build: three good note examples plus one or two bad ones did more for output quality than a model upgrade would have.

The model learns the register from actual sentences, not from a description of the register. A rule like "no fluff phrases" tells it what to avoid. An example shows it the target to hit, and a target is far easier to copy than a prohibition.

I tested it both ways. With rules only, a "shipped a new feature" draft came back as something like "Excited to share a game-changing update that will supercharge your workflow." Correct topic, generic voice, exactly the register I do not use. With three of my real notes in the file, the same prompt produced a draft that opened with the concrete thing I had shipped and why it annoyed me enough to build it, in short flat sentences. Same rules, same model, same prompt. The only difference was that the model now had sentences to imitate instead of a list of things to avoid.

Rules alone drift generic; three real examples pull the draft into voice. | Generated with Claude

I collect more of these "where does the complexity actually belong" calls in a free email series, The Claude Code Memory Starter.

When RAG is right

None of this is anti-RAG. Retrieval earns its place when the context actually changes by query, so that feature X and feature Y pull different docs, or when there is more context than the prompt window can hold.

There is a spot for it in this same dashboard, in fact. The day I add a "what have I already written about pricing" lookup, that is retrieval work: the answer is a specific past post, and there is far more of it than I want sitting in a prompt. The voice file has nothing to do with it.

For voice, none of that is true. The identity is the same every time, and it fits in the prompt with room to spare. Getting the register right is a matter of showing the model the right examples, not searching for them.

The rule I keep coming back to

Voice is a baseline. Knowledge is retrieval.

Bake the constant part into the system prompt as a static blob, and retrieve only what actually changes per query.

I built this for my own dashboard, but the same split holds for any AI feature you bolt onto your own tool, whether that is a chat wrapper or a content drafter like mine. Before reaching for a vector DB, ask whether you actually need retrieval, or whether you just need a baseline.

Most of the time, you do not.

External Sources

Retrieval-augmented generation — what RAG is, in one page
Pinecone — managed vector database for retrieval
Google AI for Developers — Gemini Flash Lite models and pricing

I write up more of these build decisions as a free email series, The Claude Code Memory Starter.

I'm Daniel. I build content tools and small games solo, and write about what breaks on the way.

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

Three things I learned shipping ONNX to Fly.io

Digital Craft Workshop — Thu, 10 Sep 2026 15:04:03 +0000

ld-linux-x86-64.so.2: No such file or directory. That error cost me 20 minutes. Then OOM killed my Fly machine within 30 seconds of first inference. Then Pinecone's SDK threw "Must pass in at least 1 recordID" on a call where I clearly passed an array of IDs. Three errors in one afternoon, all misleading.

I was shipping a small Node feature for grownote, my Substack growth dashboard. The feature: a button that pulls memories from my mem0 (Pinecone-backed) and bakes them into AI-generated engagement drafts. To query Pinecone semantically I needed the same embedding model that wrote the index: sentence-transformers/all-MiniLM-L6-v2. The Node-friendly route is @xenova/transformers, an ONNX runtime port of the same model.

Three things had to work: getting the ONNX native binary running on Linux, fitting the model in machine memory, and making the Pinecone client behave like its docs say. None of them did on the first try.

1. Alpine vs glibc: the silent native binary trap

My Dockerfile was the standard node:22-alpine recipe. Multi-stage build, deps + build + runtime, ~180MB image. It's been good for grownote since launch.

@xenova/transformers installed cleanly and the build passed. The container came up, but the first call to the embedding pipeline returned this from Fly logs:

Error loading shared library ld-linux-x86-64.so.2: 
No such file or directory 
(needed by /app/node_modules/onnxruntime-node/bin/napi-v3/linux/x64/libonnxruntime.so.1.14.0)

The ld-linux error that really means Alpine has no glibc | Generated with Claude

The lie in the error message: ld-linux-x86-64.so.2 is the glibc dynamic linker. The file is missing because Alpine doesn't have glibc. Alpine uses musl libc, which uses a different linker (ld-musl-x86_64.so.1).

@xenova/transformers ships prebuilt binaries via onnxruntime-node. Those binaries are linked against glibc. They don't run on musl, and there's no onnxruntime-node build for musl in the official package.

You can fix this two ways:

Option A: switch to a glibc base image. Change ARG NODE_VERSION=22-alpine to node:22-bookworm-slim. Image grows ~85MB (Debian is heavier than Alpine). Otherwise drop-in compatible. ONNX prebuilt binaries load without complaint.

Option B: keep Alpine and build ONNX from source against musl. Theoretically possible. Practically not worth the time unless you have hard reasons to keep Alpine (image size for very large fleets, security policy). For one app, this is hours of yak-shaving.

I went with Option A. The Dockerfile change was one line:

ARG NODE_VERSION=22-bookworm-slim

Rebuilt, pushed, the container came up clean.

Lesson: Native Node modules that ship prebuilt binaries are usually glibc-only. Alpine works for pure-JS packages. Once your dep tree includes a compiled module like ONNX or sqlite3, Debian slim is the safer base. If a package fails at runtime instead of install time, you want to catch it in 30 seconds via docker run locally, not after deploy.

2. 512 MB Fly machine: the OOM with misleading symptoms

The next deploy started fine. Health check passed. I clicked "Sync from mem0" in the dashboard. Frontend showed a spinner. After 30 seconds: 502 from Fly's edge proxy.

Browser DevTools showed an empty response body. Frontend logged a generic "Uncaught Error: An unexpected response was received from the server."

I checked Fly logs:

[125.024082] Out of memory: Killed process 634 (node) 
total-vm:23813904kB, anon-rss:391536kB, file-rss:184kB
INFO Process appears to have been OOM killed!

23.8 GB virtual is noise; 391 MB resident is what got it killed | Generated with Claude

The numbers: 23.8 GB virtual memory, 391 MB resident. The kernel killed the process because it was using ~76% of the 512 MB machine RAM, and its heuristic for "this process is about to thrash and bring down everything else" fired.

The 23 GB virtual is misleading. ONNX Runtime mmaps the model file. mmap reserves virtual address space without committing physical memory upfront, and pages get pulled in only as you read them. So the virtual number is meaningless. The resident number (391 MB) is what mattered. On a 512 MB machine, with Node + Next.js + Drizzle + Pinecone client all running, 391 MB just for the embedding pipeline pushed total RSS past the limit.

Two options:

Option A: bump machine memory. Edit fly.toml:

[[vm]]
  cpu_kind = "shared"
  cpus = 1
  memory = "1024mb"

Cost delta: ~$2.50/month at full uptime, less if you have auto_stop_machines = "stop" and min_machines_running = 0 (idle machines don't bill). For grownote, which I use evenings, real cost delta is ~$0.40/month.

Option B: externalize the embedding. Use HuggingFace Inference API for the model. POST text, receive vector. No local model. It adds an HF API token as a new secret and 200-500ms of HTTP roundtrip per query, but no native deps and no memory overhead.

I tried Option B first because it felt cleaner. Then I realized HF Inference API for a personal app is yet another vendor dependency. If HF goes down, my engagement queue can't sync mem0. The whole point of self-hosted Pinecone with a local-friendly model was to own the stack.

I went with Option A. One-line config change, 1 GB machine, problem disappears. Fly auto-stop means I'm paying ~$0.40/mo extra for the few hours per day the app actually serves traffic.

Lesson: When local model loading OOMs on a small VM, don't reflexively reach for an API. Check the cost of bumping memory first. Auto-stopped machines are nearly free at idle. Bumping memory is usually cheaper than adding an external API, which means one more token to manage and one more service that can go down.

Wiring memory into your own Claude Code setup is its own rabbit hole; I packed the hooks, the config, and the mistakes that bite first into a free email series, The Claude Code Memory Starter.

3. Pinecone v7 SDK: the misleading validator

With Alpine swapped and machine bumped, the embedding worked. Now the actual feature: list all my mem0 records, translate Czech ones to English, re-embed, upsert. Pinecone has explicit APIs for all four steps.

The list call worked:

const page = await index.listPaginated({});
const ids = page.vectors.map(v => v.id);

The fetch call did not:

const fetched = await index.fetch(ids);
// PineconeArgumentError: Must pass in at least 1 recordID.

I logged ids to confirm: an array of 10 valid UUIDs. The validator was clearly checking something, but not what the error message said.

index.fetch(ids) throws; the validator wants { ids }, not a bare array | Generated with Claude

I dug into the fetch validator in node_modules/@pinecone-database/pinecone:

const validator = (options) => {
    if (!options.ids || options.ids.length === 0) {
        throw new PineconeArgumentError('Must pass in at least 1 recordID.');
    }
};

It checks options.ids, not the argument I handed in. My bare array arrived as options itself, so options.ids was undefined and the guard fired, even though the array held 10 entries.

The signature that works:

const fetched = await index.fetch({ ids });

Object-form, with ids as a property. That's the v7 FetchOptions shape ({ ids: string[] }); the error message just never names the property it actually wants.

The clearer case is upsert, which Pinecone v7 explicitly moved to object-form. Pass the old array and you get the same kind of validator complaint:

// v6 / examples in older docs:
await index.upsert([{ id, values, metadata }]);

// v7:
await index.upsert({ records: [{ id, values, metadata }] });

Same unhelpful message ("Must pass in at least 1 record to upsert") on a non-empty array.

This cost me 30 minutes between the two endpoints. The fix was trivial. The error message was actively unhelpful.

Lesson: When an SDK error says "must pass in at least 1 X" on a call where you clearly passed multiple X's, the validator is probably reading a property off an options object you didn't pass. Try wrapping the array in an object with a sensibly named property (ids, records, vectors). It's a 5-second test that works disturbingly often.

The Pinecone v7 release notes do mention the object-form move. I found them after I'd already debugged it. Read the migration guide first, even when the major version bump feels minor.

The payoff: same embedding model, two languages

The mem0 server that wrote the Pinecone index is a Python MCP server using the mem0 library, configured to use huggingface/all-MiniLM-L6-v2 for embeddings. The Node app reading the index uses @xenova/transformers with Xenova/all-MiniLM-L6-v2, an ONNX export of the same model.

I'd half-expected a vector dim mismatch or subtle drift between the Python and Node implementations. There was none. The ONNX export is deterministic. Vectors written by the Python pipeline and queried by the Node pipeline match within float precision.

The only thing I had to ensure: the same pooling: 'mean' and normalize: true settings on both sides. Otherwise the model is the model, regardless of which runtime you call it from.

This is genuinely useful: you can write data in one language ecosystem (Python's mature ML tooling) and read it in another (Node's web ecosystem) using the same embedding space. As long as both runtimes load the same model weights and apply the same post-processing, the vectors are interchangeable.

One embedding model, written from Python and read from Node | Generated with Claude

The rules I kept

Here's what I'm carrying into the next build:

Default to Debian for any Node app that might add native deps later. The Alpine image-size win is real for pure-JS apps. The moment you add a native dep, Alpine becomes a tax. Debian slim just works.

Probe small VM memory limits with the actual workload before assuming "it'll fit." A 512 MB machine on Fly comfortably runs Next.js + Drizzle + a few API integrations. It does not run Next.js + ONNX + a model in RAM at the same time. The OOM kill happens fast and the error is generic. Test on the target hardware, not your 32 GB Mac.

When SDK errors don't make sense, check argument shape before checking your data. "Must pass at least 1 X" on a non-empty array is almost always an arguments signature mismatch, not a data problem. Try the object-wrapped form first.

The actual feature now works. Sync runs in 8-12 seconds, costs ~$0.02 per click, and returns a 5-section markdown block of my recent decisions and project state that feeds into AI-drafted Substack engagement comments. The build was supposed to take an evening. It took two evenings plus a memory bump. Worth it for the next year of automated drafts that actually reference what I'm working on.

If you're shipping ML-adjacent Node code to Fly: bookworm-slim base and at least 1 GB of memory. Use Pinecone v7 in object-form. You'll skip three afternoons of confused debugging.

If you want the memory setup behind grownote's mem0 sync, it is a free email series, The Claude Code Memory Starter.

External Sources

Transformers.js (@xenova/transformers): ONNX-powered transformers for Node
ONNX Runtime: the native runtime behind the binaries
Pinecone Node SDK reference: v7 fetch and upsert signatures
Fly.io machine sizing: memory and auto-stop config
all-MiniLM-L6-v2 model card: the shared embedding model

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

I Built a Content Outreach Bot That Runs Itself. Two MCP Servers and a Cron Did the Work

Digital Craft Workshop — Tue, 08 Sep 2026 15:02:40 +0000

I write Notes on Substack to reach other authors. The good move is to pick a strong recent article from someone in my niche, make something for it, and tag them. Done well, it's outreach that doesn't feel like outreach.

Done by hand, it's a chore. Scroll archives. Judge what's actually landing. Render a video. Post the Note. Tag the right person. Forty minutes, three times a day.

I have one good evening window. I'm not spending it scrolling.

So I built it to run without me. Now three times a day a remote agent picks an article, my home GPU renders a reel for it, and a video lands in my Telegram. I react with a thumbs-up. That ships a Substack Note with the video and a real @mention. If I don't react, nothing happens.

The interesting part isn't the AI. It's how dumb the orchestration is once the hard parts live behind MCP.

TL;DR: Two MCP servers (one on Fly, one on my home PC behind a Cloudflare tunnel) become the "hands", a scheduled claude.ai routine becomes the "schedule", and a Telegram reaction becomes the "approval." Each new capability is one MCP tool. Orchestration is a prompt on a cron.

The mental model

Three roles, cleanly split:

MCP servers are my hands. Each thing I can't do yet becomes a tool. Deploy it once, it exists forever.
A cloud routine is my schedule. A remote Claude agent on a cron. It calls the tools in order. It never asks me anything.
A chat reaction is my approval. The one human gate. I react to a Telegram message and that ships.

When I framed it that way, the build got boring in the best way. Every "how do I automate this?" turned into "which of those three buckets is this?"

The three roles behind a self-running bot: tools do the work, a routine picks the moment, one tap approves | Generated with Claude

The flow

End to end, one run looks like this:

  ┌─────────────────────────┐
  │  cloud routine (cron 3×) │   the schedule
  └────────────┬────────────┘
               │ 1. find_reel_candidate
               ▼
  ┌─────────────────────────┐
  │      substack-mcp        │   (Fly.io)
  │  ranks archives, dedup   │
  └────────────┬────────────┘
               │ 2. render_reel_from_url  (jobId, then poll)
               ▼
  ┌─────────────────────────┐
  │         pc-mcp           │   (home PC, CF tunnel)
  │   RPK + ComfyUI → R2     │
  └────────────┬────────────┘
               │ 3. record_reel_outreach
               │ 4. send_reel_draft
               ▼
  ┌─────────────────────────┐
  │        Telegram          │   video lands in my chat
  └────────────┬────────────┘
               │  👍 (message_reaction)
               ▼
  ┌─────────────────────────┐
  │  webhook on substack-mcp │
  │      → publish_note      │
  └────────────┬────────────┘
               ▼
           Substack  (Note + video + @mention)

I touch exactly one of those arrows. The rest runs whether I'm at my desk or asleep.

Server 1: substack-mcp, the brain on Fly

This one wraps the Substack API plus my own "grownote" engine, the thing that drafts and schedules my Substack Notes. The tools:

find_reel_candidate: scans the archives of publications I subscribe to, ranks them by reactions, comments, and restacks, and returns the best one I haven't touched.
record_reel_outreach: logs that I'm about to tap an author, so I don't hit them again next run.
send_reel_draft: posts the finished reel to Telegram and stashes the publish payload.
publish_note: posts the Note. It now supports attaching a video and a real @mention, which is the whole point of the outreach.

The dedup is the part that matters. An outreach bot that taps the same author twice a day is a spam bot. So find_reel_candidate excludes, server-side, every article I've ever made a reel for and every author I've tapped in the last 7 days.

I didn't want a migration for this. So state is just small JSON blobs in a Postgres app_config table:

-- conceptually:
select value from app_config where key = 'reel_done_article_ids';
select value from app_config where key = 'reel_author_taps';

find_reel_candidate reads both, filters the candidate set before it ever returns, and the caller can't accidentally skip the check. The dedup lives where the decision lives.

That's the rule I keep relearning: put the guard inside the tool, not in the prompt that calls it. It's the same reason I put a code reviewer in front of every git push to main instead of trusting myself to remember.

Wiring your own capabilities into Claude Code like this? I keep the whole setup, the hooks, the config, and the mistakes that bite first, in a free email series, The Claude Code Memory Starter.

Server 2: pc-mcp, the muscle on my home PC

The reel itself is rendered locally. My home PC runs the Reel Pipeline Kit (a Next.js app) driving ComfyUI on an RTX 3060. The GPU is free; cloud GPU minutes are not.

So I exposed exactly one tool from that machine: render_reel_from_url. It takes an article URL, produces the branded reel with read-along captions, and uploads it to R2.

The PC sits behind a Cloudflare tunnel so the cloud routine can reach it without me opening a port. Which leads to the one design detail that actually bit me.

The async-job pattern that bites everyone

A reel render takes one to eight minutes. Cloudflare's edge kills a request at roughly 100 seconds on the free tier. So a synchronous render_reel_from_url that blocks until the video is done will always time out for the slow ones. The tunnel hangs up, the routine sees an error, and you've burned a render for nothing.

The fix is to never do long work synchronously behind MCP. Return a handle, poll for the result:

// render_reel_from_url returns immediately
{ jobId: "reel_a3f9", status: "queued" }

// render_reel_status(jobId) is called until done
{ status: "rendering" }
{ status: "rendering" }
{ status: "done", videoUrl: "https://...r2.dev/reel_a3f9.mp4" }

The caller fires the job, then polls render_reel_status every so often until status is done. Each call is well under the timeout. The render keeps running on the PC regardless of who's connected.

Fire the job, then poll for status, so no single call hits the 100-second edge limit | Generated with Claude

I'd already learned this with my local image-gen tool, which works the exact same way. So when I added the reel renderer, job + poll was the default, not a fix after the first timeout.

If you take one thing from this post: long work behind MCP-over-Cloudflare has to be job + poll, never a sync call. The edge timeout isn't negotiable, and you don't want it to be. The alternative is a held-open socket for eight minutes, which is its own kind of fragile.

The orchestrator is just a prompt on a cron

Here's the part that still feels like cheating. The thing tying all this together is a claude.ai cloud routine, a scheduled remote Claude agent that runs three times a day, with the MCP servers connected and a prompt that says, in effect:

Call find_reel_candidate. Take the article URL. Call render_reel_from_url, then poll render_reel_status until done. Call record_reel_outreach. Call send_reel_draft with the video URL. Stop.

That's it. No local machine has to be awake, and no session I have to babysit. It never asks me a question, because there's nothing to ask. The candidate is chosen, the dedup is enforced server-side, and the only human decision happens later, in Telegram.

The orchestration logic is just a paragraph, not code I maintain. When I want to change the behavior, say render two candidates or skip weekends, I edit the prompt, not a deploy. It's the same instinct behind wiring persistent memory into every Claude Code session: let the agent read the state, don't hard-code it.

The approval loop: react-to-publish

This is my favorite trick. send_reel_draft posts the reel to Telegram as a video, and stores the full publish_note payload keyed by the Telegram message_id. The draft just sits there.

Then I set a Telegram bot webhook on substack-mcp, scoped to exactly one update type:

// one-time setup
setWebhook({
  url: "https://substack-mcp.fly.dev/telegram/webhook",
  allowed_updates: ["message_reaction"],
})

Now when I react to a draft message with any emoji, Telegram fires a message_reaction update. The webhook reads the message_id, looks up the stored payload, and calls publish_note. Reacting is shipping.

There are no buttons and no separate app to open. Nothing to remember. I'm in Telegram anyway, so a thumbs-up from my phone publishes a Substack Note with the video attached and the author @mentioned.

One detail worth stealing: the handler removes the pending entry before it publishes. If it published first and deleted after, a second reaction (or Telegram retrying the webhook) could double-post the same Note.

const payload = pending.take(message_id); // atomic read-and-remove
if (!payload) return ok();                // already shipped, or never existed
await publishNote(payload);

Delete-then-act makes the operation idempotent. A second reaction finds nothing and quietly does nothing.

What this pattern is, generalized

Strip away my specifics and the shape is reusable for any solo builder:

Every capability you don't have yet becomes one MCP tool you deploy. Now it exists for every agent, forever.
Keep your guards (dedup, rate limits, idempotency) inside the tools, where a drifting prompt can't skip them.
Use job + poll for anything slow behind a tunnel.
Let a cloud routine be the clock. Orchestration as a prompt is editable in seconds and needs no machine of yours awake.
Make one human gate, and put it where you already are. A chat reaction beats a dashboard you have to remember to open.

The split is the whole trick: the tools do the work, a cloud routine picks the moment, and I approve with a tap. Wire those together and "build it once, it runs itself" stops being a slogan.

I haven't manually picked a reel candidate in two weeks. The bot taps three authors a day. I tap an emoji when I like the result. That's the whole job now.

If you're building your own Claude Code setup, the hooks and guardrails I wish I'd had on day one are in a free email series, The Claude Code Memory Starter.

External Sources

Model Context Protocol (the open spec behind MCP tools)
Cloudflare Tunnel (expose a local service without opening a port)
ComfyUI (node-based local image and video pipeline)
Telegram Bot API (webhooks and message_reaction updates)
Fly.io (where the substack-mcp server runs)

P.S. The funniest part is how little of this is AI. The model picks an article and writes a Note, sure. But the architecture (job + poll, server-side dedup, react-to-publish, a prompt on a cron) is plain systems plumbing. What made it work was drawing the boundaries right. The model just colors inside them, as usual.

I turn articles like this one into short vertical videos with my own pipeline. The free playbook is here: https://danielrusnok.gumroad.com/l/article-to-reel-playbook

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

Not a member? Use this link.

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.