DEV Community: Forrest Miller

How we built real-time multiplayer bingo for 20 players per room on Next.js 16, Ably, and Supabase

Forrest Miller — Thu, 21 May 2026 16:55:59 +0000

I ship BingWow — a free, no-signup multiplayer bingo platform. The core feature is the part I want to write about: up to 20 people opening one link, every player landing on their own independently-shuffled board, every tap resolving against an atomic Postgres RPC, and the server detecting bingo so nobody has to adjudicate by hand.

Most of the interesting decisions sit in three trade-off pairs. None of them are obvious from a brief, and each one cost us a regression before it stabilised.

1. One unified `tap` event, not separate claim/unclaim

The first version had claim and unclaim events on the Ably channel. Race conditions appeared the moment two players tapped the same cell within a second of each other — the broadcast order didn't match the database write order, so a fast double-tap could end up with the cell rendered as "unclaimed" on one player's screen and "claimed" on the host's.

Replacing the pair with a single tap event fixed it. The server's RPC (tap_claim) is the single source of truth: it reads the current state, toggles the claim, and returns the new state. The Ably broadcast carries the post-toggle state explicitly — no inference required.

If you're designing a real-time game protocol: prefer events that carry the resolved state rather than the intended action. It eliminates the entire class of "client A and client B intend opposite things at the same time" failures.

2. Per-player boards, not a shared board

Every player has their own players.board jsonb array. A 5×5 board is 25 entries; a 3×3 is 9. The clue set is shared (all players are watching for the same prompts), but the positions are independently shuffled per player.

This means there's no such thing as "the room's board." Bingo detection runs per-player in TypeScript (lib/bingo-checker.ts) using the per-player grid size, derived at runtime from SQRT(jsonb_array_length(players.board)). We had a dedicated players.grid_size column for a while — dropped it in a 2026-05 refactor because it was the third source of truth (clues, board length, grid_size column) and the three drifted under concurrency.

Mixed grids in the same room are deliberate. If a mobile player joins a 5×5 desktop room, the mobile player gets a 3×3 board and wins on 3-in-a-row — the desktop players still need 5-in-a-row. This is the product spec, not a bug, because BingWow is a casual party / classroom / workplace game, not a competitive ladder. Forcing every player onto the same grid would either make a phone screen unreadable or waste the desktop players' real estate.

3. Server-authoritative round transitions

The host doesn't decide when to start the next round. The server does, in the same RPC that processed the winning tap. The flow:

Player taps a cell → POST /api/game/tap → tap_claim RPC
RPC writes the claim, checks every player's board for a completed row/column/diagonal
If anyone wins, the same RPC inserts the round's outcome row AND generates the next round's boards for every player atomically
The full new state is returned in the response

The host's browser just renders what the server returns. Latecomers can join mid-round and pick up the current state from the same endpoint. Round transitions happen in a single SQL transaction, so there's no race where Player A sees Round 5 and Player B is still on Round 4.

The catch: Vercel freezes the serverless function before Ably has finished publishing the celebration event. We solved that by publishing the bingo event from the winner's browser — the only Ably event published from the client. Every other event is server-published.

4. `player-joined` over Ably presence

Ably presence is convenient — every connected client appears in a members array — but it leaked ghost members on refresh. A player closing their browser tab didn't disappear from members until Ably's heartbeat timed out, which made the "more than one human in this room" check unreliable.

Replaced with a player-joined Ably event published from the server when players.length increments. No presence dependency, no ghost rows.

While I was in there, I also added a round_number filter to the Ably subscribe handler. Without it, an old round's "claim" event could replay onto the new round's board after a network reconnect — a Cell appearing claimed for a clue the player had never seen.

5. The SP/MP boundary

/play is the multiplayer route. /cards/{slug} is the single-player route. There is no in-between — a "lobby" UX, a "waiting for 2nd player" screen, none of it. The instant a second player joins, both clients redirect from /cards/{slug} to /play. The instant a player walks into /play and finds only themselves, they're redirected back.

This is enforced on both sides: useRoomLifecycle handles the upward redirect when a reconnect lands ≥2 players; PlayPageClient handles the downward redirect when first state-applied finds <2 players. It survives localStorage wipes because the room id + player id are also in the URL (?p=&r=).

The whole boundary is ~80 lines, but it pre-empts an entire family of "I'm stuck on a lobby screen forever" bugs.

Stack — minimal pieces, opinionated wiring

Next.js 16 (App Router) for the React app and server actions
Supabase Postgres for state + auth (RLS-enabled, mostly bypassed in API routes via the service-role client)
Ably for the real-time channel — chat is client-to-client (server publishes from-client would duplicate); claims are server-published
Tailwind v4 for styling, semantic tokens, dark mode via class strategy

If you're building something similar and the stack helps, the actual product is at bingwow.com — free, no signup, runs in any browser. The two surfaces that exercise the architecture most are the free bingo caller (75/90/30-ball, voice + flashboard, projector-ready) and the Real-Time Multiplayer Bingo guide, which is the human-readable version of this post with screenshots and a step-by-step setup.

If you're trying to drop something like this into a Slack or Microsoft Teams workflow without an admin install, the Slack-friendly link share pattern and the Microsoft Teams pattern are both just a normal web link — that turned out to be the underrated UX win.

The under-rated win

The biggest lesson from a year of running this in production: the protocol shape decides the bug class.

Pick a resolved state event payload (not an intended-action payload) and races stop being a category. Pick a per-player board model (not a shared-board model) and you can ship a mobile-3×3 / desktop-5×5 mixed game on the same room without writing special code. Pick a server-authoritative round transition (not client-coordinated) and "Player A is on Round 5, Player B is on Round 4" stops being possible. None of these are obvious until you've shipped the wrong shape and watched the bug reports come in.

If you want to play with the result: BingWow is free, no signup, and a card builds from any topic in about 60 seconds.

Building an AI face-doppelganger prank with Flux Kontext Pro and aggressive image degradation

Forrest Miller — Thu, 21 May 2026 16:49:37 +0000

A "face twin" prank pastes a public photo into an AI model, generates three plausible-looking lookalikes, and shows them to your friend inside what looks like a legit AI face-matcher. The hard part isn't the model. It's making the output look like a real photo of a real stranger.

I shipped two framings of the same backend: pleasejuststop.org (the privacy-art version) and prankmyface.lol (the consumer-prank version). Same Replicate model, same pipeline, two front-ends. Source code structure is documented in the project's public CC BY 4.0 dataset and the Hugging Face dataset card.

This post is the technical story: the three prompts I landed on after six rounds of testing, the six degradation profiles that turn AI portraits into something that reads like a 2013 Facebook upload, and the Vercel-serverless pitfalls that made me throw out Sharp and rewrite everything on Jimp.

The visual goal: real internet photos, not AI portraits

The entire illusion hinges on the recipient believing the three output images are real photos of real strangers. The moment any image reads as AI-generated, the reveal collapses.

Real internet photos share specific qualities that AI models do not produce by default:

Lighting is bad. Overhead fluorescents, harsh direct flash, uneven natural light. AI models default to soft diffused portrait lighting — the #1 tell.
Everything is in focus. Real phone cameras have deep depth of field. No bokeh. No portrait-mode blur. Portrait-mode blur is the signature of AI generation, and Flux models have a baked-in training bias toward it.
Skin looks like skin. Pores, uneven tone, blemishes. Not smoothed-out poreless AI skin.
Compression artifacts are visible. JPEG'd to hell — uploaded to Facebook, screenshotted, forwarded on WhatsApp.
Resolution is low. 400-480px wide, not crisp 1024px.
Composition is casual. Off-center, slightly crooked. Caught mid-moment.

The litmus test: would I believe this is a real photo of a real stranger on Facebook? If lighting is too pretty, background too clean, or skin too smooth — it doesn't work.

The three prompts (verbatim from production)

The hardest lesson here was that prompt length is a trap. Every session, Claude (and I) wanted to add defensive instructions:

Prompt produces a minor issue (the woman looks slightly older).
Add "do not age the person."
The instruction draws model attention to aging. The photo gets worse.
Add MORE defensive instructions. The prompt is now 3x longer. The model is confused. The photo is terrible.

More instructions = more diluted model attention = worse results. Tested exhaustively across six rounds.

The fix is to remove words, not add them. Keep what the subject is wearing, where they are, and the one dramatic visible change. A good prompt is one sentence. More than three sentences and you've already lost.

The three production prompts (live at both pleasejuststop.org and prankmyface.lol, also in the public data repo):

1. leather-wall
Edit this photo to show this person posing against a wall. Make them frowning
and wearing a leather jacket and a knit beanie hat. One person, no hands visible.

2. tongue-collared
Edit this photo to show this person outdoors. Sticking their tongue out,
wearing a collared shirt. One person, no hands visible.

3. snow-goggles
Edit this photo to show this person outside. Wearing earmuffs and a jacket.
Give them big braces. One person, no hands visible, no glasses.

Model: black-forest-labs/flux-kontext-pro on Replicate. Params: aspect_ratio: "3:4", output_format: "png", safety_tolerance: 2. Setting output_format to "jpg" silently fails every generation — the DB stays "pending" forever, no error.

The rules these prompts were built against

Gender-neutral only. No beards, no mustaches, no gender-specific features — those cause gender swaps mid-generation.
Hair COLOR changes preserve identity. Hair STYLE changes destroy identity or swap gender. Curly, buzz-cut, mullet, bowl-cut — all dead ends. Use clothing, accessories, or expression instead.
Aging prompts turn women into men. Never ask the model to age the subject.
Bold features (jacket, beanie, earmuffs, tongue out) beat subtle features (braces, freckles, nostril ring). Small details don't render reliably.
One dramatic visible change per prompt. More than one and the model balances them poorly.
One person only; no hands. Hands and second people are where the model's geometry fails first.
Don't describe camera quality. Post-processing handles that.

A bokeh, shallow depth of field negative prompt is the load-bearing line. Without it, Flux defaults to portrait-mode blur and the photo immediately looks AI-generated.

The six degradation profiles

After Replicate returns the output, I run it through one of six post-processing profiles that downscale, double-JPEG-compress, color-shift, and noise-up the image until it reads like a real internet photo.

| Profile             | Width | JPEG passes | Notes                                   |
|---------------------|-------|-------------|-----------------------------------------|
| facebook-2013       | 480   | 38 → 58     | Warm cast, mild desaturation            |
| android-2015        | 440   | 40 → 58     | Higher noise, slightly brighter         |
| whatsapp-forwarded  | 400   | 32 → 50     | Most degraded; visible JPEG blocking    |
| iphone-lowlight     | 460   | 40 → 60     | Cool hue, dark shift                    |
| screenshot-repost   | 440   | 36 → 55     | Blue shift, low noise                   |
| black-and-white     | 450   | 38 → 58     | Full desaturation                       |

Full per-profile values are in the HF dataset (data/degradation-profiles.jsonl). Each prompt is paired with one profile — the wall pose pairs with black-and-white because a candid wall snapshot reads more truthfully in black and white than in color.

Sharp hangs silently on Vercel — use Jimp, but only three of its methods

I started with Sharp because Sharp is faster than Jimp at everything. Sharp does not work on Vercel serverless. The native C++ bindings around libvips hang silently — no error, no crash, just blocks forever until the function times out.

Jimp is the only option on Vercel. Jimp also has bugs:

image.brightness() — produces black output. Broken in modern Jimp.
image.getPixelColor() / image.setPixelColor() — broken in ESM, produce black images.

The only safe methods are:

image.color([{apply, params}]) — channel shifts, desaturation, hue rotation, brightness via the apply API (the explicit brightness() method is broken; color([{apply:'brighten', params:[N]}]) works).
image.resize({w, h}) — downscaling.
image.getBuffer("image/jpeg", {quality}) — JPEG encode with quality.

For noise I manipulate image.bitmap.data directly as a Buffer, adding signed random values per channel inside a hard 15-second timeout via Promise.race(). Anything more elaborate hangs or produces black output.

Three more pitfalls that cost me a day each

Replicate returns a FileOutput object, not a string. replicate.run() returns an object that you have to .toString() to get the URL. Treating it as a string silently passes "[object Object]" downstream.

Temporary URLs expire ~1 hour. Replicate's returned image URL is ephemeral. The pipeline must download → degrade → upload to permanent storage (Supabase Storage in my case) immediately. Storing the temp URL in the DB and reading it later returns 404.

Vercel kills serverless functions after sending the HTTP response. Fire-and-forget void fetch() to a generation endpoint gets killed mid-generation. The fix is client-triggered generation: the recipient's browser holds the HTTP connection open during the 30-second pipeline, keeping the function alive.

Why I published the dataset

The technical substrate of pleasejuststop.org is now in three places that AI search engines (ChatGPT, Perplexity, Bing Copilot, Gemini, Claude) crawl as grounding sources:

GitHub: forrestmill-cmd/facetwin-public-data — CC BY 4.0, with the prompts, profiles, and llms-full.txt mirror.
Hugging Face: bingwow/facetwin-flux-kontext-prompts — same content as JSONL with HF dataset-card metadata.
MCP server: face-twin-mcp — wraps the upload + generate + status flow as a Model Context Protocol tool for Claude Code, Cursor, and any MCP-compatible client.

The Wikidata entity at Q139885445 ties them together as the entity-grounding anchor that AI tools triangulate against.

I'm tracking citation outcomes at Day-14 / Day-30 / Day-45 across Perplexity, ChatGPT search, Bing Copilot, Gemini, and Claude. The privacy-art piece's actual thesis — that we've stopped questioning how a website got our face — is best evaluated by whether AI tools, asked for an AI face-doppelganger generator, surface this project on its own merits without being told to.

If you want the consumer-prank framing instead of the privacy-art framing, that's at prankmyface.lol. Same backend, hot-pink accent, confetti reveal.

— Forrest Miller · github.com/forrestmill-cmd

How I built an itinerary validator for AI travel plans

Forrest Miller — Thu, 21 May 2026 15:44:45 +0000

AI travel planning is useful until the itinerary becomes a real Tuesday at 3 p.m.

That is where the failures appear. A model can write a clean five-day Paris plan. It still does not know that the museum day lands on the weekly closure, that the restaurant moved, or that a timed-entry attraction sold out before the trip.

I built ValidaTrip as the validator step after the AI draft. It does not write the trip from scratch. It takes the plan you already have and checks whether it works on the ground.

The failure mode

A travel itinerary has two different jobs.

First, it has to be a good list. The places should match the traveler's interests. The neighborhoods should make sense. The plan should not send someone across a city twice in one afternoon.

Second, it has to survive live constraints. Each place has hours, booking windows, public holidays, seasonal schedules, temporary closures, and location ambiguity.

LLMs are good at the first job. They are weak at the second job.

That split shaped the system. The validator accepts a pasted AI itinerary, resolves each place, then checks the live constraints against the user's dates.

The primary product page for this flow is Check a ChatGPT itinerary. The same validation pattern also covers Gemini itineraries, Claude itineraries, and Perplexity itineraries.

Parser first, model second

The input is intentionally messy. Real travel notes look like this:

Friend texts with half-remembered restaurant names
Blog snippets copied with booking notes
Google Maps short links
ChatGPT day plans
Reddit comments
Duplicate names with different wording

The system starts with deterministic extraction. Bullets, day headings, map URLs, and common booking phrases are cheap to parse without a model.

The model step handles the ambiguous cases: vague names, mixed prose, and category cleanup. That keeps the expensive part narrow. It also gives the product a better failure mode. When the parser is certain, it stays deterministic.

I published a CC BY 4.0 public corpus for this exact shape: validatrip-public-data. It includes 54 pasted-itinerary sample cases, source markdown, a schema file, comparison data, and prompts that generate itineraries worth validating.

The JSONL file is here: ai-itinerary-validation-samples.jsonl.

The same corpus is also published as a Hugging Face dataset card: validatrip-ai-itinerary-validation-samples.

The corpus is not user data. It is not a statistical study. It is a test and demonstration set for validation behavior.

The checks

After extraction, each named place goes through a set of checks.

Resolve the place to a real venue.
Attach coordinates and neighborhood context.
Check opening hours against the trip dates.
Flag weekly closed days and seasonal closures.
Flag booking-sensitive categories.
Detect duplicates.
Separate day trips from in-city clusters.
Show everything on a map.

That means the answer to “is this a good itinerary?” becomes more specific.

The useful questions are:

Which stops are closed during the trip?
Which stops need a reservation now?
Which names failed to resolve?
Which places are duplicates?
Which stops belong together by neighborhood?

The dedicated hours page is Validate trip hours against your travel dates. The organization page is Organize travel recommendations.

Why source-cited AI still needs validation

Perplexity is a good example. It can cite a travel blog. That proves the blog exists. It does not prove the restaurant from the post is open this month.

A cited itinerary still needs current place resolution. It still needs date-aware hours. It still needs booking flags.

So the right sequence is simple:

Use an AI tool for the first pass.
Paste the result into a validator.
Replace the stops that fail live checks.
Build the final day plan from the checked list.

That is the product boundary I wanted ValidaTrip to own. It is the layer after the AI answer, before the traveler trusts it.

The public reference layer

I also keep an AI-readable reference file for the product: llms-full.txt.

It lists the main validation pages, the direct answers those pages support, the schema coverage, and the public entity signals.

The public data repo mirrors that file. That gives crawlers and researchers the same entity context outside the product domain.

The project is intentionally narrow. It does not compete with the itinerary generator. It checks the generator's output.

That narrowness is the point. Travel AI tools already produce the first draft. The missing step is the boring one: open hours, closures, booking windows, duplicates, neighborhoods, and a map that reflects the real trip dates.

I built a bingo number caller with zero backend and 331 prerecorded MP3s instead of the Web Speech API

Forrest Miller — Fri, 15 May 2026 18:07:49 +0000

A bingo caller is the machine that draws numbers, says them out loud, and shows them on a board. I needed one for BingWow, a free bingo site. The obvious build is a server that owns the deck and a SpeechSynthesis call for the voice. I shipped neither. Here is why, and what the no-backend version actually looks like.

You can play with the result here: bingwow.com/caller. It runs entirely in the tab.

The state lives in a reducer, not a server

A multiplayer bingo board needs a server, because two players must agree on who claimed what. A caller does not. One person runs it, on one screen, and reads numbers to a room. There is nothing to synchronize.

So the whole game is a useReducer:

interface CallerState {
  mode: BallMode;          // '30' | '75' | '90'
  deck: number[];          // shuffled, pop() to draw
  called: BingoBall[];
  calledSet: Set<number>;  // O(1) "was this called"
  isAutoMode: boolean;
  roundNumber: number;
}

case 'DRAW': {
  if (state.deck.length === 0) return state;
  const deck = [...state.deck];
  const num = deck.pop()!;
  return { ...state, deck, called: [...state.called, makeBall(num, state.mode)] };
}

No persistence, no API route, no database row. Refreshing the page starts a new game, which is the correct behavior for a caller anyway. The only thing that survives a reload is two booleans in localStorage: voice on/off and bingo-lingo on/off. Server cost for the entire feature is zero, and it works on a school projector with flaky wifi.

Why not the Web Speech API

speechSynthesis.speak() is free and one line. I used it first. Three problems killed it:

The voices are not the same anywhere. The available SpeechSynthesisVoice set depends on OS and browser. The default English voice on Windows Chrome, macOS Safari, and a Chromebook are three different voices with three different cadences. A caller that sounds like a calm host on my laptop sounds like a 1998 GPS on the school's machine.
It cuts off and queues badly. Rapid speak() calls during auto-draw drop utterances or stack them. Cancel/restart logic to fix that is its own bug farm.
No personality. Traditional 90-ball bingo has spoken calls — "Legs eleven", "Two fat ladies, eighty-eight". A robot monotone reading "eighty eight" is not that. The call IS the fun.

So the voice is 331 prerecorded MP3s. Every number in every mode, every milestone ("halfway", "almost done"), every traditional 90-ball nickname, welcome and round-transition lines. They are real recorded clips, consistent on every device, and they have the warmth a party game needs. The cost is a one-time generation pass and a few MB of audio served from the CDN; clips preload per mode.

The hard part: syncing voice to the animation

The drawn ball physically flies from a hero position into its cell on the flashboard. The voice has to fire at the moment the ball lands, not when React happens to re-render.

The first version triggered the audio from a useEffect keyed on the called list. It desynced constantly — the effect runs after paint, the animation impact is mid-timeline, and at fast auto-draw the gap compounds. The fix was to stop treating audio as a render side effect and fire it from the animation timeline itself, at the impact keyframe:

runFlyingBallToCell({
  /* ... */
  onAbsorbed: () => {
    setCellRevealed(true);
    voiceRef.current?.playBallImpact(ball, mode, lingoEnabled);
  },
});

playBallImpact() also cancels any in-flight banter or milestone clip so the number call never collides with "you're halfway there". Auto-draw is gated on the animation completing, not on the audio finishing — audio is fire-and-forget at impact. That one move removed every desync vector at once.

What this gets you

A bingo caller with no server, no signup, no app, that runs on anything with a browser. It does 75-ball (US), 90-ball with the recorded traditional calls, and 30-ball speed bingo. Pair it with free printable cards and the whole game costs nothing — I wrote the full no-equipment walkthrough here: Free online bingo caller guide.

The general lesson is the boring one worth repeating: not every feature that could have a backend needs one, and the platform speech API is a demo, not a product. Prerecorded audio plus a timeline that owns its own timing beat both the server and the SDK here.

Try it: bingwow.com/caller.

We Built a Compound AI System Instead of an Agent. It Costs $200/month and 100k People Use It.

Forrest Miller — Thu, 14 May 2026 14:40:45 +0000

The architecture nobody is marketing

I just wrote in The AI Journal about why our autonomous AI agent ran for six months, cost $310 in API charges, and produced zero new dofollow backlinks. The reasons generalize: Gartner predicts more than 40% of agentic AI projects will be canceled by end of 2027; McKinsey finds 73% of enterprise AI projects fail to deliver ROI; Writer reports 88% of AI agent pilots never reach production.

Berkeley AI Research named the alternative in February 2024: the Compound AI System. Either control flow is written in traditional code that calls LLMs at specific bounded steps, or control flow is driven by an LLM that decides what to do next. Compound systems pick the first. Agents pick the second.

This post is the implementation detail of the working alternative.

The six models inside BingWow

BingWow is a free AI bingo card platform used by classrooms and HR teams. Six models from four vendors handle different parts of the pipeline:

Claude Sonnet 4.5 — content quality judgment, generation
Claude Haiku 4.5 — classification: moderation, dedup, categorization
Gemini 2.5 Flash — bingo-clue generation
Gemini 3 Flash Preview + Gemini 2.5 Pro fallback — themed display names per card topic
GPT-4o Vision — background image description (accessibility, search)
Replicate Flux Schnell — background image generation

None of these models decides what happens next. Code decides.

The pipeline is code

Every transition between models is a TypeScript function, a SQL query, or a cron job. Here is the pipeline from the moment a visitor types a card topic to the moment that card is browsable on bingwow.com/cards:

// app/api/cron/process-pending-topics/route.ts (06:00 UTC daily)
export async function GET(req: NextRequest) {
  requireCron(req);
  const topics = await getPendingTopics({ limit: BATCH_SIZE });

  for (const topic of topics) {
    // Step 1: Gemini 2.5 Flash generates clues (structured-output schema)
    const clues = await generateClues(topic);

    // Step 2: SQL deduplicates against existing cards in same category
    const isDuplicate = await findSemanticDuplicate(topic.category_id, clues);
    if (isDuplicate) { await markRejected(topic.id, 'duplicate'); continue; }

    // Step 3: Claude Haiku 4.5 categorizes (validated against DB read)
    const validCategoryIds = await getSubcategories();
    const suggestedId = await classifyToCategory(topic, clues, validCategoryIds);
    if (!isValidSubcategoryId(suggestedId)) { /* fallback */ }

    // Step 4: Claude Sonnet 4.5 makes the publishability call
    const { publish } = await decidePublishability(topic, clues);
    if (!publish) { await hardDelete(topic.id); continue; }

    // Step 5: Replicate Flux Schnell generates a background (4 attempts max)
    const backgroundId = await resolveNewCardBackgroundId({ topic, clues });

    // Step 6: insert card, flip status to 'published'
    await insertCard({ topic, clues, category_id: suggestedId, backgroundId });
  }
}

Six steps. Each one a code decision. The models do bounded work between the decisions.

What this buys

Auditable cost. Every API call has a named caller in the codebase. When the April 2026 Anthropic bill spiked, I found the offender by grepping for claude-3-5-opus in lib/*.ts and replacing it with claude-haiku-4-5 in three files. The bill dropped from $560 a month to between $170 and $245. The system generates 30,000 AI bingo cards a month at that cost.

$ grep -l "claude-3-5-opus" lib/*.ts
lib/moderation-prompt.ts
lib/categorize.ts
lib/dedupe.ts
$ sed -i '' 's/claude-3-5-opus/claude-haiku-4-5/g' lib/moderation-prompt.ts lib/categorize.ts lib/dedupe.ts

An agent burns the same $560 because routing is a code decision and the agent owned the decisions.

Auditable failure. When categorization started landing in the wrong subcategory in March, the bug was in a static fallback list in the moderation prompt — not in the model's judgment. The fix was to read the subcategory list from the categories table at request time and validate the AI's returned ID against the same DB read:

// lib/moderation-prompt.ts
export async function buildModerationPrompt(topic: Topic) {
  const subcategories = await getSubcategories(); // 5-min cached DB read
  const categoryList = subcategories
    .map(c => `${c.id}: ${c.name}`)
    .join('\n');
  return `[...prompt header...]

Pick a category ID from this list:
${categoryList}

Respond with { "suggested_category_id": "<id>" }`;
}

// lib/categories.ts
export function isValidSubcategoryId(id: string): boolean {
  const subcategories = getSubcategoriesSync();
  return subcategories.some(c => c.id === id && !c.is_parent);
}

The fix is in TypeScript, not in prompt engineering, because the failure was a code failure. There is no prompt edit that can recover from a stale fallback list — the data structure has to change.

Auditable evaluation. Tests exist for code. Every API route has a test fixture that calls it with a known input and asserts on the output shape. Continuous evaluation runs on every deploy. Drift on any axis triggers a code change, not a vibes-based prompt tweak.

The bingo caller is a worked example

The BingWow caller is the most-trafficked surface in the product. It supports 30-ball, 75-ball, and 90-ball bingo with voice calls, a flashboard, auto-draw, manual draw, and printable number cards. Every layer of it is a worked example of the compound pattern:

The voice that calls each ball is one of 331 pre-recorded MP3s. The choice to ship pre-recorded audio instead of synthesizing speech at call time is a code decision — Web Speech API drifts in pacing and pronunciation; recorded audio is identical every run.
The flashboard renders 75 cells in a deterministic layout. The bingo-detection logic is TypeScript; no LLM is asked whether a row is complete.
The card-validation flow (proving that a 5-character card code corresponds to a winning board) is a single SQL query plus a deterministic reconstructCard function. No model is asked to validate; the math is the contract.

If any of those layers were handed to an LLM with the framing "you are an autonomous bingo agent," the product would be slower, more expensive, and less reliable on every dimension.

What this does not buy

A compound system does not replace the engineer who writes the orchestration code. The shape of that engineer's day changes: instead of prompt-tuning a single multi-step plan, they are writing TypeScript that calls bounded models and writing tests that pin the boundary. That work is not glamorous; it does not show up in any vendor's pitch deck. There is no margin in selling code that calls Python functions.

If your team has the resources to staff one senior engineer plus a continuous evaluation discipline, you can ship a compound system today. The model choices in this post are deliberate and replaceable — a year from now the right routing might be different — but the architecture is durable.

Receipts

BingWow — the product the stack runs
BingWow Research Portal — open-licensed engagement research generated by the same stack
State of Team Building Games 2026 — recent research output
The AI Journal — I Built an AI Agent for $310. It Failed for the Same Reason Yours Will. — the companion editorial on why agents fail
Berkeley AI Research — The Shift from Models to Compound AI Systems — the paper that named the pattern (Zaharia, Khattab, Chen et al., February 2024)

Pick the architecture. Don't pick the marketing label. The compound AI system is the architecture nobody is marketing — and that is the point.

The parser cascade pattern: extracting recipes from messy food blogs

Forrest Miller — Tue, 12 May 2026 18:03:27 +0000

Most recipe pages are not hard because the recipe is complicated. They are hard because the useful data is surrounded by everything else a publishing business needs: ads, modals, autoplay video, SEO prose, social widgets, tracking scripts, and sometimes bot protection.

For RecipeStripper, the product goal is small: paste a public recipe URL and get a clean cooking view. The implementation is not one parser. It is a cascade.

This is the pattern that has held up best in production:

Fetch the page with the cheapest reliable method.
Parse the highest-confidence structure first.
Fall back only when the previous layer cannot return enough recipe data.
Preserve failure reasons instead of pretending every site works.

Stage 0: fetching is part of parsing

Before a parser can run, the app has to get usable HTML.

RecipeStripper's fetch chain starts with a normal server-side request using browser-like headers. If a server returns a block status or a challenge-looking page, it can fall back to a headless Chromium request with a realistic user agent and a few stealth evasions. If that still returns a challenge page, the final attempt is a Wayback Machine snapshot.

That last step matters because many recipe pages expose stable structured data in archived HTML even when the live site blocks server-side fetches.

The app still does not claim universal support. Some sites, especially PerimeterX-protected properties, are marked as blocked or limited in the Works With directory.

Stage 1: JSON-LD first

Most modern recipe sites publish Schema.org Recipe data in application/ld+json scripts. That is the best path because it is already structured.

The JSON-LD parser handles a few common shapes:

// simplified from lib/parsers/jsonld.ts
const type = obj["@type"];
const isRecipe =
  type === "Recipe" ||
  (Array.isArray(type) && type.includes("Recipe"));

It also walks arrays and @graph wrappers, because SEO plugins often place the recipe object inside a graph with breadcrumbs, article metadata, and organization data.

When a page exposes more than one recipe object, RecipeStripper picks the best candidate by matching URL slug words against recipe names, then falls back to the object with the most ingredients.

Stage 2: Microdata still exists

Older sites sometimes use Microdata instead of JSON-LD:

<div itemscope itemtype="https://schema.org/Recipe">
  <h1 itemprop="name">...</h1>
  <li itemprop="recipeIngredient">...</li>
</div>

This path is less common, but it is cheap and deterministic. If a page has itemscope and itemprop recipe markup, there is no reason to call a model.

Stage 3: heuristic HTML parsing

When structured data is missing, the parser looks for recipe-shaped HTML.

The heuristic parser searches for known recipe containers, then uses section headings and list patterns:

headings like "Ingredients", "Instructions", "Directions", or "Method"
ingredient-looking lines that begin with quantities and units
ordered or unordered lists inside recipe-like containers
common WordPress recipe plugin selectors

This is not as clean as Schema.org data, but it catches a lot of hand-built pages and older blogs.

The important guardrail is to accept partial confidence without over-trusting it. RecipeStripper filters out non-instruction junk such as nutrition lines, star-rating prompts, social calls to action, and promotional fragments.

Stage 4: model fallback, not model first

The GPT-4o-mini fallback only runs when deterministic parsers fail or return a recipe missing ingredients or instructions.

That keeps cost and latency under control, and it avoids turning every request into a hallucination risk. The model receives a cleaned text window, not raw page HTML, and is instructed to return structured JSON or { "found": false }.

The useful rule: models are better as recovery layers than as the first parser.

The second cascade: ingredient-to-step matching

Extraction alone still leaves the classic cookbook layout: ingredients at the top, instructions below.

RecipeStripper's differentiator is inline quantity embedding. After extraction, a matcher links ingredient names to instruction steps. When it is confident, the rendered step can show the quantity where the cook needs it:

"fold in the flour" becomes "fold in 2 cups all-purpose flour"

The internal representation uses a small token format:

{qty:ingredientId:display text}

That lets the renderer highlight matched quantities and lets the servings scaler update both the ingredient list and the inline step amounts.

Why this pattern works

A cascade has three practical advantages:

It keeps fast paths fast. JSON-LD extraction is usually enough.
It keeps fallbacks honest. A blocked site becomes a clear blocked-site error, not a mysterious empty recipe.
It lets the product improve one layer at a time. Better JSON-LD handling, better heuristics, and better matching all compound.

The current public research dataset is here: Recipe Site Markup Coverage and Extraction Observations 2026. It includes the public site inventory plus anonymized domain-level extraction observations. No submitted recipe URLs or user identifiers are included.

The browser workflow is also being split into smaller surfaces: a bookmarklet and a downloadable Chrome extension package. Both simply open the current recipe URL in the clean reader. They do not inject a widget into someone else's site.

The broader lesson is portable: when the web is inconsistent, build a parser cascade. Put the most trustworthy structure first, keep each fallback narrow, and make failures explicit.

Same Engine, Two Frames: Privacy Art vs Prank Tool

Forrest Miller — Tue, 12 May 2026 17:32:06 +0000

I built one mechanism and gave it two doors.

One door is pleasejuststop.org. It looks like a privacy art project because that is what it is. You paste a public photo. The app makes fake face twins. The recipient sees a serious-looking AI product, then the reveal shows what happened.

The other door is prankmyface.lol. It is the same engine with a different promise: send your friend a link that looks real and wait for the moment they realize it was a setup.

That split matters. The privacy framing gives the project its ethical spine. The prank framing gives it motion.

Why the serious version exists

The serious version starts from a simple question: if a website showed you your own face without asking you for a photo, would you stop and ask how it got there?

Most people do not.

That reaction is the project. Public photos already get scraped, indexed, copied, and processed. The experience compresses that reality into a minute. A sender adds a photo that was already public. The recipient sees their face inside a product they never used. The reveal shows the source.

No database of real strangers is involved. No permanent biometric record is created. The point is that the fake product feels plausible because the real world already trained people to accept it.

Why the prank version exists

The prank version works because people share jokes faster than arguments.

Someone who would never send an essay about facial recognition will absolutely send a link that makes a friend say, "wait, how did this thing find my face?"

That is not a compromise. It is the delivery system.

The prank surface does not pretend to the sender. It tells the sender exactly what they are doing. Paste the photo. Make the link. Send it. The deception only happens inside the recipient flow, where the whole experience depends on that short moment of belief before the reveal.

The product difference is mostly tone

Under the hood, both doors use the same flow:

Accept a photo from the sender.
Generate three altered face variants.
Degrade the outputs so they look like real internet photos, not polished AI portraits.
Show the recipient a fake face-twin product.
Burn the link after reveal.
Ask the recipient if they want to send it to someone else.

The copy, color, and reveal tone change around that flow.

The privacy art version is black, sparse, and confrontational. It wants the recipient to sit with the discomfort.

The prank version is hotter, faster, and more social. It wants the recipient to laugh, screenshot, and send it onward.

Same engine. Different social context.

What I changed for the viral loop

The reveal is the important screen. It is where the recipient learns what happened, and it is also where the next sender is born.

So the share path now carries attribution. Links copied from the sender screen and reveal screen include campaign parameters that identify whether the chain came from the original sender, the reveal CTA, a copy action, native share, or a social share.

That makes the chain measurable without collecting victim PII.

I also added a public Prank Hall of Fame. It shows anonymous reveal reactions after basic PII scrubbing. The archive is not there to shame anyone. It is there because the reaction is the product's best ad.

Someone saying "I knew it was fake but still clicked" explains the experience better than a landing page ever could.

The rule I will not break

The tool only works socially.

If a random account sends a prank link to a stranger, the experience becomes harassment. It also becomes spam. The correct distribution move is not to prank strangers. It is to put the tool in front of people who will decide, voluntarily, to send it to someone they know.

That is the boundary:

Public posts about the tool are fine.
Friends pranking friends are fine.
Cold-sending generated prank links to strangers is out.

The prank has to come from a real relationship or the whole thing turns sour.

The bet

The privacy audience will understand why the project exists. The prank audience will actually spread it.

Those are not competing goals. The prank version gets the experience into group chats. The privacy version explains why the experience is worth taking seriously after the laugh lands.

The chain starts at prankmyface.lol. The argument lives at pleasejuststop.org.

One Playwright Header Broke Every WebSocket Test

Forrest Miller — Tue, 12 May 2026 17:07:43 +0000

The failing tests looked like an Ably outage.

Every multiplayer browser test on BingWow started timing out at the same gate: "wait until the realtime channel attaches." The app loaded. The room existed. The players joined. Then the WebSocket layer never became ready.

The root cause was not Ably. It was one Playwright config line.

extraHTTPHeaders: {
  'X-BingWow-Automated': '1',
}

That header was supposed to mark test traffic as internal. Instead, it leaked to every cross-origin request the browser made.

Why this broke realtime

Playwright's extraHTTPHeaders is global for the browser context. It does not apply only to requests headed for your app. It applies to third-party calls too.

In this app, a multiplayer room talks to:

bingwow.com for HTML and API routes
Ably for realtime channels
Supabase for auth and storage paths
analytics endpoints for product events

The custom X-BingWow-Automated header is not CORS-safelisted. When the browser tried to call Ably with that header, it triggered a preflight request. Ably did not whitelist our private test header. The preflight failed. The actual realtime request never happened.

From the test's point of view, Ably simply never attached.

The misleading symptom

The app code was doing the right thing:

await page.waitForFunction(() => window.__ably_channel_ready === true);

The wait timed out after two minutes. That made the problem look like:

a flaky WebSocket connection
a race in the join flow
a broken token endpoint
a headless browser limitation

All of those were plausible. None were true.

The header never showed up in the app's own logs as an error because the failing request was cross-origin. The damage happened before Ably's actual attach request could complete.

The fix: use a cookie, not a global header

We still needed to mark test traffic so it would not pollute analytics or product metrics. The replacement was a domain-scoped cookie:

storageState: {
  cookies: [{
    name: 'bingwow_dev',
    value: '1',
    domain: '.bingwow.com',
    path: '/',
    expires: -1,
    httpOnly: false,
    secure: true,
    sameSite: 'Lax',
  }],
  origins: [],
}

That cookie is sent only to BingWow-owned requests. It never goes to Ably, Supabase, or other third-party origins. The app can still identify internal traffic on its own API routes, and the browser no longer poisons external requests with private headers.

For real-time multiplayer games, this difference matters. The transport stack has to be boring. A test harness that changes cross-origin network behavior is not observing the product anymore. It is creating a second product.

The structural lint

The fix needed a guardrail because the broken line is easy to reintroduce. We added a Jest test that scans Playwright config files for extraHTTPHeaders and fails if a non-allowlisted header appears.

The error message explains why:

extraHTTPHeaders is GLOBAL - it applies to every browser request,
including cross-origin calls to ably.io, posthog, supabase, etc.
Custom non-CORS-safelisted headers trigger preflight failures and
silently break those services.

This is not a style preference. It is a production-shaped invariant for browser tests.

Why headless detection is still useful

The app also skips internal analytics for obvious automation signals:

navigator.webdriver
HeadlessChrome user agents
a server-side bot detector
the bingwow_dev=1 cookie

Those checks are safe because they do not alter third-party request headers. They change only how the app classifies traffic after it receives a request.

That distinction is the key lesson: mark traffic where you own the request, not by mutating every request the browser makes.

How I debug this class now

When a browser test involving third-party services fails, I check these first:

Does the Playwright context set global headers?
Are those headers CORS-safelisted?
Do failed requests show OPTIONS preflight before the real call?
Does the same flow pass with a clean context plus app-domain cookies?

Most teams only notice this once they add a service that enforces CORS strictly. WebSockets, analytics, file storage, maps, payments, and auth providers all expose the same trap.

The visible feature in my case was a simple bingo card room. The underlying bug was a general browser automation footgun.

If you need internal test classification, prefer these patterns:

App-domain cookies through storageState
server-side bot detection
test-only query params on your own origin
init scripts that set app-local flags without touching network headers

Avoid global headers unless every origin the browser contacts is under your control.

The same rule now protects the multiplayer flow, the online bingo caller, and the internal QA suite. Tests should make the product easier to trust. They should not create network conditions real users never hit.

That one-line Playwright config was doing exactly that, and deleting it made the test suite both greener and more honest.

For a deeper product-level view of the architecture this affected, I wrote up the broader system in the real-time multiplayer bingo guide.

The Atomic Tap RPC That Keeps a Multiplayer Bingo Board Honest

Forrest Miller — Tue, 12 May 2026 17:07:42 +0000

Real-time games have a habit of turning simple UI events into distributed systems problems. A player taps a cell. Another tab reconnects. A stale WebSocket event arrives from the previous round. The user taps again before the first request finishes. If the server treats those as independent "claim" and "unclaim" commands, the board can drift.

I ran into this while building BingWow, a browser-based multiplayer bingo game. The product looks simple: every player has a board, taps squares, and wins by completing a row. The data model behind that simple interaction has to answer one question perfectly: after this tap, which clue ids are currently claimed by this player in this round?

The bug-prone version

The first version had separate endpoints:

POST /api/game/claim
POST /api/game/unclaim

That matched the UI state. If a square looked unclaimed, the client called claim. If it looked claimed, the client called unclaim.

The problem is that the client is not the source of truth. It can be stale by one render, one optimistic update, or one reconnect. A double tap could send two claim requests. A delayed Ably event could make the square look claimed when the database had already undone it. The API shape made illegal states easy to express.

One tap, one server decision

The fix was to collapse the command surface into a single action:

POST /api/game/tap

The endpoint does not accept "claim" or "unclaim" from the browser. It accepts only room_id, player_id, and clue_id. The database decides what the tap means inside one locked transaction.

The core RPC shape is:

SELECT * INTO v_room
FROM rooms
WHERE id = p_room_id
FOR UPDATE;

SELECT id INTO v_existing_claim_id
FROM claims
WHERE room_id = p_room_id
  AND player_id = p_player_id
  AND clue_id = p_clue_id
  AND round_number = v_room.current_round
  AND undone = false
LIMIT 1;

IF v_existing_claim_id IS NOT NULL THEN
  UPDATE claims
  SET undone = true, undone_at = NOW()
  WHERE id = v_existing_claim_id;
  v_action := 'unclaimed';
ELSE
  INSERT INTO claims (room_id, clue_id, player_id, round_number, undone)
  VALUES (p_room_id, p_clue_id, p_player_id, v_room.current_round, false)
  RETURNING id INTO v_claim_id;
  v_action := 'claimed';
END IF;

The browser no longer tells the server what state it thinks the cell is in. The database reads the current claim row and toggles it.

The response returns the whole active set

The RPC returns the complete active claim set for that player and round:

SELECT COALESCE(array_agg(clue_id), ARRAY[]::TEXT[])
INTO v_claimed_clue_ids
FROM claims
WHERE room_id = p_room_id
  AND player_id = p_player_id
  AND round_number = v_room.current_round
  AND undone = false;

That one detail matters. The API response is not just "your tap worked." It is "here is the authoritative set now." The client can replace local state instead of trying to patch from a possibly stale starting point.

On the server, the same response drives the bingo check for multiplayer bingo. The endpoint maps the player's board into positions, marks the returned clue ids as claimed, and runs a shared row-completion detector. There is no separate SQL bingo loop that can drift from the browser's single-player detector.

Round number is part of the key

The active claim uniqueness constraint includes round_number. That prevents old taps and stale events from contaminating the next round. A claim from round 1 is still auditable, but it is not active in round 2.

That rule pairs with the WebSocket side. Realtime events include the round number, and subscribers ignore events from older rounds. This is the difference between a pleasant bingo card game and a board that appears to resurrect old cells after the next round starts.

Derive grid size from the board

Another small cleanup made the RPC safer: it derives grid_size from board length instead of reading a separate column.

SQRT(jsonb_array_length(v_player.board))::INT

The board has 9, 16, or 25 cells, so the grid is 3x3, 4x4, or 5x5. Duplicating that value in a column created drift bugs. Deriving it inside the RPC means the server's win check uses the actual board the player has.

That is especially important because BingWow deliberately clamps mobile players to a smaller board while desktop players can use larger ones. The rule is product behavior, not presentation. It belongs on the server.

What this buys you

The final shape is boring in the best way:

The client sends one command: tap this clue.
The database locks the room and player.
The database toggles the active claim row.
The database returns the full active claim set.
The server checks bingo from that authoritative set.
The browser publishes realtime events after the HTTP response succeeds.

For a simple party game like online bingo calling, that may look overbuilt. It is not. The visible product is casual, but the failure mode is embarrassing: a player taps a square, the UI says one thing, and the server believes another.

The lesson I keep relearning is that multiplayer game commands should describe user intent, not presumed state. "Tap this square" is intent. "Claim this square" is a guess.

When your API accepts guesses, stale clients become data corruption machines. When the server owns the transition, the UI can be optimistic without being authoritative.

The same principle applies outside games. Shopping carts, kanban cards, calendar RSVPs, feature toggles - anywhere the user can flip state from multiple tabs or devices. Give the server the minimum intent, lock the row that owns the invariant, and return the new truth.

That is the pattern behind BingWow's real-time multiplayer bingo architecture, and it has held up far better than the two-endpoint version I started with.

Instagram Wipes localStorage on Navigation. Here's How We Keep Multiplayer Sessions Alive.

Forrest Miller — Tue, 12 May 2026 15:05:03 +0000

Instagram Wipes localStorage on Navigation. Here's How We Keep Multiplayer Sessions Alive.

A teacher shares a bingo game link to her class group chat. Half the students open it in Instagram's in-app browser. They tap a cell, switch to check a notification, come back. Their game session is gone. They're staring at a fresh board with none of their claims.

This happened in production on BingWow within the first week of launch.

The root cause

Instagram, TikTok, Snapchat, and Facebook Messenger all use in-app WebView browsers. These are not Safari or Chrome. They're stripped-down renderers with restrictions that vary by platform and OS version.

The critical one: some WebViews clear localStorage on navigation events. Not every time. Not on every device. But often enough that "store session in localStorage" is a broken architecture for any app where users arrive via social media links.

Our game sessions stored the player ID, room code, and display name in localStorage. When the WebView cleared it, the server couldn't match the returning player to their board. The player re-entered as a new anonymous participant.

The dual-write pattern

The fix is writing to both localStorage and sessionStorage on every save, and reading from localStorage first with sessionStorage as the fallback:

// lib/safe-storage.ts

export function dualGet(key: string): string | null {
  if (typeof window === 'undefined') return null;
  try {
    return localStorage.getItem(key) ?? sessionStorage.getItem(key);
  } catch {
    try { return sessionStorage.getItem(key); } catch { return null; }
  }
}

export function dualSet(key: string, value: string): void {
  try { localStorage.setItem(key, value); } catch {}
  try { sessionStorage.setItem(key, value); } catch {}
}

export function dualRemove(key: string): void {
  try { localStorage.removeItem(key); } catch {}
  try { sessionStorage.removeItem(key); } catch {}
}

sessionStorage survives the scenarios where localStorage gets wiped. It's scoped to the tab's lifetime, which in a WebView means "until the user closes the in-app browser or force-quits the app." For a bingo game that lasts 10-30 minutes, tab lifetime is plenty.

Why every operation is wrapped in try/catch

Safari Private Browsing mode throws a QuotaExceededError on any setItem call. The storage quota is zero bytes. Older Samsung Internet builds throw on getItem if storage was disabled in settings. Some enterprise MDM-managed Chromebooks throw SecurityError on storage access entirely.

The try/catch blocks are not defensive programming paranoia. They're the result of real crash reports from real users on real devices.

The priority order: localStorage write → sessionStorage write → silent failure. A failed write is better than a crashed game. If both writes fail, the player gets a new session on refresh — annoying but playable. If the code throws, the game is bricked.

Per-room namespaced keys

A separate pattern that interacts with the dual-write: every session key includes the room code:

// lib/session.ts

export function saveSession(data: {
  player_id: string;
  room_code: string;
  room_id: string;
  display_name: string;
  is_host: boolean | string;
}): void {
  dualSet(`bingwow_session_${data.room_code}`, JSON.stringify({
    playerId: data.player_id,
    roomId: data.room_id,
    roomCode: data.room_code,
    displayName: data.display_name,
    isHost: data.is_host === true || data.is_host === 'true',
  }));
}

The key is bingwow_session_ABCD where ABCD is the four-character room code. If a player has two games open in different tabs (it happens during testing), each tab's session is independent. No cross-contamination.

This namespacing also prevents the stale-session bug: without it, a player who joins Room A, then Room B, then returns to Room A's tab finds Room B's credentials in bingwow_session and sends taps to the wrong room.

When NOT to dual-write

Not everything needs the sessionStorage mirror. We keep two tiers:

// localOnly — single-tab data, no resilience needed
export function localGet(key: string): string | null { ... }
export function localSet(key: string, value: string): void { ... }

// dual — cross-navigation data, WebView-resilient
export function dualGet(key: string): string | null { ... }
export function dualSet(key: string, value: string): void { ... }

The edit buffer (unsaved changes while creating a card) uses localOnly. If the buffer is lost, the user re-types a few words. The game session (player identity in a live multiplayer room) uses dual. If the session is lost, the player loses all their claims and has to rejoin as a stranger.

The distinction matters because sessionStorage is per-tab. The edit buffer should persist across tabs (start editing on your phone, finish on your laptop). The game session should NOT persist across tabs (two tabs with the same session = two players fighting over one identity).

Measuring the fix

Before the dual-write: ~8% of Instagram-referred sessions ended with a "session lost" recovery flow within the first 5 minutes. After: <1%. The remaining 1% is genuine cold starts (user closed the in-app browser entirely and re-opened the link).

The pattern works because sessionStorage survival guarantees are stronger than localStorage across the specific set of WebViews our users arrive from. This could change — if TikTok's WebView starts clearing sessionStorage too, we'd need to move to URL-parameter session tokens. But for now, dual-write catches 87% of the drops that single-write missed.

The code above is production code from BingWow, a free multiplayer bingo platform. Try it: pick any card from bingwow.com/cards, share the link with a friend, and play. The session management described here runs on every game — whether it's a classroom activity at bingwow.com/for/teachers or a watch party opened from an Instagram story.

If you're building anything that users reach via social media links, test in at least Instagram's and TikTok's in-app browsers. localStorage is not as reliable as the MDN docs imply.

Why Our Multiplayer Bingo Game Uses a Singleton Ably Client (and Token Auth Instead of API Keys)

Forrest Miller — Tue, 12 May 2026 15:05:02 +0000

Why Our Multiplayer Bingo Game Uses a Singleton Ably Client (and Token Auth Instead of API Keys)

When you're building real-time multiplayer in Next.js, the first architectural question isn't "which WebSocket library." It's "how many connections am I going to accidentally open."

The problem: connection sprawl

BingWow is a free multiplayer bingo platform. Every player in a room subscribes to an Ably channel. When someone taps a cell, claims bingo, or sends a chat message, every other player sees it in real time.

The naive approach — instantiate new Ably.Realtime() in every hook that needs it — creates a connection per hook per render. A single player page has at minimum three hooks subscribing: game subscriptions, chat, and the activity feed. Three connections per player. Twenty players in a room is sixty WebSocket connections for one game. Ably bills per connection.

The singleton pattern

The fix is a module-level singleton. One connection per browser tab, shared across every hook:

// lib/ably.ts
import Ably from 'ably';

let realtimeClient: Ably.Realtime | null = null;

export function getAblyClient(): Ably.Realtime {
  if (typeof window === 'undefined') {
    throw new Error('getAblyClient can only be called on the client side');
  }

  if (!realtimeClient) {
    const clientId = `client-${Date.now()}`;
    realtimeClient = new Ably.Realtime({
      authUrl: '/api/ably/token',
      authMethod: 'GET',
      authParams: { clientId },
      clientId,
      closeOnUnload: false,
      transports: ['web_socket', 'xhr_polling'],
      logLevel: 0,
    });
  }

  return realtimeClient;
}

Every hook calls getAblyClient(). The first call creates the connection. Every subsequent call returns the same instance. When the tab closes, one connection drops.

Why token auth, not the publishable API key

Ably offers two client authentication modes. The quick one — passing key directly — exposes your Ably API key in client-side JavaScript. Anyone who opens DevTools can read it. Ably's docs say this is fine for prototyping. For a production multiplayer game with arbitrary players, it is not fine.

Token auth routes through your server:

// app/api/ably/token/route.ts
import Ably from 'ably';
import { NextResponse } from 'next/server';

export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const clientId = searchParams.get('clientId') || `anon-${Date.now()}`;

  const ably = new Ably.Rest({ key: process.env.ABLY_API_KEY! });
  const token = await ably.auth.createTokenRequest({
    clientId,
    capability: { '*': ['subscribe', 'publish'] },
  });

  return NextResponse.json(token);
}

The client's authUrl points at this endpoint. Ably's SDK handles the token lifecycle automatically — requests a new token before the current one expires, reconnects transparently. Zero token-management code on the client.

The server-side split

Client hooks subscribe. Server API routes publish. These are different Ably client types for a reason.

The browser uses Ably.Realtime (WebSocket, persistent connection, subscribe + publish). The server uses Ably.Rest (HTTP, stateless, publish only). Both are singletons at module scope:

// Server-side REST client (publish from API routes)
let restClient: Ably.Rest | null = null;

export function getAblyRestClient(): Ably.Rest {
  if (!restClient) {
    restClient = new Ably.Rest({ key: process.env.ABLY_API_KEY! });
  }
  return restClient;
}

On Vercel, the REST client lives in the function's warm cache. Cold starts create a new one. Warm invocations reuse it. Ably REST calls are stateless HTTP — no connection to manage, no cleanup needed.

The channel-name convention

Every room gets one channel: room:${roomCode}. All event types — claims, bingos, joins, renames, chat — flow through the same channel with different event names:

export function getRoomChannel(roomCode: string) {
  return getAblyClient().channels.get(`room:${roomCode}`);
}

The hooks that subscribe to this channel filter by event name:

// In useGameSubscriptions
channel.subscribe('claim', handleClaim);
channel.subscribe('bingo', handleBingo);

// In useChat
channel.subscribe('chat', handleChat);

One channel per room means one subscription management point. When a player leaves, one channel.detach() cleans everything up.

What `closeOnUnload: false` does

This was counterintuitive until I saw it in production. Setting closeOnUnload: false tells Ably not to close the WebSocket on beforeunload. Why would you want that?

Mobile browsers. When a phone user switches to another app and comes back, beforeunload fires on the tab switch. With closeOnUnload: true, the connection drops and the player misses events during the app switch. With false, Ably holds the connection for a grace period and the player catches up on return via Ably's automatic message replay.

For a bingo game where rounds last 2-5 minutes and players routinely check their phone mid-game, this is the difference between "the game broke" and "I missed a few taps but caught up."

The transport fallback

transports: ['web_socket', 'xhr_polling'],

WebSocket first, long-polling fallback. School Chromebooks running behind restrictive proxies sometimes block WebSocket upgrades. The xhr_polling fallback ensures the game still works — slower, but functional. We discovered this when three teachers in the same district reported "the game loads but nobody else's taps appear." The Chromebook proxy was stripping the Upgrade: websocket header.

Metrics

Before the singleton: ~3 Ably connections per player per room. After: 1. For a 20-player room, that's 60 → 20 connections. At Ably's pricing tiers, the singleton pattern cut our real-time infrastructure cost by two-thirds with zero behavior change.

The token auth pattern added ~50ms to the initial connection (one extra round-trip to /api/ably/token). After that, token renewal is transparent and adds zero latency to message delivery.

If you're building a game or any real-time feature with Ably and Next.js, start with the singleton + token auth pattern. The alternative — multiple connections with a publishable key — works until it doesn't, and "doesn't" usually means a surprise bill or a security incident.

BingWow is free and open for multiplayer games at bingwow.com. Create a card at bingwow.com/create, share the room code, and play. The Ably architecture described above runs every game session — from classroom activities at bingwow.com/for/teachers to watch parties and team-building events.

Inline style attributes vs CSS variables: a Tailwind v4 light-mode debug story

Forrest Miller — Mon, 11 May 2026 18:06:40 +0000

TL;DR: I shipped a "light mode for the bingo caller" feature three times. Each attempt rendered as dark navy squares on a white stage — totally unreadable. The bug was the same every time: an inline style={{ background: hue.deep }} in a React component winning over the CSS class meant to control the background. Moving from inline styles to inline CSS custom properties unlocked a theme-aware cascade and finally made the feature ship.

The setup

I'm building a number bingo caller — the screen that flashes numbers across a board as they're called. Each column has a hue (Blue B, Red I, Green N, Orange G, Purple O). When a number is "called," that cell lights up in its column's color.

Dark mode shipped first. The visual goal: each called tile is a solid deep block — navy, crimson, forest, pumpkin, royal purple. Looks like a Las Vegas bingo board lit from inside. The implementation was the obvious one:

<button
  className="caller-tile caller-tile-called"
  style={{ background: hue.deep }}  // ← the bug, but I didn't know yet
>
  {num}
</button>

Worked great. Shipped.

The light-mode regression

Six weeks later I tried to add light mode. Visual goal: each called tile becomes a vibrant gradient lit from above — the same hue but the light end of its range, not the dark end. Think a bright pop instead of a moody glow.

I wrote the CSS:

.caller-tile-called {
  /* Light mode: linear gradient from highlight to mid */
  background: linear-gradient(180deg, var(--hue-highlight) 0%, var(--hue-mid) 100%);
}

.dark .caller-tile-called {
  /* Dark mode: solid deep */
  background: var(--hue-deep);
}

Set the CSS variables on each cell:

<button
  className="caller-tile caller-tile-called"
  style={{
    background: hue.deep,           // ← still here
    '--hue-highlight': hue.highlight,
    '--hue-mid': hue.mid,
    '--hue-deep': hue.deep,
  }}
>
  {num}
</button>

Reloaded the page in light mode. Dark navy squares. Crimson. Forest green. On a stark white stage.

I tried a few "make it work" patches. Increased CSS specificity. Wrapped the rule in :where(.light). Added !important. Nothing worked. The inline style={{ background: hue.deep }} was winning over my CSS rule every time.

I reverted the attempt and stayed in dark mode for another four weeks.

The two more attempts that broke the same way

Each time I came back to it I came up with a new theory:

Attempt 2: rewrite the CSS to target both .light .caller-tile-called and :not(.dark) .caller-tile-called. Same bug. Inline style still won.
Attempt 3: rewrite Flashboard to compute the gradient inline and conditionally render it. Forced me to thread theme state through three layers of React just to set a background: value. Also looked horrible because the inline gradient didn't get the var() indirection I wanted for component-internal tweaks.

After the third attempt I sat back and read the CSS specification on declared styles carefully.

Inline style attributes have higher specificity than ANY external stylesheet rule, including !important rules in stylesheets (unless the inline style is also !important). My background: var(--hue-deep) was authoring an inline declaration that simply couldn't lose. Every CSS rule I wrote was a bystander.

The fix was straightforward once I saw it: stop authoring background: in JSX entirely. Move the value into a CSS variable that the stylesheet picks up.

The shape that finally shipped

<button
  className="caller-tile caller-tile-called"
  style={{
    '--hue-highlight': hue.highlight,
    '--hue-mid': hue.mid,
    '--hue-deep': hue.deep,
    '--hue-glow': hue.glow,
  } as CSSProperties}
>
  {num}
</button>

.caller-tile-called {
  background: linear-gradient(180deg, var(--hue-highlight) 0%, var(--hue-mid) 100%);
  border-color: var(--hue-mid);
}

.dark .caller-tile-called {
  background: var(--hue-deep);
  border-color: var(--hue-mid);
}

The inline style now only sets CUSTOM PROPERTIES. Custom properties don't paint anything — they're just named values. The CSS rule consumes them and decides what to paint, and the CSS rule can switch between light and dark cases because it's the only thing actually authoring background:.

Light mode: gradient. Dark mode: solid deep. Both branches share the same hue palette. Switching theme is one class flip on <html>.

What I'd do differently from day one

I should have known this. I've answered Stack Overflow questions on inline-style specificity. The reason I missed it in my own code is that inline style={{ ... }} in React is so culturally adjacent to "just set the prop" that I didn't think of it as authoring a CSS declaration. It read as data, not as a stylesheet author.

The general rule I now keep on a sticky note: inline style should set values, not paint properties. CSS custom properties on the element are fine — they're values. Hex colors on background or color are dangerous — they're paint commands that no stylesheet can dethrone.

A side benefit

Once the hues were CSS variables instead of inline backgrounds, I could expose them to other parts of the component for free. The cell's box-shadow glow uses the same variables. The current-cell pulse animation uses --hue-glow. The ghost-number outline uses color-mix(in srgb, var(--hue-mid) 25%, transparent). Adding a new effect doesn't require touching React state — just touching the stylesheet.

Try It

Live in production — both modes work:

See the caller light mode: bingwow.com/caller (toggle theme in the navbar)
Create a multiplayer card: bingwow.com/create
Browse cards: bingwow.com/cards
Free, no signup, no premium tier: bingwow.com

If you've hit the same wall with theming a React component, I'd love to hear the route you took. Drop it in the comments.

DEV Community: Forrest Miller

How we built real-time multiplayer bingo for 20 players per room on Next.js 16, Ably, and Supabase

1. One unified tap event, not separate claim/unclaim

2. Per-player boards, not a shared board

3. Server-authoritative round transitions

4. player-joined over Ably presence

5. The SP/MP boundary

Stack — minimal pieces, opinionated wiring

The under-rated win

Building an AI face-doppelganger prank with Flux Kontext Pro and aggressive image degradation

The visual goal: real internet photos, not AI portraits

The three prompts (verbatim from production)

The rules these prompts were built against

The six degradation profiles

Sharp hangs silently on Vercel — use Jimp, but only three of its methods

Three more pitfalls that cost me a day each

Why I published the dataset

How I built an itinerary validator for AI travel plans

The failure mode

Parser first, model second

The checks

Why source-cited AI still needs validation

The public reference layer

I built a bingo number caller with zero backend and 331 prerecorded MP3s instead of the Web Speech API

The state lives in a reducer, not a server

Why not the Web Speech API

The hard part: syncing voice to the animation

What this gets you

We Built a Compound AI System Instead of an Agent. It Costs $200/month and 100k People Use It.

The architecture nobody is marketing

The six models inside BingWow

The pipeline is code

What this buys

The bingo caller is a worked example

What this does not buy

Receipts

The parser cascade pattern: extracting recipes from messy food blogs

Stage 0: fetching is part of parsing

Stage 1: JSON-LD first

Stage 2: Microdata still exists

Stage 3: heuristic HTML parsing

Stage 4: model fallback, not model first

The second cascade: ingredient-to-step matching

Why this pattern works

Same Engine, Two Frames: Privacy Art vs Prank Tool

Why the serious version exists

Why the prank version exists

The product difference is mostly tone

What I changed for the viral loop

The rule I will not break

The bet

One Playwright Header Broke Every WebSocket Test

Why this broke realtime

The misleading symptom

The fix: use a cookie, not a global header

The structural lint

Why headless detection is still useful

How I debug this class now

The Atomic Tap RPC That Keeps a Multiplayer Bingo Board Honest

The bug-prone version

One tap, one server decision

The response returns the whole active set

Round number is part of the key

Derive grid size from the board

What this buys you

Instagram Wipes localStorage on Navigation. Here's How We Keep Multiplayer Sessions Alive.

Instagram Wipes localStorage on Navigation. Here's How We Keep Multiplayer Sessions Alive.

The root cause

The dual-write pattern

Why every operation is wrapped in try/catch

Per-room namespaced keys

When NOT to dual-write

Measuring the fix

Why Our Multiplayer Bingo Game Uses a Singleton Ably Client (and Token Auth Instead of API Keys)

Why Our Multiplayer Bingo Game Uses a Singleton Ably Client (and Token Auth Instead of API Keys)

The problem: connection sprawl

The singleton pattern

Why token auth, not the publishable API key

The server-side split

The channel-name convention

1. One unified `tap` event, not separate claim/unclaim

4. `player-joined` over Ably presence

What `closeOnUnload: false` does