DEV Community: Forrest Miller

Date-Scoped Travel Pages Turned Into ValidaTrip’s First Unbranded Search Wedge

Forrest Miller — Tue, 02 Jun 2026 12:57:04 +0000

On June 2, 2026, I pulled fresh Search Console data for ValidaTrip.

The site had 319 clicks and 11,459 impressions across the prior 28 days. Visible unbranded query rows accounted for 40 clicks and 1,493 impressions.

That mattered because the prior baseline was branded-only.

The first unbranded wedge was not a generic AI travel term. It was date-scoped city event search.

Queries like “madrid events july 2026” and “stockholm events july 2026” sent clicks. That is small, but it is real.

The pages receiving that demand were built as city-month surfaces, not blog posts.

Examples:

The implementation point is simple. Travel search has a date dimension that generic itinerary pages often ignore.

A traveler does not only ask for “things to do in Madrid.” They ask what is happening while they are there.

That changes the content shape.

A useful travel page needs the destination, the month, the event window, and the itinerary context. It also needs a reason to exist beyond a list.

ValidaTrip already checks trip plans against opening hours, closures, holidays, bookings, neighborhoods, and maps.

The city-month pages connect that checker to demand that already has dates baked in.

The product flow is:

A traveler searches for events in a city and month.
They land on a date-scoped city page.
They see relevant events, attractions, and trip timing context.
They paste their own plan into the trip-hours validator.
They catch closed places, booking-sensitive stops, and missed event windows before the trip.

The same surface supports AI travel checks.

ChatGPT can write a plausible travel plan without knowing live hours. It can also miss a festival that overlaps the exact trip.

The ChatGPT itinerary checker handles the post-AI reality check.

The missed events and festivals guide explains the event problem directly.

The public AI citation layer mirrors that answer in llms-full.txt. That file gives AI search systems canonical wording and canonical URLs.

The ranking lesson is not “publish more pages.”

It is “publish pages where a specific traveler intent already includes a city, date, and action.”

For ValidaTrip, that intent is not abstract.

It is:

What events are in this city during my trip?
Is this place open when I arrive?
Does this AI itinerary work on real dates?
Can I turn these notes into a checked map?

Those questions map to pages with a clear job.

The traffic is early. The mechanism is visible now.

Search Console showed unbranded clicks after the site exposed city-month event pages with clean URLs and crawlable content.

That is the surface I am doubling down on.

I Built a Free Bingo Caller Board With 331 Audio Clips and No Backend

Forrest Miller — Tue, 02 Jun 2026 12:28:40 +0000

A bingo caller board has four jobs: draw a number without repeats, say it out loud, mark it on a flashboard, and leave enough history on screen to check a winner. I built that as a browser-only feature for BingWow, because the room already has one host and one screen. There is no shared state worth sending to a server.

The live version is here: bingwow.com/caller. It supports 75-ball, 90-ball, and 30-ball speed bingo, with voice calls and a fullscreen board for a TV or projector.

The caller is local state

A multiplayer bingo game needs a server because every player has an independent board and every tap needs authority. A standalone caller does not. One host runs it. The output is public in the room. Refreshing starts a new game, which is normal for a caller.

The main state is a reducer:

interface CallerState {
  mode: BallMode;          // '30' | '75' | '90'
  deck: number[];          // shuffled, pop() to draw
  called: BingoBall[];
  calledSet: Set<number>;  // O(1) caller-board lookup
  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)],
  };
}

The caller sends no request when a number is drawn. The deck is shuffled in the tab, the flashboard reads the called set, and the auto-call timer advances only after the current animation has completed.

Why I skipped the Web Speech API

speechSynthesis.speak() looked like the cheap answer. It failed the product test.

The available voices differ by OS and browser. A calm voice on a Mac became a different voice on a Chromebook. Rapid calls also queued badly during auto-call, and traditional 90-ball nicknames sounded flat when a browser voice read them.

The shipped caller uses 331 prerecorded MP3s instead:

number calls for 30, 75, and 90-ball games
every traditional 90-ball nickname, from "Legs eleven" to "Two fat ladies"
welcome, pause, progress, and round-transition clips
short clips that fit between visual calls at faster speeds

That makes the 90-ball bingo caller sound the same in a classroom, a senior center, a church hall, or a browser tab on a TV.

The flashboard is the product

Most users describe the same surface as a bingo caller board, bingo calling board, or flashboard. The code treats it as a pure display component: it does not own the game; it only renders the current mode and called numbers.

75-ball uses B-I-N-G-O columns. 90-ball and 30-ball use number ranges. The shared caller component seeds the mode from the route:

// /caller defaults to 75-ball
<CallerClient />

// /caller/90-ball
<CallerClient initialMode="90" />

// /caller/30-ball
<CallerClient initialMode="30" />

That gave each mode its own indexable page while keeping one caller implementation. The 90-ball page also includes an interactive list of all 90 traditional calls, built from the same audio manifest used by the caller.

Audio fires from the animation timeline

The drawn ball flies into its cell on the flashboard. The number needs to be spoken at impact, not when React finishes rendering. The first implementation keyed audio from a state effect, and it drifted during auto-call.

The fix was to fire audio from the animation callback:

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

The timeline owns timing, the reducer owns state, and the flashboard stays a pure read model. That split kept manual draw, auto-call, voice mute, and fullscreen mode from fighting each other.

Printing completes the offline game

A free caller alone is only half a bingo night. Players still need cards. The 75-ball caller has a Print Cards flow that generates up to 500 unique cards with validation codes. The support guide is here: Free online bingo caller, and the card printer is here: bingwow.com/print.

The practical setup is simple:

Open the free caller board.
Print cards or hand out existing tickets.
Use fullscreen on a TV or projector.
Start manual draw or auto-call.
Check the winner against the call history.

Try the caller

75-ball caller board: bingwow.com/caller
90-ball UK caller: bingwow.com/caller/90-ball
30-ball speed caller: bingwow.com/caller/30-ball
No-equipment host guide: free online bingo caller
Bingo night guide: how to host bingo night

Six layers to canonicalize 'FiDi', 'Wall Street area', and 'Lower Manhattan' as one neighborhood

Forrest Miller — Mon, 01 Jun 2026 02:10:33 +0000

The problem

A user pastes their travel list into our travel-paste validator. They got recs from a friend, a blog, an AI itinerary, and a Reddit thread. The list mentions Lower Manhattan four ways:

"FiDi"
"Wall Street area"
"Financial District NYC"
"Lower Manhattan financial district"

Our Neighborhoods tab groups by area so users can plan a day at a time. Without canonicalization, those four labels become four area cards with one place each. The user can't tell that they're looking at one walkable district. The product looks broken.

This is a small example. The full surface across 145 cities is thousands of variants per city — formal vs informal, English vs local, Wikipedia title vs administrative subdivision, polygon-level granularity vs guidebook vocabulary. Solving it in one pass with a single API or a single LLM call is the obvious wrong answer.

We solved it in six layers. Each layer covers a class of variants the next layer can't see.

Layer 1: spatial reverse-geocode

When a validated item has (lat, lng), the polygon-based name overrides whatever text label the upstream Google Places match returned.

// lib/providers/places/spatial-reverse.ts
const r = await fetchAddressDescriptors(lat, lng, GOOGLE_GEOCODING_API_KEY);
const areas = r?.addressDescriptors?.areas ?? [];

// areas are returned smallest-to-largest with WITHIN / NEAR / OUTSKIRTS
// take the smallest WITHIN — the most specific containing area
return areas.find((a) => a.containment === 'WITHIN')?.displayName?.text ?? null;

If Google's call fails, we fall through to Mapbox v6 reverse with types=neighborhood,locality,place. Result is cached per rounded-coord (4 decimal places, ~10 m precision) so adjacent items in the same neighborhood share a single billable call.

This collapses the trivial split: two items that physically sit inside Tribeca will both come back labeled "Tribeca", even if one was pasted as "near the Holland Tunnel exit" and the other as "by the Mysterious Bookshop."

Layer 2: bulk alias mining via Gemini

The spatial pass handles items with coordinates. About 2.5% of real-world pastes have no coordinates because the title alone failed to match any place ("our friend's apartment in BoCoCa", "the Marais restaurant Maya recommended"). For those, we lean on a per-city alias dictionary.

We mined the dictionary once with a single Gemini 2.5 Flash call per city:

// scripts/places/mine-aliases-gemini.mjs
const prompt = `For each canonical neighborhood in ${city}, list the
informal abbreviations, prefix-stripped forms, article variations,
multilingual transliterations, and common misspellings real travelers use.

Return strict JSON: { "<canonical>": ["alias1", "alias2", ...] }

Canonical list:
${canonicalEntries.join("\n")}`;

We tried this against the Wikidata Action API first. The anon wbsearchentities + wbgetentities flow rate-limits at roughly 1 request per second with 11-second Retry-After headers under load. At ~75K canonical entries with ~4 fetches each, the wall-clock cost is days.

The Gemini call returns aliases for an entire city in one shot with hallucination guards: a returned alias is dropped if it matches another canonical entry in the same city (those are distinct neighborhoods), and aliases containing "X and Y" are dropped when the canonical doesn't (catches "Camden Town and Regent's Park" pseudo-combinations).

Result: FiDi → Financial District. DUMBO → Down Under the Manhattan Bridge Overpass. Le Marais → Marais. La Roma → Roma. 渋谷 → Shibuya. The 4-spelling NYC FiDi example collapses at this layer.

Layer 3: Overture Maps polygon point-in-polygon

Spatial reverse-geocode handles coords. The alias dictionary handles labels. Neither handles the case where a Google Places result returns the right polygon but at the wrong level of administrative granularity.

NYC is the canonical example. Overture's NYC neighborhood polygons are at Community Board granularity. CB 5 covers Midtown East, Midtown West, AND Murray Hill — three guidebook neighborhoods folded into one admin zone. If we wrote the polygon's raw name to the item, the user would see a "Manhattan Community Board 5" area card instead of the three distinct neighborhoods they care about.

We pre-bake the polygons once per release with DuckDB against Overture's S3:

duckdb -c "
  COPY (
    SELECT id, names.primary AS name, subtype, bbox, geometry
    FROM read_parquet('s3://overturemaps-us-west-2/release/2026-05-20.0/theme=divisions/type=division_area/*')
    WHERE subtype IN ('neighborhood','microhood','macrohood','borough','localadmin')
      AND ST_Intersects(geometry, ST_GeomFromText('${cityBbox}'))
  ) TO 'polygons-${slug}.geo.json' (FORMAT 'GeoJSON');
"

At validate time, we lazy-load the city's .geo.json, build a flatbush R-tree from pre-computed bboxes, run @turf/boolean-point-in-polygon to find every enclosing polygon, and pick the most specific one by subtype rank:

const SUBTYPE_RANK: Record<string, number> = {
  microhood: 0,
  neighborhood: 1,
  macrohood: 2,
  borough: 3,
  localadmin: 4,
};

Per-city "too-coarse" skip patterns prevent the granularity downgrade. NYC skips Community Board names so the LLM resolver (Layer 5) keeps its more specific guess. London skips borough names like "City of Westminster" because that single borough covers Mayfair / Soho / Marylebone / Covent Garden / Westminster / St James's — six guidebook neighborhoods. Mexico City skips the 13 alcaldía names.

The skip list is per-name, not per-subtype, because Overture occasionally labels admin areas at the neighborhood subtype.

Layer 4: POI gazetteer (Wikidata-derived)

Some titles are famous enough that the title itself tells you the neighborhood. "Whitney Museum of American Art" implies Meatpacking District. "Tate Modern" implies South Bank. We mined a per-city (title → neighborhood) gazetteer from Wikidata SPARQL:

SELECT ?poi ?poiLabel ?neighborhood ?neighborhoodLabel WHERE {
  VALUES ?landmarkType { wd:Q33506 wd:Q1244442 wd:Q12876 wd:Q35112 wd:Q860861 }
  ?poi wdt:P31/wdt:P279* ?landmarkType .
  ?poi wdt:P131 ?neighborhood .
  { ?neighborhood wdt:P131 wd:${cityQid} }
    UNION
  { ?neighborhood wdt:P131 ?parent . ?parent wdt:P131 wd:${cityQid} }
  FILTER NOT EXISTS { ?poi wdt:P576 ?dissolved }
  SERVICE wikibase:label { bd:serviceParam wikibase:language "en" }
}

That gives us roughly 8,600 entries across 15 cities. Lookup is foldKey-exact only (we tried substring matching once — 14 of 23 hits on a live Paris audit were false positives, so exact-only is the conservative choice). The gazetteer file is module-cached after first load.

This catches the long tail Layer 3 polygons can't catch: a paste that says "Whitney" with no coordinates and no neighborhood label resolves to Meatpacking District because the gazetteer recognizes the abbreviation.

Layer 5: per-trip LLM canonical resolver

After the four deterministic layers, some labels still don't match. "Historic center of Mexico City", "Colonia Centro", "Centro Histórico", and "Centro" all describe the same neighborhood but the alias dictionary only had three of them.

The fifth layer runs ONE gpt-4o-mini call per trip that maps every distinct raw label to the canonical guidebook name:

// lib/validation/resolve-canonical-neighborhoods.ts
const prompt = `Map each raw label to the closest canonical neighborhood in ${city}.

If a label doesn't clearly match any canonical entry, return it unchanged.
Don't guess across cities. Don't invent new canonical names.

Canonical: ${canonicalNames.join(", ")}
Raw labels in this trip: ${rawNeighborhoods.join(", ")}

Return JSON: { "<raw>": "<canonical or raw>", ... }`;

Two defensive filters at the boundary: the response is filtered against Set(rawNeighborhoods) AND Set(canonicalNames). Any hallucinated key that isn't in the input set is dropped silently. Any value that isn't in the canonical set is dropped silently. The LLM can never hand the database a name we didn't ask about.

One call per trip, not per item. A 30-item trip costs the same as a 3-item trip. Latency is amortized into the existing validate step, which already takes 8 seconds.

If OPENAI_API_KEY is missing or the call fails, the layer is a no-op. The four deterministic layers above are sufficient for the common cases; the LLM is a long-tail backstop.

Layer 6: per-city consolidation maps

After all five layers, polygon-real names sometimes still aren't the guidebook canonical. Overture subdivides Polanco into "Polanco 3ª Sección", "Polanco 4ª Sección", "Polanco 5ª Sección". Paris arrondissements arrive in 50+ surface forms ("14th arrondissement of Paris", "Paris 14e Arrondissement", "14th Arrondissement").

A small per-city map collapses each polygon-real subdivision into the guidebook canonical via foldKey lookup:

export const CANONICAL_CONSOLIDATIONS: Record<string, Record<string, string>> = {
  'mexico city|MX': {
    'polanco 3a seccion': 'Polanco',
    'polanco 4a seccion': 'Polanco',
    'polanco 5a seccion': 'Polanco',
    morelos: 'Centro Histórico',
    guerrero: 'Centro Histórico',
    buenavista: 'Centro Histórico',
    // 30+ more
  },
  'paris|FR': {
    '14th arrondissement of paris': '14th Arrondissement',
    'paris 14e arrondissement': '14th Arrondissement',
    // 48+ more arrondissement variants
  },
};

When a new polygon raw name appears in verify-pass-d that should fold to an existing canonical, the fix is to add it here, not to teach the LLM to handle it stochastically.

Why six layers, and not one LLM call

A single LLM call would work for any individual case. It would also cost more per validate, take longer, hallucinate occasionally, and degrade silently when the model drifts between releases.

Each deterministic layer handles a class of variants the cheaper and more stable way:

Layer	Strength	Cost
1. Spatial reverse-geocode	Exact answer when coords exist	~1 Geocoding API call per unique coord
2. Gemini alias mining	Handles label-only no-coord cases	Mined ONCE per city, $0 per validate
3. Overture polygon PIP	Handles weird Google Places labels	Lazy-load + R-tree, no API call
4. POI gazetteer	Famous landmarks by title alone	foldKey-exact lookup, no API call
5. LLM canonical resolver	Long-tail rephrasings	One `gpt-4o-mini` call per trip
6. Consolidation map	Polygon-real → guidebook canonical	Static map lookup

The LLM is layer five, not layer one, because by the time we reach it, 95% of the labels have been resolved deterministically. The remaining 5% are exactly the cases where its strength — pattern-matching across spellings — matters most.

That same logic applies to most "the data is messy" problems in travel software. Real pastes are heterogeneous because real users are heterogeneous. A London trip has Tube-stop names, Wikipedia titles, blog rephrasings, and Reddit short-hand all in the same paste. The cheapest path to a clean Neighborhoods tab is to peel the layers in order: geometry first, dictionaries second, structured catalogs third, LLM last.

If you want to see the result, paste anything messy into a new trip and open the Neighborhoods tab. The canonicalization runs on every validate. The full canonical guidebook lives at our destinations page if you want to see what we're matching against, or check a ChatGPT itinerary if you want to see the same pipeline applied to LLM-generated travel plans.

1,071 of our 1,190 moderation-queue cards were test pollution. Here's the 5-layer fix.

Forrest Miller — Mon, 01 Jun 2026 02:10:12 +0000

The bug we shipped twice

Our test fixtures leaked into production. Twice.

The first leak was visible. 117 QA cards reached /cards/education/science because their titles looked enough like real cards to slip past the title-pattern heuristic our public surfaces used. We cleaned them up in May.

The second leak was invisible until I audited the moderation queue last week. 1,071 of 1,190 cards waiting for human review were automation pollution — Playwright fixtures, a QA 65678 test account, timestamped runs named PW Test, Security Test, Mobile PW, plus high-volume anon seeds like Road Trip Bingo (×217) and Test Merged Create (×128). They had been queued up for the AI moderator as if a human had submitted them.

Neither leak was a bug in any single code path. The bug was that "is this a test row?" was a guess every consumer made on its own. So I wrote down the rule once and enforced it five ways.

This is the playbook, with the actual Postgres + TypeScript that runs in BingWow.

Why "is this a test row?" is hard

Test fixtures look exactly like real records. They use the same INSERT path. They carry the same shape. The only difference is intent: a human typed one, a Playwright spec typed the other.

Pre-2026, our public surfaces filtered tests with title heuristics — strings like QA test card or [playwright] were dropped at query time. That worked until a Shiplight test forgot to include the magic substring. Then the row was indistinguishable.

The fix Stripe shipped is the canonical reference: every record carries a livemode boolean set at INSERT time by whichever code path created it. Public surfaces filter on it; analytics segment by it; cleanup automates on it.

We needed the same shape, expanded to an enum-of-strings because we have more origins than test/prod.

Layer 1: the origin column (NOT NULL + CHECK)

ALTER TABLE card_templates
  ADD COLUMN origin text NOT NULL DEFAULT 'legacy_unknown';

ALTER TABLE card_templates
  ADD CONSTRAINT card_templates_origin_check
  CHECK (origin IN ('ai', 'user', 'admin', 'test'));

Four values. ai is the cron pipeline that invents brand-new cards from trending topics. user is everything a human submits at our create page. admin is hand-curated. test is every automation row.

Why text + CHECK instead of a native ENUM: ALTER TYPE … ADD VALUE acquires ACCESS EXCLUSIVE on every table using the type, which blocks writes during the migration. text + CHECK uses SHARE UPDATE EXCLUSIVE. Concurrent writes still work, the validation is the same.

After backfill, the column is the discriminator the codebase had been faking. creator_id IS NULL previously conflated AI cards with anonymous human cards (anonymous users have null creator_id too — that conflation broke moderation for months before we caught it).

Layer 2: the Postgres CHECK that makes the bad state impossible

ALTER TABLE card_templates
  ADD CONSTRAINT card_templates_no_published_test_origin
  CHECK (NOT (origin = 'test' AND status = 'published'));

This is the load-bearing line.

Any INSERT or UPDATE that would set origin='test' AND status='published' returns 23514 check_violation. Postgres refuses the write. The application code doesn't get a chance to do the wrong thing.

Application-level guards are necessary but not sufficient. A direct service-role write from a test fixture bypasses every TypeScript type-check. A future contributor who copy-pastes a working INSERT block from another file inherits whatever assumptions that file made. The database constraint is the only thing every write path passes through.

Layer 3: `isTestTraffic()` at every INSERT site

export function isTestTraffic(
  request: Request,
  body?: { is_automated?: boolean },
  userId?: string | null,
): boolean {
  if (body?.is_automated === true) return true;
  if (isInternalRequest(request, userId)) return true;

  // THE rule. Real user iff bingwow_anon_id cookie present.
  const cookie = request.headers.get('cookie') ?? '';
  return !/(^|;\s*)bingwow_anon_id=/.test(cookie);
}

Three card-creation routes call this on every POST: card creation, fork-and-start, and clone. The origin is computed at the row's birth — isTestTraffic(request, body, userId) ? 'test' : 'user' — and written into the same INSERT.

The cookie rule is the strongest signal. Every real visitor's first GET sets bingwow_anon_id. Playwright contexts launch without it. Headless Chrome and CDP-stealth fingerprints stay caught even when scripts try to set is_automated: false.

For forks of forks of forks, a small helper propagates the tag:

function deriveForkOrigin(parentOrigin: string): string {
  return parentOrigin === 'test' ? 'test' : 'user';
}

So an organic-looking fork tree rooted in a test card stays origin='test' all the way down. When the cleanup cron reaps the root, the whole tree goes with it.

Layer 4: the daily cleanup cron

// app/api/cron/cleanup-test-cards/route.ts
const { error } = await supabase
  .from('card_templates')
  .delete()
  .eq('origin', 'test')
  .lt('created_at', sevenDaysAgo);

It runs at 06:00 UTC every day. It only ever touches origin='test' rows older than seven days. A user-submitted card with origin='user' is never even considered, no matter how thin or how recently submitted, because a user's saved work is sacred.

The CHECK from Layer 2 means a test row can never have status='published', so the cleanup never deletes a publicly-indexed page. We sidestep the entire class of "the cleanup cron took down a popular card" incident.

Layer 5: the CI lint that catches the next mistake

// __tests__/test-fixtures-marked.test.ts
const FIXTURE_DIRS = ['shiplight-tests', 'e2e'];

it('every card_templates POST in test fixtures includes origin: test', () => {
  for (const file of allTestFiles(FIXTURE_DIRS)) {
    const text = readFileSync(file, 'utf-8');
    if (text.includes('card_templates') && /POST|insert\(/.test(text)) {
      expect(text, file).toMatch(/origin:\s*['"]test['"]/);
    }
  }
});

The runtime layers catch a malicious or careless write. The lint catches the next test author who forgets the rule before their PR even gets reviewed.

This was the missing piece. Test files bypass /api/templates/create — they POST directly with a service-role key, so the TypeScript types don't cover them. The lint is what closes that hole.

What the rule looks like once you write it down

A row is a test row iff it was created by automation.
Test rows MAY exist in the database.
Test rows MUST NOT be public.
Test rows ARE deleted after 7 days.

Five layers because each layer enforces one of those clauses in a place the others can't reach:

Clause	Layer
Test rows MAY exist	`card_templates.origin` column (NOT NULL + CHECK)
Test rows MUST NOT be public	`card_templates_no_published_test_origin` CHECK
Created by automation = tagged	`isTestTraffic(request, body, userId)` at every INSERT
The tag propagates	`deriveForkOrigin(parent.origin)` on every fork
New code obeys the rule	`__tests__/test-fixtures-marked.test.ts` CI lint

Drop any one of those and the leak comes back through whatever hole that layer was covering. The CHECK without isTestTraffic means tests are unrestricted because nothing tags them. isTestTraffic without the CHECK means a single buggy UPDATE statement can flip a tagged row to status='published'. The cleanup cron without the propagation rule reaps the parent but orphans the forks.

The lint is the layer that ships next month, because the others stop existing failures and the lint stops the failure that hasn't been written yet.

What changed for users

Nothing visible. The product on the play surface looks identical.

What changed is that I stopped writing post-mortems about test data on production. The 2026-05-07 leak was the second one. After Layer 2 shipped, there were zero.

A structural defense is the only kind that scales. Be-more-careful does not scale; documentation does not scale; code review does not scale to every junior contributor's first PR. A Postgres CHECK scales to every write your application will ever make, including the ones written by the contributor who hasn't been hired yet.

If you have a _test table or a dev_mode boolean nobody is sure does anything, you have the same gap we did. The 2-line Stripe-style CHECK is the fastest cleanup you will ever ship.

Architecture details: our research page has the longer write-ups. The product is a free multiplayer bingo game; the source pattern above runs against every card that lands in our database.

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.