Make scoring predictable and explain each game's rules

AGENTS.md

@@ -8,3 +8,9 @@
 - Use touch-friendly targets and gestures, accessible labels, and keyboard alternatives where relevant. Do not rely on hover for essential functionality.
 - Provide functional fallbacks when enhanced browser features are unavailable.
 - Validate changes at a realistic mobile viewport first, then check larger screens. Preserve a player's progress when applying appearance changes.
+
+## Scoring policy
+
+- New games use linear closeness: `round(100 * clamp(1 - error / zeroPointBound, 0, 1))`. Tune the game's error measure and bound; do not add a power curve.
+- Score independent dimensions separately and average their closeness before rounding. Opposing errors must not cancel.
+- Freeze scoring versions on questions and gate daily changes by challenge date. Preserve historical questions, saved results, and earned scores.

README.md

@@ -37,6 +37,7 @@ Free. No login. No downloads. No sound needed.
 ## Your daily little reality check
 
 - **One shared Daily Five.** Five different puzzle types, determined by your device’s date. Players on the same date get the same challenge.
+- **One scoring rule.** New practice rounds and daily games from October 16 use linear scoring: halfway to the game’s zero-point error bound earns 50 points. Earlier games retain their original scores.
 - **Close counts.** Every round is worth 100 points. See your guess and the target together, then inspect small comparisons in your final results.
 - **Compare with friends.** Share your Daily Five results as a compact scorecard with the date, puzzle emojis, and your total. No answer spoilers.
 - **Practice when you feel like it.** Open the game menu, then Practice, for a fresh mix or an individual skill. Trivia practice draws from past Daily Fives, keeping upcoming questions out of the pool.

docs/GAME-SHELL.md

@@ -148,3 +148,13 @@ keep scoring and saved question data independent from display text. Optional
 registry `label` overrides a game name consistently in prompts and summary cards.
 Run `node tests/browser-results.cjs` to check exact/opposing size errors, long
 values, source disclosures, and summaries in both themes on small phones.
+
+New scored games follow the linear scoring policy in `docs/MAINTENANCE.md`. Use
+the shared conversion in `scoring.js`; configure the error measure and zero-point
+bound. Do not introduce a game-specific power curve. Preserve unversioned
+historical questions and only apply the current policy to newly generated rounds.
+
+The shared How it works dialog lives in `src/design-options/how-to-play.html`,
+with scoped styling in `how-to-play.css`. Update its controls, scoring examples,
+and legacy explanation when game rules change. It must remain scrollable on
+phones with dismissal controls reachable and preserve the active round.

docs/MAINTENANCE.md

@@ -60,3 +60,60 @@ for test in tests/verify-*.cjs; do node "$test"; done
 The build writes the complete playable site into `public/`. GitHub Pages publishes that directory at the domain root through the Actions workflow. CNAME and HTTPS remain configured for `perception.thedanktank.com`. Player identity, saved progress and bounded history remain in the player's browser; scheduling adds no browser storage.
 
 The share-preview artwork is generated by `scripts/build-social-image.py`, using the game's bundled fonts and native puzzle drawings. Regeneration needs Pillow with WOFF2 font support; the exported PNG ships as a static asset.
+
+## When? scoring versions
+
+New When? practice rounds and daily rounds dated October 16, 2026 onward carry
+`timelineScoringVersion: 2` and a frozen `scoringYear`. The zero-point error bound
+is `max(5, 0.25 * max(0, scoringYear - answerYear))` years. Score linearly as
+`round(100 * max(0, 1 - abs(guessYear - answerYear) / bound))`. A four-year miss
+within the five-year baseline earns 20 points. Older events have larger bounds.
+Use the challenge year, never the date a replay is opened. Questions without
+these fields retain the original 50-year bound and squared scoring curve; do not
+rewrite old saved decks or stored scores. Other games' error bounds are unchanged.
+
+## Time scoring versions
+
+New Time practice rounds and daily rounds dated October 16, 2026 onward carry
+`timeScoringVersion: 2`. Their zero-point error allowance is
+`max(1.25 seconds, 0.5 * targetSeconds)`. Score linearly using
+`round(100 * max(0, 1 - abs(elapsedSeconds - targetSeconds) / allowance))`.
+The floor widens the scoring range on short rounds; it does not create a free
+error window. Freeze the version on each question. Unversioned saved questions
+and daily dates through October 15 retain the old three-second squared curve.
+
+## Scoring rule: linear closeness for every game
+
+All new games must convert their measured error to points linearly:
+`round(100 * clamp(1 - error / zeroPointBound, 0, 1))`. Define difficulty through
+the game's error measure and bound, rather than adding a power curve. Rhythm
+retains its logarithmic distance measure for multiplicative bounds.
+Size it up clips width and height independently, averages their closeness, then
+rounds once; an oversized dimension cannot cancel an undersized one.
+
+New practice questions and daily dates on or after October 16, 2026 carry
+`scoringVersion: 2`. Question generation, IDs, answers and schedule order stay
+unchanged. Do not add that marker to historical or saved questions: their original
+scoring remains valid. Time and When? also retain their bound-specific metadata.
+
+In the linear scoring version, **3D view uses a 90° zero-point rotation bound**;
+**Angles uses 180°**. Historical 3D questions retain their 180° bound and original
+curve. A 45° 3D miss earns 50; a 90° miss earns zero.
+
+## Inner-box perspective, duration, and trace overlap
+
+Questions with `scoringVersion: 2` use these rules immediately in practice and
+from October 16, 2026 in daily challenges. Earlier questions retain their original
+bounds, curves, and thin-line rendering.
+
+- Perspective: error is the point distance divided by 40% of the inner-box
+  diagonal, `0.4 * 0.65 * hypot(360, 260)` (about 115.4 logical units).
+- How long?: error is `abs(durationValue(guess) / answer - 1) / 0.5`.
+  A 25% miss earns 50 points; 50% short or long earns zero.
+- Line memory: points are `round(100 * intersection / union)` of the two
+  round-capped, round-joined strokes, each 12 units wide on a 400×300 board.
+  A fixed half-unit raster makes scoring independent of viewport, DPR, drawing
+  speed, direction, and retracing. Extra marks increase the union and lower the
+  score. The target's dashed center distinguishes it from the player's stroke.
+- Color memory keeps its wheel-distance scoring. Internal `colour`/`memory`
+  identifiers and historical question text stay intact; UI uses American spelling.

public/about.html

@@ -1,31 +1,31 @@
 <!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>About Perception — How to Play the Daily Puzzle Game</title>
-<meta name="description" content="Five quick daily puzzles. Match colours, judge angles, feel time, and test your trivia. Play free, score up to 500, and share your results.">
+<meta name="description" content="Five quick daily puzzles. Match colors, judge angles, feel time, and test your trivia. Play free, score up to 500, and share your results.">
 <meta name="robots" content="index,follow,max-image-preview:large">
 <link rel="canonical" href="https://perception.thedanktank.com/about.html">
 <meta property="og:type" content="website">
 <meta property="og:site_name" content="Perception">
 <meta property="og:title" content="About Perception — How to Play the Daily Puzzle Game">
-<meta property="og:description" content="Five quick daily puzzles. Match colours, judge angles, feel time, and test your trivia. Play free, score up to 500, and share your results.">
+<meta property="og:description" content="Five quick daily puzzles. Match colors, judge angles, feel time, and test your trivia. Play free, score up to 500, and share your results.">
 <meta property="og:url" content="https://perception.thedanktank.com/about.html">
 <meta property="og:locale" content="en_US">
 <meta property="og:image" content="https://perception.thedanktank.com/assets/social/perception-mix.png">
 <meta property="og:image:width" content="1200">
 <meta property="og:image:height" content="630">
-<meta property="og:image:alt" content="Five Perception puzzles: rotate a 3D shape, remember a colour, judge an angle, tap a rhythm, and place a historical event on a timeline.">
+<meta property="og:image:alt" content="Five Perception puzzles: rotate a 3D shape, remember a color, judge an angle, tap a rhythm, and place a historical event on a timeline.">
 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:title" content="About Perception — How to Play the Daily Puzzle Game">
-<meta name="twitter:description" content="Five quick daily puzzles. Match colours, judge angles, feel time, and test your trivia. Play free, score up to 500, and share your results.">
+<meta name="twitter:description" content="Five quick daily puzzles. Match colors, judge angles, feel time, and test your trivia. Play free, score up to 500, and share your results.">
 <meta name="twitter:image" content="https://perception.thedanktank.com/assets/social/perception-mix.png">
-<meta name="twitter:image:alt" content="Five Perception puzzles: rotate a 3D shape, remember a colour, judge an angle, tap a rhythm, and place a historical event on a timeline.">
-<script type="application/ld+json">{"@context": "https://schema.org", "@graph": [{"@type": "WebSite", "@id": "https://perception.thedanktank.com/#website", "name": "Perception", "url": "https://perception.thedanktank.com/", "description": "Five quick daily puzzles. Match colours, judge angles, feel time, and test your trivia. Play free, score up to 500, and share your results.", "inLanguage": "en"}, {"@type": "WebApplication", "@id": "https://perception.thedanktank.com/#game", "name": "Perception", "url": "https://perception.thedanktank.com/", "description": "Five quick daily puzzles. Match colours, judge angles, feel time, and test your trivia. Play free, score up to 500, and share your results.", "applicationCategory": "GameApplication", "operatingSystem": "Any device with a modern web browser", "browserRequirements": "Requires JavaScript", "isAccessibleForFree": true, "offers": {"@type": "Offer", "price": "0", "priceCurrency": "USD"}, "image": "https://perception.thedanktank.com/assets/social/perception-mix.png"}, {"@type": "WebPage", "@id": "https://perception.thedanktank.com/about.html#page", "url": "https://perception.thedanktank.com/about.html", "name": "About Perception — How to Play the Daily Puzzle Game", "isPartOf": {"@id": "https://perception.thedanktank.com/#website"}, "about": {"@id": "https://perception.thedanktank.com/#game"}, "inLanguage": "en"}]}</script>
+<meta name="twitter:image:alt" content="Five Perception puzzles: rotate a 3D shape, remember a color, judge an angle, tap a rhythm, and place a historical event on a timeline.">
+<script type="application/ld+json">{"@context": "https://schema.org", "@graph": [{"@type": "WebSite", "@id": "https://perception.thedanktank.com/#website", "name": "Perception", "url": "https://perception.thedanktank.com/", "description": "Five quick daily puzzles. Match colors, judge angles, feel time, and test your trivia. Play free, score up to 500, and share your results.", "inLanguage": "en"}, {"@type": "WebApplication", "@id": "https://perception.thedanktank.com/#game", "name": "Perception", "url": "https://perception.thedanktank.com/", "description": "Five quick daily puzzles. Match colors, judge angles, feel time, and test your trivia. Play free, score up to 500, and share your results.", "applicationCategory": "GameApplication", "operatingSystem": "Any device with a modern web browser", "browserRequirements": "Requires JavaScript", "isAccessibleForFree": true, "offers": {"@type": "Offer", "price": "0", "priceCurrency": "USD"}, "image": "https://perception.thedanktank.com/assets/social/perception-mix.png"}, {"@type": "WebPage", "@id": "https://perception.thedanktank.com/about.html#page", "url": "https://perception.thedanktank.com/about.html", "name": "About Perception — How to Play the Daily Puzzle Game", "isPartOf": {"@id": "https://perception.thedanktank.com/#website"}, "about": {"@id": "https://perception.thedanktank.com/#game"}, "inLanguage": "en"}]}</script>
 <style>
 :root{color-scheme:dark}*{box-sizing:border-box}body{margin:0;background:#101116;color:#eef0f5;font:17px/1.7 system-ui,-apple-system,sans-serif}main{max-width:800px;margin:auto;padding:48px 24px 64px}a{color:#c7f06a}a:focus-visible{outline:3px solid #c7f06a;outline-offset:5px}.brand{font-size:18px;font-weight:700;letter-spacing:2px;text-decoration:none}h1{font-size:clamp(36px,7vw,58px);line-height:1.1;letter-spacing:-2px;margin:32px 0 20px}h2{margin-top:40px;font-size:26px;line-height:1.3}p,li{color:#bdc2cc}.lead{font-size:21px}.play{display:inline-block;background:#c7f06a;color:#151a10;padding:12px 22px;border-radius:9px;text-decoration:none;font-weight:700;margin:10px 0}table{width:100%;border-collapse:collapse;font-size:15px}th,td{text-align:left;border-bottom:1px solid #303440;padding:12px 10px;vertical-align:top}th{color:#c7f06a}td:last-child{color:#bdc2cc}details{padding:16px 0;border-bottom:1px solid #303440}summary{font-weight:600;cursor:pointer}footer{border-top:1px solid #303440;margin-top:44px;padding-top:20px;font-size:14px}footer a{margin-right:20px}@media(max-width:500px){main{padding:28px 18px}table{font-size:14px}th,td{padding:10px 6px}}
 </style></head><body><main>
 <a class="brand" href="./">◯ PERCEPTION</a>
 <h1>How sharp is your perception?</h1>
 <p class="lead">Five quick puzzles. Five different ways to get surprisingly close—or spectacularly wrong.</p>
-<p>Perception is a free daily browser game combining visual puzzles, timing, memory, and trivia. Explore an answer space: rotate a 3D shape, pick a colour on a wheel, slide through a timeline, or turn a duration dial. Make your guess, then see how close you came.</p>
+<p>Perception is a free daily browser game combining visual puzzles, timing, memory, and trivia. Explore an answer space: rotate a 3D shape, pick a color on a wheel, slide through a timeline, or turn a duration dial. Make your guess, then see how close you came.</p>
 <a class="play" href="./">Play today’s Daily Five →</a>
 <h2>One daily challenge. 500 possible points.</h2>
 <ol><li>Open the game and jump straight into Daily Five.</li><li>Play five different puzzle types. Every round is worth up to 100 points.</li><li>See your guess and the target together, with an explanation after each answer.</li><li>Finish your five rounds and share your results to compare with friends.</li></ol>
@@ -39,13 +39,18 @@ <h2>Eleven ways to test your judgement</h2>
 <tr><td>Size it up</td><td>Start with one square. Drag the corner to make a rectangle the requested number of squares wide and tall; the shaded starting square stays fixed as your reference.</td></tr>
 <tr><td>Rhythm</td><td>Watch a silent pulse and tap its tempo.</td></tr>
 <tr><td>Angles</td><td>Rotate a line to match the requested angle.</td></tr>
-<tr><td>Colour memory</td><td>Remember a swatch, then find it on a colour wheel.</td></tr>
+<tr><td>Color memory</td><td>Remember a swatch, then find it on a color wheel.</td></tr>
 <tr><td>Time awareness</td><td>Start, wait, and stop when you think the time is up.</td></tr>
 <tr><td>When?</td><td>Slide the timeline to the year of an event.</td></tr>
 <tr><td>How long?</td><td>Estimate a duration from sport, space, films, or everyday life.</td></tr>
 </tbody></table>
 <h2>How scoring works</h2>
-<p>Size it up gives width and height equal weight: each dimension earns up to 50 points using squared closeness. A 5% error in both dimensions earns 81/100; a 50% error in one dimension earns zero for that dimension. The reveal shows your dashed outline and the solid target grid.</p><p>Closer guesses earn more points. Each game measures error in its own units—degrees, seconds, years, position, or proportion—then uses the same scoring curve. An error of 10% of that game’s zero-point bound earns 81 points; 25% earns 56; 50% earns 25. Scores are rounded to whole points. An exact answer earns 100.</p>
+<p>Time uses linear scoring in daily challenges from October 16, 2026, and in new practice rounds. Its zero-point allowance is the greater of 1.25 seconds or 50% of the target duration. Only an exact match earns full accuracy; the minimum allowance is not a free-error window. Earlier daily rounds and saved results keep their original scoring.</p>
+<p>When? uses linear scoring in daily challenges from October 16, 2026, and in new practice rounds. Its zero-point allowance is the greater of five years or 25% of the event’s age, measured in the challenge year. Within the five-year allowance, each year missed costs 20 points: a four-year miss earns 20. Earlier daily rounds and saved results retain their original scoring.</p>
+<p>All new practice rounds and daily challenges from October 16, 2026 use linear scoring. Each game measures error against its own zero-point bound, then awards 100 times the remaining closeness. Using 10% of that allowance earns 90 points; 25% earns 75; half earns 50. An exact match earns 100, and reaching the bound earns zero.</p>
+<p>For the new linear scoring version, 3D view reaches zero points at 90° of rotation error; Angles reaches zero at 180°. A 45° miss earns 50 points in 3D view, while a 90° miss earns 50 in Angles.</p>
+<p>Size it up scores width and height independently, each worth up to 50 points, then rounds the combined score. A 5% miss in both dimensions earns 90/100. A 50% error in one dimension earns zero for that dimension. Earlier daily rounds and saved questions retain their original scoring.</p>
+<p>Perspective measures your miss against the inner box: 40% of its diagonal earns zero. How long? reaches zero at 50% shorter or longer than the target; a 25% miss earns 50 points. Line memory uses equal-width strokes: your score is the percentage of their combined area that overlaps. Extra marks count against you. These rules apply to the new scoring version.</p>
 <p>The game’s “How scoring works” instructions list the bounds for each puzzle. Your results show small comparisons so you can see where you were close.</p>
 <h2>A little more practice?</h2>
 <p>Open the Practice menu to pick an individual game or a fresh mixed five. Daily Five is the only daily challenge; individual games are practice-only. Trivia practice uses questions from previous Daily Fives, keeping today’s, upcoming, and unused trivia out of the practice pool. As the archive grows, sessions offer up to five different past questions.</p>