Blur and Spotlight reveals

Status: Production
Source: 7 files · web 7
web
lib/challenges/blur-reveal.ts
routes/challenges/blur/BlurChallenge.svelte
routes/challenges/blur/BlurFlagHero.svelte
routes/challenges/spotlight/SpotlightChallenge.svelte
routes/challenges/spotlight/SpotlightFlagCanvas.svelte
lib/challenges/ElementsClickProtection.svelte
lib/challenges/touch-interaction-guard.ts
Verified: 2026-09-27 against master

1. Foundational mental model

Blur and Spotlight are two ways of rationing information about one flag. Both routes (/challenges/blur, /challenges/spotlight) pick a target with pickRandomCountry() from gameCountries, give the player 5 guesses through CountrySearch, and reveal more of the flag as the round goes on.

Blur reveals by time: every wrong guess lowers a CSS blur() radius and a grayscale() percentage. The player spends guesses to buy sharpness.
Spotlight reveals by place: the flag sits under a black canvas, and each tap erases a circle. The player spends moves (a separate budget from guesses) to buy area.

Blur: a guess changes one number, and the hero swaps filter snapshots instead of animating the filter.

Spotlight: a pointerdown either reveals a circle, shakes the frame, or does nothing.

2. Implementation status & known gaps

Active today: Blur uses the four constants in BLUR_REVEAL and MAX_GUESSES = 5. The filter never animates; BlurFlagHero crossfades between two static filter layers for 500 ms, and snaps when the reduce-motion class is on <html>.
Active today: Spotlight draws a 600×400 canvas with hard-edged destination-out circles. Radii and move caps are 50 px / 15, 25 px / 10, 22 px / 3 for Easy, Medium, Hard.
Known gap: both modes ship the unobscured flag to the browser. Blur’s <img> is sharp under a CSS filter; Spotlight’s <img> sits under the canvas. Removing the filter or hiding the canvas in DevTools shows the answer. See §5.
Known gap: results are client-reported. Both routes use xpPolicy: "none" and send a best-effort postSideChallengeCompletionBestEffort call; nothing replays or verifies the round.
Known gap: Spotlight computes a per-guess score (100 − (index + 1) · 15) and passes it to ChallengeResults, but no component reads GuessStat.score today. It is dead data.

3. Concrete implementation

Blur schedule

The whole schedule is one pure function:

export const BLUR_REVEAL = {
  initialBlurPx: 26,
  blurReducePerGuess: 5,
  initialGrayscale: 100,
  grayscaleReducePerGuess: 17,
} as const;

export function blurRevealAtGuessIndex(guessIndex: number): BlurRevealFilter {
  return {
    blurPx: Math.max(
      0,
      BLUR_REVEAL.initialBlurPx - guessIndex * BLUR_REVEAL.blurReducePerGuess
    ),
    grayscale: Math.max(
      0,
      BLUR_REVEAL.initialGrayscale - guessIndex * BLUR_REVEAL.grayscaleReducePerGuess
    ),
  };
}

BlurChallenge.svelte feeds it the guess count and forces both values to 0 once the round ends, win or lose:

const guessCount = $derived(guesses.length);
const blurAmount = $derived(
  isCompleted ? 0 : blurRevealAtGuessIndex(guessCount).blurPx
);
const grayscaleAmount = $derived(
  isCompleted ? 0 : blurRevealAtGuessIndex(guessCount).grayscale
);

Snapshot crossfade in BlurFlagHero

BlurFlagHero never transitions filter. It keeps the current filter in snapshotBlur. When the props change, it copies the old snapshot to outgoingBlur, applies the new filter to the base layer immediately, and lets a second layer with the old filter fade out:

function beginRevealCrossfade(from: BlurFilterSnapshot, to: BlurFilterSnapshot) {
  clearRevealFadeTimer();
  outgoingBlur = from;
  snapshotBlur = to;
  revealOutgoingKey += 1;
  revealFadeTimer = setTimeout(() => {
    revealFadeTimer = undefined;
    outgoingBlur = null;
  }, BLUR_REVEAL_CROSSFADE_MS);
}

The outgoing layer is keyed by revealOutgoingKey, so a fast second guess restarts the fade from the latest snapshot instead of stacking layers. A new round (gameRoundId changes) resets snapshotBlur with no fade. The layer’s only animation is opacity:

{#if outgoingBlur}
  {#key revealOutgoingKey}
    <div
      class="blur-flag-reveal-outgoing pointer-events-none absolute inset-0 z-1 flex items-center justify-center p-2 sm:p-4 isolate"
      style:filter={filterStyle(outgoingBlur)}
      style:--blur-reveal-ms="{BLUR_REVEAL_CROSSFADE_MS}ms"
      style:--blur-reveal-easing={BLUR_REVEAL_EASING}
      aria-hidden="true"
    >

Both layers live inside a contain-[paint] wrapper, and the hero sits inside ElementsClickProtection without allowInteraction, which adds a transparent z-50 overlay plus contextmenu, dragstart, and selectstart blockers. That stops “Save image as” and long-press callouts on the sharp source image. It does nothing about DevTools.

Interactive

Blur reveal frame-time benchmark

Steps the same flag through the production blur schedule two ways and samples requestAnimationFrame deltas for each. Strategies run one after the other so they do not share frames.

Flag

Production schedule blurRevealAtGuessIndex()

0 guesses 26px 100%
1 guess 21px 83%
2 guesses 16px 66%
3 guesses 11px 49%
4 guesses 6px 32%
Solved 0px 0%

Spotlight difficulty table

const DIFFICULTY_SETTINGS = {
  easy: { name: "Easy", radius: 50, maxMoves: 15 },
  medium: { name: "Medium", radius: 25, maxMoves: 10 },
  hard: { name: "Hard", radius: 22, maxMoves: 3 },
} as const satisfies Record<DifficultyLevel, DifficultyConfig>;

Changing difficulty starts a new game (onSelect calls startNewGame). The default is medium.

Canvas mask

The canvas is 600×400 in its own coordinate space and stretched to the 3:2 frame with CSS. Every render repaints the whole mask: fill black, clip to the flag’s letterboxed rectangle, erase one circle per reveal, then stroke a faint outline:

ctx.clearRect(0, 0, w, h);
repaintBase(ctx, w, h);

if (activeReveals.length > 0) {
  ctx.save();
  if (rect) {
    ctx.beginPath();
    ctx.rect(rect.x, rect.y, rect.w, rect.h);
    ctx.clip();
  }

  ctx.globalCompositeOperation = "destination-out";
  for (const point of activeReveals) {
    ctx.beginPath();
    ctx.arc(point.x, point.y, radius, 0, Math.PI * 2);
    ctx.fill();
  }

The fill is a solid color, so each hole has a hard edge. There is no radial gradient or feathering. The flag itself is a plain <img> behind the canvas (z-0, canvas at z-2), and a black div covers it until the first render sets isMaskBufferPrimed.

Click rejection

const liveFlagRect = getLiveFlagRect(canvas);
if (!isPointInsideRect({ x: clickX, y: clickY }, liveFlagRect)) {
  onInvalidClick();
  return;
}

const isTooClose = reveals.some(
  (point) =>
    Math.sqrt((point.x - clickX) ** 2 + (point.y - clickY) ** 2) < revealRadius / 2
);

if (!isTooClose) {
  onReveal({ x: clickX, y: clickY });
}

A click outside the flag shakes the frame and costs nothing. A click whose center is closer than $r/2$ to any earlier reveal is dropped with no feedback and costs nothing. Everything else spends one move.

Per-guess score

guesses={guesses.map((guess, index) => ({
  code: guess.code,
  score: guess.code === tc.code ? 100 : Math.max(0, 100 - (index + 1) * 15),
  status: guess.code === tc.code ? "correct" : "incorrect",
}))}

Wrong guesses at positions 1 to 5 would score 85, 70, 55, 40, 25. As noted in §2, nothing downstream reads this field. The result screen shows moves used, guesses, and difficulty instead.

4. Internal mechanics & mathematics

Blur schedule

For $n$ wrong guesses so far, with $B_0 = 26$ , $\Delta_B = 5$ , $G_0 = 100$ , $\Delta_G = 17$ :

b(n) = \max(0,\; B_0 - n\,\Delta_B), \qquad g(n) = \max(0,\; G_0 - n\,\Delta_G)

The round ends after 5 guesses, so play only ever sees $n \in \{0, 1, 2, 3, 4\}$ :

Wrong guesses $n$	0	1	2	3	4	Round over
`blur` (px)	26	21	16	11	6	0
`grayscale` (%)	100	83	66	49	32	0
Visibility badge	0%	20%	40%	60%	80%	100%

The max(0, …) floor never fires in play: blur would first go negative at $n = 6$ , grayscale at $n = 6$ too. The last hint the player sees is still a 6 px blur at 32% grayscale. The badge is $\min(100, n / 5 \cdot 100)$ , a guess counter with a percent sign, and it does not measure perceived sharpness.

Why a crossfade

With strategy A (transition: filter), every frame of the 500 ms transition has a different blur radius, so the engine must re-run the blur over the whole layer on each frame. CSS blur(σ) is a Gaussian with standard deviation σ; how expensive one pass is depends on the engine (separable kernels, box-blur approximations, downsampling), but the work repeats roughly 30 times at 60 Hz.

With strategy B, neither layer’s filter changes during the fade. The only animated property is the outgoing layer’s opacity, which browsers can hand to the compositor. At worst the engine re-runs two fixed blurs per frame; when it caches the filtered layers, it only blends two textures. The on-screen result during the fade is a blend,

C(t) \approx \alpha(t)\, \mathrm{Blur}_{b_\text{old}} + \big(1 - \alpha(t)\big)\, \mathrm{Blur}_{b_\text{new}}, \qquad \alpha: 1 \to 0

where A would show $\mathrm{Blur}_{b(t)}$ for intermediate radii. At a 5 px step between two already-soft images the difference is hard to see. The code comment on BLUR_REVEAL_CROSSFADE_MS states the intent; the benchmark above lets you measure it on your own hardware, and the result will vary.

Spotlight coordinates and flag rectangle

Pointer positions map to canvas units independently of display size:

x = \frac{\text{clientX} - \text{left}}{\text{width}} \cdot 600, \qquad y = \frac{\text{clientY} - \text{top}}{\text{height}} \cdot 400

So radius, rejection distance, and coverage are all resolution-independent. On a 390 px phone the 25-unit Medium radius is about 16 CSS px on screen, but it covers the same fraction of the flag as on desktop.

The flag is letterboxed with object-contain. For image aspect $a = w/h$ , getFlagRectForImage returns $600 \times 600/a$ when $a > 1.5$ and $400a \times 400$ otherwise, centered. Reveals are clipped to that rectangle $F$ .

Coverage

After $k$ reveals at centers $p_1, \ldots, p_k$ with radius $r$ , the visible area is

A_k = \Big|\, F \cap \bigcup_{i=1}^{k} D(p_i, r) \Big|

Upper bound: $A_k \le \min\big(|F|,\; k\pi r^2\big)$ , reached only when no two disks overlap and none crosses the edge of $F$ . Lower bound for $k \ge 1$ : every center lies inside $F$ , so at least a quarter disk is visible, $A_k \ge \pi r^2 / 4$ (when both sides of $F$ are at least $r$ ).

The rejection rule makes centers pairwise at least $r/2$ apart. Two disks at the minimum distance $d = r/2$ overlap in a lens of area

L(d) = 2r^2 \arccos\!\frac{d}{2r} - \frac{d}{2}\sqrt{4r^2 - d^2} \;\approx\; 2.152\,r^2 \quad (d = r/2)

so the second disk adds only $\pi r^2 - 2.152 r^2 \approx 0.99 r^2$ , about 31% of a fresh disk. The rule stops free duplicate taps; it does not stop wasteful ones.

For a 3:2 flag, $|F| = 600 \times 400 = 240{,}000$ units², and the best case is:

Difficulty	$r$	Moves $k$	$\pi r^2$	One disk / $\lvert F \rvert$	Max coverage $k\pi r^2 / \lvert F \rvert$
Easy	50	15	7,854	3.27%	49.1%
Medium	25	10	1,963	0.82%	8.2%
Hard	22	3	1,521	0.63%	1.9%

Flags that letterbox to a smaller rectangle raise the fraction. A square flag such as Switzerland letterboxes to 400×400 (160,000 units²), so Easy tops out at 73.6%. Hard differs from Medium mostly in its 3-move cap; the radius only shrinks from 25 to 22.

5. Threat model, failure modes & edge cases

What stands between a curious player and the answer.

Sharp source in the DOM. Blur applies CSS filters to a normal FlagImage; Spotlight draws a canvas over a normal <img>. Either is one DevTools toggle from the answer. The flag URL is opaque (see Opaque flag tokens), hideCountryInAlt keeps the Blur alt text at “Flag”, and Spotlight sets alt="Flag" until the round ends. The target is picked client-side, so the answer is also in memory.
No server check. These are side challenges with no XP. Completion goes to a local record (recordChallengeCompletionLocally), a product analytics event, and a fire-and-forget POST. Cheating changes nothing shared.
Rapid Blur guesses. A second guess inside 500 ms clears the timer and keys a new outgoing layer from the current snapshot, so at most two filter layers exist.
Reduced motion. prefersReducedMotion() reads the reduce-motion class on <html> (driven by the app’s motion setting), not the media query directly. With it on, Blur snaps, the fog intro is skipped, and the reveal flash is hidden.
Spotlight image load. Until the <img> is decodable, the canvas has pointer-events-none and the handler returns early. SVG flags count as loaded even when naturalWidth is 0, because flagImageReady checks isSvgFlagUrl.
Silent rejections. A too-close tap gives no feedback at all. The hover preview (mouse and pen only; touch skips pointermove) shows a dashed circle, but touch players get nothing until a tap lands.
Flag rect lookup. getLiveFlagRect queries img[alt^='Flag of'], which only matches after the round ends. During play it falls back to the bound imageRef, which is the same element, so the result is unchanged.
Snapshots in results. Each guess stores captureSnapshot(), a 600×400 WebP data URL at quality 0.5 composed from the image and the mask. The <img> has crossorigin="anonymous" so the offscreen canvas stays untainted. If the CDN stopped sending CORS headers, the image would fail to load; the error listener still marks it loaded, so the round would play over an empty frame.

6. Architectural tradeoffs & non-goals

Choice	Alternative	Why the code does this
Crossfade static filter snapshots	`transition: filter`	Opacity animates without re-running the blur each frame. The cost is a blend of two blur levels during the fade instead of a true continuous deblur.
Linear schedule, 5 px and 17% per guess	Perceptual curve (for example, equal steps in recognizability)	Simple, predictable, easy to share as “revealed 60%”. The first steps from 26 px barely help on flags with large color fields.
Hard-edged `destination-out` circles	Radial gradient or feathered mask	Players can see exactly what they paid for, and the stroke outline marks each hole.
Canvas mask over an `<img>`	Draw the flag into the canvas	Keeps the opaque CDN image path and browser decoding; the canvas holds only the mask. The flag stays in the DOM, which is the main cheat vector.
Silent drop within $r/2$	Shake, or spend the move anyway	Avoids punishing double taps on touch screens. Players get no signal that the tap was ignored.
Moves separate from guesses	One shared budget	Lets Hard be a 3-tap puzzle while keeping 5 guesses across all difficulties.

Non-goals: hiding the flag from someone with DevTools open, verifying results server-side, and awarding XP for these modes. The opaque URL and click protection only defeat casual inspection.