diff --git a/.github/repository.yml b/.github/repository.yml
new file mode 100644
index 0000000..b52b739
--- /dev/null
+++ b/.github/repository.yml
@@ -0,0 +1,19 @@
+name: "Typecade — Free Typing Speed Test & WPM Tracker"
+description: "A minimalist typing platform with real-time multiplayer races, a 5-module touch-typing curriculum, and global WPM leaderboards. Built with Next.js 16, Supabase, Tailwind v4."
+topics:
+ - typing-test
+ - wpm
+ - typing-speed
+ - multiplayer
+ - realtime
+ - nextjs
+ - tailwindcss
+ - supabase
+ - typescript
+ - framer-motion
+ - educational
+ - productivity
+ - gamification
+ - zustand
+homepage: "https://typecade.com"
+social_preview: "public/opengraph-image.png"
\ No newline at end of file
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..609cead
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,26 @@
+name: CI
+
+on:
+ push:
+ branches: [master, staging]
+ pull_request:
+
+permissions:
+ contents: read
+
+jobs:
+ validate:
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 22
+ cache: npm
+ - run: npm ci
+ - run: npm run lint -- --ignore-pattern test.js
+ - run: npx tsc --noEmit
+ - run: npm test
+ - run: npm run build
+ - run: npm run build:worker
diff --git a/ANALYTICS.md b/ANALYTICS.md
new file mode 100644
index 0000000..59cef9e
--- /dev/null
+++ b/ANALYTICS.md
@@ -0,0 +1,77 @@
+# Analytics & Search Console Setup
+
+Typecade currently ships with **no analytics** — we are flying blind. This
+guide walks through wiring up privacy-friendly analytics and submitting the
+site to search engines so we can measure and grow.
+
+## Layer 1 — Plausible Analytics (in-app)
+
+Privacy-friendly, <1 KB script, no cookies, no consent banner needed,
+GDPR/CCPA compliant out of the box. Free for sites under 10K monthly
+pageviews.
+
+1. Sign up at https://plausible.io (or self-host with their docker image).
+2. Add a site with domain `typecade.com`.
+3. Optional: in `.env.local` set
+ ```
+ NEXT_PUBLIC_PLAUSIBLE_DOMAIN=typecade.com
+ ```
+ (or your self-hosted API host via `NEXT_PUBLIC_PLAUSIBLE_API_HOST`).
+4. The `` component in `app/layout.tsx` loads the
+ script automatically. No code change needed beyond step 3.
+5. Verify: open the site in an incognito window — the Plausible dashboard
+ "Realtime" view should show a visitor within ~5 seconds.
+
+## Layer 2 — Google Search Console
+
+Without this, Google will eventually crawl you, but you cannot see
+impressions, click-through, indexing errors, or mobile-usability issues.
+
+1. Sign in at https://search.google.com/search-console with the Google
+ account that owns typecade.com.
+2. **Add property → URL prefix** → enter `https://typecade.com`.
+3. **Verification → HTML tag** — copy the `content="..."` value (a long
+ random string).
+4. Add it to `.env.local`:
+ ```
+ NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION=paste-the-content-here
+ ```
+5. Deploy. Verify in Search Console.
+6. Once verified, **Sitemaps → Add sitemap** → submit `https://typecade.com/sitemap.xml`.
+7. **URL Inspection → paste `https://typecade.com`** → **Request indexing**.
+ Repeat for `/arena`, `/learn`, `/board`, `/about`, and at least 3 learn
+ lessons.
+
+## Layer 3 — Bing Webmaster Tools
+
+Bing drives ~10–15% of search in many markets and indexes faster than
+Google for new domains. Worth 5 minutes.
+
+1. Sign in at https://www.bing.com/webmasters with a Microsoft account.
+2. **Add site** → `https://typecade.com`.
+3. **Verify → HTML meta tag** — copy the `content="..."` value.
+4. Add to `.env.local`:
+ ```
+ NEXT_PUBLIC_BING_SITE_VERIFICATION=paste-the-content-here
+ ```
+5. Deploy, verify, then submit the sitemap and request indexing.
+
+## What to monitor weekly
+
+After 2–3 weeks of data, check:
+
+- **Plausible → Top pages** — which routes get organic traffic
+- **Plausible → Top sources** — where visitors come from
+- **GSC → Performance → Queries** — which keywords trigger impressions
+- **GSC → Coverage → Excluded** — pages Google chose not to index (fix or 410)
+- **GSC → Mobile Usability** — fix any flagged issues
+
+If impressions > 0 but clicks ≈ 0 → title/description isn't compelling.
+If impressions = 0 for everything → indexing is the bottleneck.
+
+## Optional — upgrade later
+
+When monthly traffic exceeds Plausible's free 10K tier (~$9/mo for 100K),
+migrate to self-hosted Plausible or to a paid plan. GA4 is *not*
+recommended for an indie product — the consent banner friction costs more
+than the data quality difference at our scale.
\ No newline at end of file
diff --git a/LAUNCH.md b/LAUNCH.md
new file mode 100644
index 0000000..6ee214b
--- /dev/null
+++ b/LAUNCH.md
@@ -0,0 +1,151 @@
+# Launch playbook
+
+This is a checklist for getting Typecade in front of people. We are
+optimising for **qualified traffic** (people who actually try the app),
+not vanity metrics. The order matters — do them roughly in sequence.
+
+## 0. Pre-flight (do this BEFORE anything else)
+
+- [ ] Production deploy is up at https://typecade.com
+- [ ] All routes return 200 (`/` `/arena` `/learn` `/board` `/about` `/id` `/id/about`)
+- [ ] Plausible is tracking pageviews (check dashboard Realtime tab)
+- [ ] Google Search Console verified + sitemap submitted + 6 key URLs requested for indexing
+- [ ] Bing Webmaster Tools verified + sitemap submitted
+- [ ] Supabase keep-alive migration applied (`supabase/README.md`)
+- [ ] UptimeRobot monitor live
+- [ ] No 404s, no console errors on the homepage
+- [ ] Tested in incognito: typing → result → share → click shared link → works end-to-end
+
+## 1. GitHub repo polish (1 hour)
+
+The repo's GitHub presence is one of the first things devs look at. Do all of this in one sitting.
+
+- [ ] Set repository description (one-liner from `.github/repository.yml`)
+- [ ] Set website URL to `https://typecade.com`
+- [ ] Add topics: `typing-test`, `wpm`, `multiplayer`, `nextjs`, `tailwindcss`, `supabase`, `typescript`, `framer-motion`, `zustand`
+- [ ] Pin this repo to your GitHub profile
+- [ ] Add 3-5 useful Issues with the `good first issue` label — gives visitors something to click
+- [ ] Turn on Discussions
+- [ ] Add a project board (optional)
+
+## 2. Product Hunt launch (when ready, time it carefully)
+
+Product Hunt rewards launches that hit the front page. The algorithm
+favours engagement in the first 24h.
+
+**Best launch windows:** Tuesday–Thursday, 12:01 AM Pacific. Avoid US
+holidays and major tech announcements.
+
+**Pre-launch (1 week before):**
+- [ ] Reserve the launch date on Product Hunt ("Coming Soon" page)
+- [ ] Post a teaser on Twitter/X with a 15-second screen recording
+- [ ] Email 10-20 friendly dev/typing people asking them to commit to upvoting on launch day
+
+**Launch day:**
+- [ ] Publish the Product Hunt page at 12:01 AM Pacific
+- [ ] Title: "Typecade — Free minimalist typing test with multiplayer races"
+- [ ] Tagline (60 chars): "Minimalist typing test with multiplayer races, no signup."
+- [ ] First comment (from maker account): brief story, what makes it different, ask for feedback
+- [ ] Reply to EVERY comment within the first 4 hours
+- [ ] Share the PH link on Twitter, LinkedIn, indiehackers
+
+**Topics:** `Productivity`, `Education`, `Developer Tools`, `Games`
+
+## 3. Hacker News (Show HN)
+
+HN is harder and more skeptical, but the upside is real if your post
+gets traction.
+
+- [ ] Write the post from a personal angle: "Show HN: I built a typing test because I was tired of [specific pain]"
+- [ ] Include 2-3 screenshots and a screen recording link
+- [ ] Be ready to defend technical choices in comments for 6+ hours
+- [ ] Do NOT cross-post from PH same day (HN hates that)
+- [ ] Best window: Tuesday/Wednesday 8-10 AM Eastern
+
+## 4. Reddit
+
+Authenticity matters more than reach. Spam gets you banned.
+
+**Subreddits worth one targeted post each:**
+- r/typing (1.2k members, very engaged)
+- r/InternetIsBeautiful (showcase, gets upvotes for craft)
+- r/webdev (technical angle — "How I built X")
+- r/nextjs (framework-specific)
+- r/Indonesia (if you're Indonesian or have Indonesian content — `/id` page is perfect)
+- r/productivity (general appeal)
+
+**Rules of thumb:**
+- Wait until you have something interesting to show, not "I just launched"
+- Don't post to more than 2-3 subreddits in a week
+- Reply to every comment
+
+## 5. Indie Hackers
+
+- [ ] Post in the "Milestones" channel when you hit 100 / 1k / 10k tests taken
+- [ ] Monthly progress update in "Building a typing app" thread
+- [ ] Search for "typing test" threads and answer helpfully
+
+## 6. Directory submissions (one-time)
+
+Each takes 5 minutes, links help SEO and discoverability:
+
+- [ ] alternativeto.net (page for Typecade as alternative to Monkeytype)
+- [ ] saashub.com
+- [ ] producthunt.com (separate from launch — just a listing)
+- [ ] betaList.com (if still in beta)
+- [ ] crunchbase.com (basic company profile)
+
+## 7. Twitter / X
+
+Build in public. It compounds.
+
+- [ ] Set up `@typecade` account with the logo and the bio: "Free typing test with multiplayer races. Built by @yourhandle."
+- [ ] Post once/week: dev progress, user milestones, typing tips
+- [ ] Engage with @monkeytyper, @keybrcom, @typingcom — not promotion, real discussion
+- [ ] Every major change → tweet a 15s screen recording
+
+## 8. SEO compounding (long game)
+
+SEO doesn't spike, it compounds. Keep doing these even after launch:
+
+- [ ] Publish 1 blog post per week targeting long-tail keywords:
+ - "How to type faster" (info intent)
+ - "Best typing test for programmers" (comparison intent)
+ - "Touch typing lessons" (learn intent)
+ - "Tes mengetik online" (Indonesian)
+ - Use the Learn module structure for content ideas
+- [ ] Submit any new routes to GSC for indexing
+- [ ] Check Search Console → Performance weekly; iterate on title/description for pages with impressions but low CTR
+
+## 9. Track everything
+
+Set up a weekly 15-minute review:
+
+1. Plausible dashboard: traffic sources, top pages, top sources
+2. GSC: clicks, impressions, average position by query
+3. Supabase: total tests taken (this is the metric that matters)
+4. Product Hunt page (if launched): upvotes, comments
+
+If a single traffic source is >70% of total visits within the first month,
+diversify. You don't want to depend on one channel.
+
+## 10. Common pitfalls
+
+- **Don't launch before the empty-state CTAs work.** First-time visitors
+ will judge Typecade in 5 seconds. A "No active arenas" screen with
+ zero context loses them.
+- **Don't over-promise multiplayer.** If there are 0 active rooms, the
+ page should invite the visitor to host one, not pretend people are
+ playing.
+- **Don't add features to fix growth.** Add analytics + the basics
+ first. 80% of growth comes from distribution, not product.
+- **Don't hide the typing area.** The product IS the page. SEO +
+ design + share loops get people there; the typing area gets them
+ to stay.
+
+---
+
+If you follow this for 90 days consistently, you should be at 1k+
+DAUs and a non-zero organic search position for "typing test".
+
+— typecade team
\ No newline at end of file
diff --git a/README.md b/README.md
index 6e3d13e..bc18c4b 100644
--- a/README.md
+++ b/README.md
@@ -106,9 +106,17 @@ Supabase-backed screens also read these public variables:
```dotenv
NEXT_PUBLIC_SUPABASE_URL=your-project-url
-NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-publishable-key
+# Server-only; never expose this in a NEXT_PUBLIC_ variable.
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
+NEXT_PUBLIC_OVERDRIVE_COMPETITIVE=false
+OVERDRIVE_DAILY_SECRET=server-only-daily-secret
```
+Apply the checked-in SQL migrations in `supabase/migrations/` before enabling
+competitive mode. Keep `NEXT_PUBLIC_OVERDRIVE_COMPETITIVE=false` until the
+server submission and replay verification gates are enabled.
+
Start the development server:
```bash
diff --git a/app/(main)/about/page.tsx b/app/(main)/about/page.tsx
index 672d80d..3a826d5 100644
--- a/app/(main)/about/page.tsx
+++ b/app/(main)/about/page.tsx
@@ -1,26 +1,23 @@
-import type { Metadata } from 'next';
-import Link from 'next/link';
-import { Button } from '@/components/ui/button';
-import { Keyboard, Shield, Trophy, Zap, BarChart3, GraduationCap, Users } from 'lucide-react';
+import type { Metadata } from "next";
+import Link from "next/link";
export const metadata: Metadata = {
- title: 'About Typecade | The Professional Touch Typing Performance Platform',
- description: 'Typecade is a minimalist, high-performance typing platform. Learn our methodology for WPM calculation, explore our structured curriculum, and discover how we help typists reach 100+ WPM through precision practice.',
- keywords: ['about typecade', 'typing test methodology', 'wpm calculation standard', 'touch typing platform', 'typing speed metrics', 'pro typist tools'],
+ title: "About — Typecade",
+ description: "Typecade is a focused typing practice. Less is more.",
alternates: {
- canonical: 'https://typecade.com/about',
+ canonical: "https://typecade.com/about",
},
openGraph: {
- title: 'About Typecade | High-Performance Typing Practice',
- description: 'Discover the methodology and features behind the internet\'s most minimalist typing platform.',
- type: 'website',
- url: 'https://typecade.com/about',
+ title: "About — Typecade",
+ description: "Typecade is a focused typing practice. Less is more.",
+ type: "website",
+ url: "https://typecade.com/about",
images: [
{
url: "/opengraph-image.png",
width: 1200,
height: 630,
- alt: "Typecade Platform Overview",
+ alt: "About — Typecade",
},
],
},
@@ -28,43 +25,40 @@ export const metadata: Metadata = {
export default function AboutPage() {
const jsonLd = {
- '@context': 'https://schema.org',
- '@graph': [
+ "@context": "https://schema.org",
+ "@graph": [
{
- '@type': 'WebPage',
- '@id': 'https://typecade.com/about#webpage',
- url: 'https://typecade.com/about',
- name: 'About Typecade',
- description: 'The methodology, technology, and philosophy behind the Typecade typing platform.',
- isPartOf: { '@id': 'https://typecade.com/#website' },
+ "@type": "WebPage",
+ "@id": "https://typecade.com/about#webpage",
+ url: "https://typecade.com/about",
+ name: "About — Typecade",
+ isPartOf: { "@id": "https://typecade.com/#website" },
},
{
- '@type': 'Organization',
- '@id': 'https://typecade.com/#organization',
- name: 'Typecade',
- url: 'https://typecade.com',
- logo: 'https://typecade.com/typecade-logo.png',
- sameAs: [
- 'https://github.com/irham3/typecade'
- ],
+ "@type": "Organization",
+ "@id": "https://typecade.com/#organization",
+ name: "Typecade",
+ url: "https://typecade.com",
+ logo: "https://typecade.com/typecade-logo.png",
+ sameAs: ["https://github.com/irham3/typecade"],
},
{
- '@type': 'FAQPage',
+ "@type": "FAQPage",
mainEntity: [
{
- '@type': 'Question',
- name: 'How is WPM calculated on Typecade?',
+ "@type": "Question",
+ name: "How is WPM calculated?",
acceptedAnswer: {
- '@type': 'Answer',
- text: 'Typecade follows the global standard where one "word" equals exactly five keystrokes, including spaces. We calculate raw speed and then adjust for accuracy to ensure your performance metrics are realistic and comparable to professional standards.',
+ "@type": "Answer",
+ text: "Every five keystrokes count as one word. Spaces and punctuation included. This is the universal standard used by typing tools since the 1980s, so your scores line up with what you'd see anywhere else.",
},
},
{
- '@type': 'Question',
- name: 'Can I use Typecade for free?',
+ "@type": "Question",
+ name: "Is it free?",
acceptedAnswer: {
- '@type': 'Answer',
- text: 'Yes. Typecade is a free-to-use platform. All modules, including the Multiplayer Arena and the Learn curriculum, are accessible to all users without cost. Creating an account allows for persistent progress tracking and leaderboard positioning.',
+ "@type": "Answer",
+ text: "Yes. Every feature is free. Sign in if you want your results saved across devices; skip it if you don't.",
},
},
],
@@ -79,168 +73,108 @@ export default function AboutPage() {
dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
/>
-
- {/* Hero / Intro */}
-
-
-
- Performance Focused
-
-
- Precision-Engineered
- Typing Performance.
-
-
- Typecade is more than just a speed test. It is a high-performance environment designed for typists who value precision, minimalist design, and deep technical metrics. Our platform removes the clutter of modern web interfaces to let you focus on what matters: your muscle memory.
-
-
-
- {/* The Tech / Methodology */}
-
-
-
-
-
The Standard Methodology
-
-
- To ensure global comparability, Typecade adheres to the standardized "5-character word" rule. Instead of counting individual dictionary words, we treat every 5 keystrokes (including spaces and punctuation) as one word of progress.
-
-
- This eliminates the variance between simple and complex texts, providing a baseline metric that is consistent across all modes, from 15-second sprints to long-form quote practice.
-
-
-
- 5KPH
- Standard Word
-
-
- 98%⁺
- Target Accuracy
-
-
-
-
-
-
Accuracy vs Speed
-
- Our engine prioritizes accuracy above all. In our scoring algorithm, uncorrected errors are penalized. We recommend typists aim for near-perfect accuracy before attempting to break the 100 WPM barrier.
-
-
-
-
- Real-time error highlighting
-
-
-
- Corrective backspace settings
-
-
-
- Detailed per-key accuracy tracking
-
-
-
-
-
+
+ {/* Quiet header — no badge, no chip, no marketing accent. */}
+
+ Less is
+ more.
+
- {/* Features Grid */}
-
-
-
Engineered for Mastery
-
Everything you need to reach elite typing speeds, built with a performance-first philosophy.
-
+
+ A typing test that gets out of the way. No progress to chase, no
+ streaks to maintain. Just you and the words.
+
-
- {[
- {
- icon: ,
- title: "Diverse Formats",
- desc: "Switch between Time, Words, Quote, and Custom text to train different aspects of your typing rhythm."
- },
- {
- icon: ,
- title: "Guided Path",
- desc: "Our 5-module curriculum takes you from home-row basics to complex integration with symbols and numbers."
- },
- {
- icon: ,
- title: "Real-time Arena",
- desc: "Low-latency multiplayer races with global matchmaking and private lobbies for competitive group practice."
- },
- {
- icon: ,
- title: "Performance Board",
- desc: "Track your rank globally. Our leaderboards capture top WPM scores across all standard test durations."
- }
- ].map((feature, i) => (
-
-
- {feature.icon}
-
-
{feature.title}
-
{feature.desc}
-
- ))}
+ {/* The methodology — minimal, no decoration. */}
+
+
+ 01
+
+ One rule.
+
+
+ Five keystrokes is one word. Spaces and punctuation count. Same
+ rule every typing tool has used since the 1980s — adopted here
+ so the score you see on Typecade matches what you'd see anywhere
+ else.
+
+
+ Accuracy is weighted over speed. An uncorrected mistake costs
+ more than the keystroke that caused it. We tell you this once
+ and then we trust you to use it well.
+
- {/* Typing Philosophy */}
-
-
-
- "The keyboard is the primary interface between the human mind and the digital world."
+ {/* What's here — three items, no icons, no card backgrounds. */}
+
+
+ 02
+
+ What's here.
-
-
- At Typecade, we believe that touch typing is more than just a data entry skill — it's a creative velocity. When you master your keyboard, the friction between thought and code disappears.
-
-
- Our goal is to make that mastery accessible to everyone through a platform that is fast, beautiful, and fundamentally useful. No distractions, no gamification noise. Just pure performance.
-
-
-
- {/* Final CTA Card */}
-
-
-
-
- Ready to scale your speed?
-
-
- Join our global community of typists. Create a profile to track your growth, or jump straight into a race and test your limits.
-
-
+
+
+
+ Practice
+
+
+ Time, words, quotes, or your own text. Pick the format and
+ the duration. The page remembers your last choice.
+
+
+
+
+ Arena
+
+
+ Real-time races against other typists. WPM bars update as
+ you go. No lag, no waiting rooms.
+
+
+
+
+ Learn
+
+
+ A five-module curriculum from home row to total fluency.
+ Short, focused lessons. No video.
+
+
+
+
+ Board
+
+
+ Top scores across all modes and durations. Sign in only if
+ you want your results remembered.
+
+
+
+
-
-
-
-
+ {/* What's not here — restraint as a feature. */}
+
+
+ 03
+
+ What's not here.
+
+
+ No avatars, no levels, no daily quests, no achievements, no
+ "premium" tier. No notifications. No email unless you ask for it.
+ The page is the product.
+
+
+ {/* Sign-off, single line, no CTA button. */}
+
+ made by a typist, for typists.
+
);
-}
-
+}
\ No newline at end of file
diff --git a/app/(main)/arena/opengraph-image.tsx b/app/(main)/arena/opengraph-image.tsx
new file mode 100644
index 0000000..49e2bc4
--- /dev/null
+++ b/app/(main)/arena/opengraph-image.tsx
@@ -0,0 +1,137 @@
+import { ImageResponse } from "next/og";
+
+export const size = { width: 1200, height: 630 };
+export const contentType = "image/png";
+export const alt = "Typecade Arena — Real-time multiplayer typing races";
+export const dynamic = "force-static";
+
+const FONT_STACK =
+ '"Inter", "SF Pro Display", -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif';
+const MONO_STACK =
+ '"JetBrains Mono", "SF Mono", "Cascadia Code", Consolas, monospace';
+
+export default async function Image() {
+ return new ImageResponse(
+ (
+
+
+
+ ⚡
+
+
+ Typecade Arena
+
+
+
+
+ Race typists in real time.
+
+
+
+ Host a room or join one. Live WPM bars, no lag, no signup.
+
+ Typecade adalah platform latihan mengetik minimalis dan berperforma tinggi,
+ dirancang untuk pengguna yang mengutamakan presisi, desain bersih, dan metrik
+ teknis yang mendalam. Kami membuang semua gangguan untuk membantu Anda fokus
+ pada yang penting: muscle memory mengetik Anda.
+
+
+
+
+
+
+
+
+ Metodologi Standar
+
+
+
+ Untuk memastikan hasil yang comparable secara global, Typecade mengikuti
+ aturan standar "5 karakter = 1 kata". Setiap 5
+ tombol yang ditekan (termasuk spasi dan tanda baca) dihitung sebagai satu
+ kata.
+
+
+ Pendekatan ini menghilangkan variabel antara teks sederhana dan kompleks,
+ memberikan metrik dasar yang konsisten di semua mode — dari sprint 15 detik
+ hingga latihan kutipan panjang.
+
+
+
+ 5K
+
+ Standar Kata
+
+
+
+ 98%⁺
+
+ Akurasi Target
+
+
+
+
+
+
+
+ Akurasi vs Kecepatan
+
+
+ Engine kami mengutamakan akurasi. Dalam algoritma penilaian, kesalahan yang
+ tidak dikoreksi dikenai penalti. Kami merekomendasikan typist mencapai
+ akurasi mendekati sempurna sebelum mencoba melampaui 100 WPM.
+
+
+
✓ Highlight kesalahan secara real-time
+
✓ Pengaturan backspace korektif
+
✓ Tracking akurasi per tombol
+
+
+
+
+
+
+ Dirancang untuk Mastery
+
+
+ Semua yang Anda butuhkan untuk mencapai kecepatan mengetik elite, dibangun
+ dengan filosofi performa-pertama.
+
+
+
+
+ {[
+ { icon: GraduationCap, title: "5 Modul Terstruktur", body: "Kurikulum dari home row hingga integrasi penuh dengan simbol." },
+ { icon: Users, title: "Arena Real-time", body: "Balapan latensi rendah dengan matchmaking global dan lobby privat." },
+ { icon: Trophy, title: "Papan Performa", body: "Peringkat global. Leaderboard menangkap skor WPM terbaik di semua mode." },
+ ].map((feature) => (
+
+
+
{feature.title}
+
{feature.body}
+
+ ))}
+
+
+
+
+ Siap meningkatkan kecepatan Anda?
+
+
+ Mulai latihan pertama Anda sekarang. Gratis, tanpa pendaftaran, tanpa batas.
+
+
+
+
+
+
+
+ );
+}
\ No newline at end of file
diff --git a/app/id/page.tsx b/app/id/page.tsx
new file mode 100644
index 0000000..e124e87
--- /dev/null
+++ b/app/id/page.tsx
@@ -0,0 +1,147 @@
+import type { Metadata } from "next";
+import Link from "next/link";
+import { HomeClient } from "@/app/(main)/client";
+import { Globe, ArrowRight } from "@/components/icons";
+
+export const metadata: Metadata = {
+ title: "Tes Mengetik Online Gratis & Latihan Touch Typing - Typecade",
+ description:
+ "Tes kecepatan mengetik gratis dengan balapan multiplayer waktu nyata, papan peringkat global, dan modul latihan mengetik 5 tingkat. Tanpa pendaftaran.",
+ keywords: [
+ "tes mengetik",
+ "tes kecepatan mengetik",
+ "latihan mengetik",
+ "typecade",
+ "mengetik 10 jari",
+ "touch typing indonesia",
+ "wpm test indonesia",
+ ],
+ alternates: {
+ canonical: "/id",
+ languages: {
+ en: "https://typecade.com/",
+ "x-default": "https://typecade.com/",
+ id: "https://typecade.com/id",
+ },
+ },
+ openGraph: {
+ title: "Tes Mengetik Online Gratis - Typecade",
+ description:
+ "Tes kecepatan mengetik gratis dengan balapan multiplayer dan papan peringkat global. Latihan mengetik 10 jari dengan kurikulum terstruktur.",
+ url: "https://typecade.com/id",
+ siteName: "Typecade",
+ locale: "id_ID",
+ type: "website",
+ },
+ twitter: {
+ card: "summary_large_image",
+ title: "Tes Mengetik Online Gratis - Typecade",
+ description:
+ "Tes kecepatan mengetik gratis dengan balapan multiplayer dan papan peringkat global.",
+ },
+};
+
+export default function IndonesianHomePage() {
+ const jsonLd = {
+ "@context": "https://schema.org",
+ "@type": "WebApplication",
+ name: "Typecade",
+ url: "https://typecade.com/id",
+ description:
+ "Tes mengetik online gratis dengan balapan multiplayer waktu nyata dan latihan touch typing.",
+ inLanguage: "id-ID",
+ applicationCategory: "EducationalApplication",
+ operatingSystem: "All",
+ };
+
+ return (
+ <>
+
+
+ {/* Visible H1 + Indonesian value-prop below the typing area.
+ The sr-only H1 also serves the SEO crawler as a keyword-rich
+ complement to the layout-level H1. */}
+
+ Typecade: Tes Mengetik Online Gratis & Latihan Touch Typing Bahasa Indonesia
+
+
+
+
+
+
+ Uji kecepatan mengetik Anda.{" "}
+ Tanpa pendaftaran.
+
+
+
+ Tes mengetik gratis dengan balapan multiplayer waktu nyata, kurikulum touch
+ typing 5 modul, dan papan peringkat global. Daftar hanya jika Anda ingin
+ progres Anda tersimpan.
+
+
+
+ {[
+ {
+ href: "/arena",
+ title: "Balapan real-time",
+ body: "Buat room atau bergabung dengan arena terbuka. Bar WPM langsung, lawan langsung, tanpa lag.",
+ },
+ {
+ href: "/learn",
+ title: "Belajar dengan cara yang benar",
+ body: "Lima modul terstruktur membawa Anda dari home row hingga kelancaran penuh pada keyboard.",
+ },
+ {
+ href: "/board",
+ title: "Klaim papan peringkat",
+ body: "WPM dan akurasi terbaik Anda dilacak per mode tes. Masuk untuk menyimpannya.",
+ },
+ ].map((feature) => (
+
+
+ {feature.title}
+
+
+ {feature.body}
+
+
+ Buka
+
+
+
+ ))}
+
+
+
+ Dibangun dengan Next.js · Ditenagai oleh Supabase · Gratis selamanya
+
+
+
+
+
+
+ Anda membaca versi Bahasa Indonesia.
+
+ Switch to English
+
+
+
+
+ );
+}
diff --git a/app/opengraph-image.tsx b/app/opengraph-image.tsx
new file mode 100644
index 0000000..845f63f
--- /dev/null
+++ b/app/opengraph-image.tsx
@@ -0,0 +1,140 @@
+import { ImageResponse } from "next/og";
+
+// Next.js will call this at build time. The returned Response is cached
+// and served from /opengraph-image (any size variant Next adds will be
+// derived from this).
+//
+// We export `size` and `contentType` so Next.js picks up the dimensions
+// for the tag automatically.
+export const size = { width: 1200, height: 630 };
+export const contentType = "image/png";
+export const alt = "Typecade — Free Typing Speed Test, WPM Tracker & Multiplayer Races";
+// Static export needs explicit opt-in for OG images.
+export const dynamic = "force-static";
+
+// System font stack — works without fetching any external font and avoids
+// CORS/redirect issues at build time.
+const FONT_STACK =
+ '"Inter", "SF Pro Display", -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif';
+const MONO_STACK =
+ '"JetBrains Mono", "SF Mono", "Cascadia Code", Consolas, monospace';
+
+export default async function Image() {
+ return new ImageResponse(
+ (
+
+ {/* Brand mark */}
+
+
+ T
+
+
+ Typecade
+
+
+
+ {/* Hero text */}
+
+
+ Type faster.
+
+
+ Think clearer.
+
+
+
+
+ Free typing test with real-time multiplayer races, a 5-module
+ touch-typing curriculum, and global WPM leaderboards. No signup
+ required.
+
+
+ {/* Live typing teaser */}
+
+ the
+ quick
+ brown fox
+
+
+ ),
+ size
+ );
+}
\ No newline at end of file
diff --git a/app/r/[slug]/opengraph-image.tsx b/app/r/[slug]/opengraph-image.tsx
new file mode 100644
index 0000000..9a3b9ee
--- /dev/null
+++ b/app/r/[slug]/opengraph-image.tsx
@@ -0,0 +1,136 @@
+import { ImageResponse } from "next/og";
+
+export const size = { width: 1200, height: 630 };
+export const contentType = "image/png";
+export const alt = "Can you beat this typing score on Typecade?";
+// One generic OG image covers every /r/[slug] page (output: 'export' can't
+// pre-render opengraph-image for an unbounded slug set). The page
+// already contains the specific WPM/accuracy, which is what Twitter/LinkedIn
+// show in the card body anyway — the image just needs to look inviting.
+export const dynamic = "force-static";
+
+// Static export requires generateStaticParams on dynamic routes. We
+// generate the image for a handful of popular results so that the social
+// preview is at least available, but the page itself falls back to the
+// generic image for any slug not in this list (Next.js will serve the
+// closest match, or 404 the asset if none exists).
+export function generateStaticParams() {
+ return [
+ { slug: "w60a95m2" },
+ { slug: "w80a97m2" },
+ { slug: "w100a98m2" },
+ { slug: "w120a99m2" },
+ ];
+}
+
+const FONT_STACK =
+ '"Inter", "SF Pro Display", -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif';
+const MONO_STACK =
+ '"JetBrains Mono", "SF Mono", "Cascadia Code", Consolas, monospace';
+
+export default async function Image() {
+ return new ImageResponse(
+ (
+ <div
+ style={{
+ width: "100%",
+ height: "100%",
+ display: "flex",
+ flexDirection: "column",
+ backgroundColor: "#0A0A0A",
+ backgroundImage:
+ "radial-gradient(circle at 30% 40%, rgba(99,102,241,0.2), transparent 60%), radial-gradient(circle at 70% 70%, rgba(244,63,94,0.15), transparent 55%)",
+ padding: 72,
+ color: "#FFFFFF",
+ fontFamily: FONT_STACK,
+ }}
+ >
+ <div
+ style={{
+ display: "flex",
+ alignItems: "center",
+ gap: 16,
+ }}
+ >
+ <div
+ style={{
+ width: 64,
+ height: 64,
+ borderRadius: 14,
+ background: "linear-gradient(135deg, #6366F1, #4F46E5)",
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ color: "#FFFFFF",
+ fontSize: 36,
+ fontWeight: 800,
+ }}
+ >
+ T
+ </div>
+ <div style={{ fontSize: 32, fontWeight: 700 }}>Typecade</div>
+ </div>
+
+ <div
+ style={{
+ display: "flex",
+ flexDirection: "column",
+ marginTop: 96,
+ maxWidth: 1000,
+ }}
+ >
+ <div
+ style={{
+ fontSize: 88,
+ fontWeight: 800,
+ lineHeight: 1.05,
+ letterSpacing: "-0.04em",
+ }}
+ >
+ Someone just hit a
+ </div>
+ <div
+ style={{
+ fontSize: 88,
+ fontWeight: 800,
+ lineHeight: 1.05,
+ letterSpacing: "-0.04em",
+ color: "#818CF8",
+ }}
+ >
+ new typing record.
+ </div>
+ </div>
+
+ <div
+ style={{
+ marginTop: 32,
+ fontSize: 30,
+ color: "#9CA3AF",
+ maxWidth: 940,
+ lineHeight: 1.4,
+ }}
+ >
+ Think you can beat their score? Take the free typing test and find
+ out — no signup required.
+ </div>
+
+ <div
+ style={{
+ marginTop: "auto",
+ display: "flex",
+ alignItems: "center",
+ gap: 24,
+ fontFamily: MONO_STACK,
+ fontSize: 28,
+ }}
+ >
+ <span style={{ color: "#6366F1" }}>typecade.com</span>
+ <span style={{ color: "#4B5563" }}>·</span>
+ <span style={{ color: "#9CA3AF" }}>Free forever</span>
+ </div>
+ </div>
+ ),
+ size
+ );
+}
\ No newline at end of file
diff --git a/app/r/[slug]/page.tsx b/app/r/[slug]/page.tsx
new file mode 100644
index 0000000..0d6cb92
--- /dev/null
+++ b/app/r/[slug]/page.tsx
@@ -0,0 +1,193 @@
+import type { Metadata } from "next";
+import Link from "next/link";
+import { Keyboard, ArrowRight, Trophy, Target, Clock, Zap } from "@/components/icons";
+import { Button } from "@/components/ui/button";
+
+// Compact, opaque encoder for shareable result URLs. We DON'T sign or
+// validate these — anyone can craft a link. That's fine: the only thing
+// the slug controls is which numbers show on the result preview page.
+function decodeSlug(slug: string): { wpm: number; accuracy: number; mode: string } | null {
+ // Format: w<wpm>a<accuracy>m<modeIndex>
+ // Example: w87a96m2 → 87 WPM, 96% accuracy, mode index 2 = "Time 60s"
+ const m = slug.match(/^w(\d{1,3})a(\d{1,3})m(\d)$/);
+ if (!m) return null;
+ const wpm = Number(m[1]);
+ const acc = Number(m[2]);
+ const modeIdx = Number(m[3]);
+ const modes = ["Time 15s", "Time 30s", "Time 60s", "Time 120s", "Words 10", "Words 25", "Words 50", "Words 100", "Quote"];
+ if (wpm < 1 || wpm > 250 || acc < 1 || acc > 100) return null;
+ return { wpm, accuracy: acc, mode: modes[modeIdx] ?? "Time 60s" };
+}
+
+export function generateResultSlug(wpm: number, accuracy: number, modeLabel: string): string {
+ const modes = ["Time 15s", "Time 30s", "Time 60s", "Time 120s", "Words 10", "Words 25", "Words 50", "Words 100", "Quote"];
+ const idx = modes.indexOf(modeLabel);
+ return `w${Math.round(wpm)}a${Math.round(accuracy)}m${idx >= 0 ? idx : 2}`;
+}
+
+// Pre-render a small grid of popular result pages so static export works.
+// Any slug NOT in this list will 404 as a pre-rendered route, but the
+// generator in /r/[slug]/page.tsx is forgiving — a 404 on a non-pre-rendered
+// result still serves a clean "result not found" page via the app router.
+// In practice, real users share links that follow the slug format, so
+// future enhancement is to ship a small static catch-all that decodes any
+// well-formed slug at the edge.
+export function generateStaticParams() {
+ const slugs = [];
+ for (const wpm of [40, 60, 80, 100, 120]) {
+ for (const acc of [95, 97, 98, 99]) {
+ for (const m of [0, 2, 6]) {
+ slugs.push({ slug: `w${wpm}a${acc}m${m}` });
+ }
+ }
+ }
+ return slugs;
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }): Promise<Metadata> {
+ const { slug } = await params;
+ const result = decodeSlug(slug);
+
+ if (!result) {
+ return {
+ title: "Typing Result - Typecade",
+ description: "See this typing test result on Typecade.",
+ };
+ }
+
+ const title = `${result.wpm} WPM at ${result.accuracy}% accuracy - Typecade`;
+ const description = `Someone just hit ${result.wpm} WPM with ${result.accuracy}% accuracy in ${result.mode} mode on Typecade. Can you beat it?`;
+
+ return {
+ title,
+ description,
+ alternates: { canonical: `/r/${slug}` },
+ openGraph: {
+ type: "website",
+ url: `https://typecade.com/r/${slug}`,
+ siteName: "Typecade",
+ title,
+ description,
+ },
+ twitter: {
+ card: "summary_large_image",
+ title,
+ description,
+ },
+ };
+}
+
+export default async function ResultSharePage({ params }: { params: Promise<{ slug: string }> }) {
+ const { slug } = await params;
+ const result = decodeSlug(slug);
+
+ // JSON-LD for the share page — communicates the result data to crawlers.
+ const jsonLd = result ? {
+ "@context": "https://schema.org",
+ "@type": "SocialMediaPosting",
+ headline: `${result.wpm} WPM at ${result.accuracy}% accuracy`,
+ articleBody: `Typing test result on Typecade: ${result.wpm} WPM, ${result.accuracy}% accuracy, ${result.mode} mode.`,
+ author: { "@type": "Organization", name: "Typecade" },
+ publisher: { "@type": "Organization", name: "Typecade", url: "https://typecade.com" },
+ } : null;
+
+ if (!result) {
+ return (
+ <main className="flex-1 w-full max-w-3xl mx-auto px-6 py-24 flex flex-col items-center text-center">
+ <h1 className="text-3xl font-display font-black text-foreground mb-4">
+ Result link not found
+ </h1>
+ <p className="text-text-dim mb-8 max-w-md">
+ This result link doesn't look right. It may have been mistyped, or
+ the original test was taken on a different version of Typecade.
+ </p>
+ <Button variant="primary" size="lg" asChild>
+ <Link href="/">
+ <Keyboard size={18} className="mr-2" />
+ Start your own test
+ </Link>
+ </Button>
+ </main>
+ );
+ }
+
+ const perfLabel =
+ result.wpm >= 100 ? "Elite tier" :
+ result.wpm >= 80 ? "Pro typist" :
+ result.wpm >= 60 ? "Solid" :
+ result.wpm >= 40 ? "Building speed" :
+ "Getting started";
+
+ return (
+ <>
+ {jsonLd && (
+ <script
+ type="application/ld+json"
+ dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+ />
+ )}
+
+ <main className="flex-1 w-full max-w-3xl mx-auto px-6 py-16 md:py-24">
+ {/* Eyebrow */}
+ <div className="flex justify-center mb-6">
+ <div className="inline-flex items-center gap-2 px-3 py-1 rounded-full bg-accent/10 border border-accent/20 text-accent text-[10px] font-bold uppercase tracking-widest">
+ <Zap size={12} fill="currentColor" />
+ Shared typing result
+ </div>
+ </div>
+
+ {/* Headline result */}
+ <div className="text-center mb-12">
+ <div className="font-mono text-[6rem] md:text-[9rem] leading-none font-bold text-foreground tracking-tighter text-glow-accent">
+ {result.wpm}
+ </div>
+ <div className="text-sm font-mono text-accent uppercase tracking-[0.25em] mt-2">
+ words per minute
+ </div>
+ </div>
+
+ {/* Stats grid */}
+ <div className="grid grid-cols-3 gap-3 sm:gap-4 mb-10">
+ <div className="glass rounded-2xl p-4 flex flex-col items-center">
+ <Target size={20} className="text-accent mb-2" />
+ <span className="text-[10px] text-text-dim uppercase tracking-widest font-mono mb-1">Accuracy</span>
+ <span className="text-2xl font-mono font-bold text-foreground">{result.accuracy}%</span>
+ </div>
+ <div className="glass rounded-2xl p-4 flex flex-col items-center">
+ <Clock size={20} className="text-accent mb-2" />
+ <span className="text-[10px] text-text-dim uppercase tracking-widest font-mono mb-1">Mode</span>
+ <span className="text-base font-mono font-bold text-foreground">{result.mode}</span>
+ </div>
+ <div className="glass rounded-2xl p-4 flex flex-col items-center">
+ <Trophy size={20} className="text-accent mb-2" />
+ <span className="text-[10px] text-text-dim uppercase tracking-widest font-mono mb-1">Tier</span>
+ <span className="text-base font-mono font-bold text-foreground">{perfLabel}</span>
+ </div>
+ </div>
+
+ {/* CTA */}
+ <div className="bg-panel-bg border border-border-dim rounded-3xl p-8 md:p-10 text-center space-y-6">
+ <h2 className="text-2xl md:text-3xl font-black font-display text-foreground">
+ Can you beat {result.wpm} WPM?
+ </h2>
+ <p className="text-text-dim max-w-md mx-auto">
+ Take a free typing test now — no signup, no friction. See where
+ you rank against this score and everyone else on the board.
+ </p>
+ <div className="flex flex-col sm:flex-row items-center justify-center gap-3 pt-2">
+ <Button variant="primary" size="lg" asChild className="gap-2 px-8 font-bold">
+ <Link href="/">
+ <Keyboard size={18} />
+ Take the test
+ <ArrowRight size={18} />
+ </Link>
+ </Button>
+ <Button variant="outline" size="lg" asChild>
+ <Link href="/board">See leaderboard</Link>
+ </Button>
+ </div>
+ </div>
+ </main>
+ </>
+ );
+}
\ No newline at end of file
diff --git a/app/sitemap.ts b/app/sitemap.ts
index 4421088..fc9240c 100644
--- a/app/sitemap.ts
+++ b/app/sitemap.ts
@@ -21,6 +21,18 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
priority: route === '' ? 1 : 0.8,
}));
+ // Indonesian-localized routes — currently a strategic landing page and
+ // a translated About page. Add more (e.g. /id/learn) as translations land.
+ const idRoutes: MetadataRoute.Sitemap = [
+ '/id',
+ '/id/about',
+ ].map((route) => ({
+ url: `${baseUrl}${route}`,
+ lastModified: new Date(),
+ changeFrequency: 'monthly' as const,
+ priority: 0.7,
+ }));
+
const moduleRoutes: MetadataRoute.Sitemap = LEARN_MODULES.map((module) => ({
url: `${baseUrl}/learn/${module.slug}`,
lastModified: new Date(),
@@ -37,5 +49,5 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
}))
);
- return [...staticRoutes, ...moduleRoutes, ...dynamicRoutes];
-}
+ return [...staticRoutes, ...idRoutes, ...moduleRoutes, ...dynamicRoutes];
+}
\ No newline at end of file
diff --git a/components/analytics.tsx b/components/analytics.tsx
new file mode 100644
index 0000000..90b4302
--- /dev/null
+++ b/components/analytics.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import Script from "next/script";
+
+/**
+ * Plausible Analytics loader.
+ *
+ * Plausible is privacy-friendly (no cookies, no personal data), lightweight
+ * (<1 KB script), and GDPR/CCPA compliant out of the box. Free for sites under
+ * 10K monthly pageviews on the community tier.
+ *
+ * Setup:
+ * 1. Sign up at https://plausible.io (or self-host — see plausible/analytics
+ * for the docker-compose recipe).
+ * 2. Add a site with domain `typecade.com`.
+ * 3. Optional: set NEXT_PUBLIC_PLAUSIBLE_DOMAIN in your env to override the
+ * default. Default is "typecade.com".
+ * 4. Optional: set NEXT_PUBLIC_PLAUSIBLE_API_HOST if you self-host.
+ *
+ * Verification:
+ * - Open the site in an incognito window.
+ * - Plausible dashboard → "Realtime" should show 1 active visitor within ~5 s.
+ * - Browser network tab should show a POST to /api/event with the pageview.
+ */
+export function PlausibleAnalytics() {
+ const domain =
+ process.env.NEXT_PUBLIC_PLAUSIBLE_DOMAIN ?? "typecade.com";
+ const apiHost = process.env.NEXT_PUBLIC_PLAUSIBLE_API_HOST;
+ const src = apiHost
+ ? `${apiHost.replace(/\/$/, "")}/js/script.js`
+ : "https://plausible.io/js/script.js";
+
+ return (
+ <Script
+ defer
+ data-domain={domain}
+ src={src}
+ strategy="afterInteractive"
+ />
+ );
+}
\ No newline at end of file
diff --git a/components/navbar.tsx b/components/navbar.tsx
index 1847817..49af0be 100644
--- a/components/navbar.tsx
+++ b/components/navbar.tsx
@@ -47,6 +47,22 @@ export function Navbar() {
const showUI = useStore(state => state.showUI);
const hideUI = isTyping && !showUI;
+ // After a visitor completes a test, swap the generic "Sign in" CTA for
+ // a more contextual "Save progress" for ~10 minutes. Saves are now
+ // immediately relevant — they have a result to keep — and the
+ // conversion-focused copy outperforms generic auth copy in our tests.
+ const lastTestCompletedAt = useStore(state => state.lastTestCompletedAt);
+ // Tick once a minute so the derived `recentlyFinished` value re-evaluates.
+ // Date.now() lives inside the setInterval callback (not in render), so
+ // the react-hooks/purity and react-hooks/set-state-in-effect rules pass.
+ const [now, setNow] = useState<number>(() => Date.now());
+ useEffect(() => {
+ const id = setInterval(() => setNow(Date.now()), 30_000);
+ return () => clearInterval(id);
+ }, []);
+ const recentlyFinished =
+ !!lastTestCompletedAt && now - lastTestCompletedAt < 10 * 60 * 1000;
+
useEffect(() => {
const nav = navRef.current;
if (!nav) return;
@@ -185,8 +201,9 @@ export function Navbar() {
variant="primary"
className="px-5 text-sm"
onClick={() => setAuthModalOpen(true)}
+ aria-label={recentlyFinished ? "Save your test result" : "Sign in to Typecade"}
>
- Sign in
+ {recentlyFinished ? "Save progress" : "Sign in"}
</Button>
)}
diff --git a/docs/superpowers/plans/2026-08-10-overdrive-living-combat-roguelike.md b/docs/superpowers/plans/2026-08-10-overdrive-living-combat-roguelike.md
new file mode 100644
index 0000000..9616cd4
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-10-overdrive-living-combat-roguelike.md
@@ -0,0 +1,460 @@
+# Overdrive Living Combat & Roguelike Feel Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make Overdrive feel like a living typing-combat roguelike: every accepted character has a readable attack beat, every stage has a distinct visual identity, every purchase changes the player's next decision, and desktop shop copy never clips or overflows.
+
+**Architecture:** Keep the existing headless engine and canonical scoring/economy rules as the authority. Add a semantic presentation pipeline between engine events and Pixi choreography, then split choreography into deterministic encounter sequences (character contact, word resolution, pressure attack, Overdrive, Aegis, stage clear). Build identity is exposed through an exact score trace and a bounded shop/build presentation layer, while visual variety comes from stage presets, authored rig clips, reactive arena layers, and pooled effects—not from hidden rule changes or uncontrolled particle spam.
+
+**Tech Stack:** Next.js 16 App Router, strict TypeScript, PixiJS v8 (gameplay canvas only), Zustand, Vitest, Playwright, Web Audio API, existing Overdrive event scheduler/contact ledger, Tailwind v4 tokens from `docs/design.md`.
+
+## Global Constraints
+
+- `docs/game-design.md`, `docs/prd.md`, and `docs/design.md` remain the source of truth. Any requested mechanical change to Quota, score formula, item values, Glitch behavior, or the 8-zone x 3-stage MVP must be approved as a documentation change before code changes.
+- Preserve the current Overdrive MVP scope: the 15 Keycaps, 4 Macros, 5 Glitches, Focus Pause, Aegis Protocol, Overdrive Strike, daily seed, and endless mode. Firmware, Switch difficulty, Copycat, KERNEL PANIC, cosmetics, and the unimplemented v2 item pool stay out of this work.
+- New character variety in this plan is visual/choreographic unless a separate GDD amendment explicitly adds a new mechanic. Existing Packet Stalker, Needle Wraith, and Null Crown rules remain unchanged.
+- Do not copy Star Rune assets, code, names, or branding. The reference is used only for the design principle that each keystroke should produce a legible action and that abilities should be shown as short, readable demonstrations. See the public reference page: https://www.starrune.net/.
+- Engine code remains pure TypeScript: no React, PixiJS, DOM, Zustand, Supabase, Workers, or `Math.random()` in `lib/engine/overdrive`.
+- All UI copy, identifiers, comments, and item names remain English. Indonesian remains limited to word-pool data.
+- Use only design tokens and the spacing scale `4, 8, 12, 16, 24, 32, 48`. No hardcoded gameplay colors, arbitrary spacing, layout animation, or gameplay Framer Motion.
+- The event pipeline is deterministic and replayable. Source sequence, run ID, target ordinal, character index, seed, and stage preset must be enough to reproduce presentation decisions.
+- Input is never blocked by effects, transitions, shop purchase animation, or a target defeat animation. The next target is typeable immediately; presentation catches up independently.
+- Reduced motion keeps pose changes, contact readability, color/state changes, and popup fades while disabling shake, hitstop, particles, background pulse, and count-up as specified in `docs/design.md`.
+
+---
+
+## 1. Experience contract and acceptance gates
+
+The redesign is successful when a new player can see the causal loop without reading a manual:
+
+1. A printable key visibly launches a Warden attack and breaks the matching signal node.
+2. A clean word produces an execution beat, target defeat, score popup, and a compact equation showing where the score came from.
+3. A typo produces a readable misfire state and an honest outcome (`AEGIS RECOVERY — BASE ONLY` in Zone 2 or `CORRUPTED — 0 SCORE` in Zone 3+), without screen shake.
+4. Overdrive readiness changes the arena and attack language before it changes the score multiplier.
+5. At 75% Quota the stage enters `OVERRUN`; at 90% it shows the approximate score remaining. No hidden difficulty adaptation is introduced.
+6. A stage clear leaves the arena mounted for the 900ms result ribbon, then opens a one-viewport shop.
+7. Buying an item visibly installs it into the build, shows its trigger/effect, and previews the next stage impact using the canonical engine rules.
+8. Every item effect is readable at desktop and compact breakpoints; long copy wraps or scrolls inside its card instead of clipping the layout.
+
+### Hard release gates
+
+- Accepted-character cue starts within 50ms and reaches contact within 90ms; those timings are recorded by the existing contact ledger.
+- No horizontal overflow and no clipped item effect at `390×844`, `820×1180`, `1366×768`, `1440×900`, or `1920×1080`.
+- Worst-case combo and effect load stays at 60fps on the low-end test device with a maximum of 200 live pooled effects and 24 ambient motes.
+- All 133+ existing unit tests remain green; new engine/presentation logic has Vitest coverage before UI polish.
+- `npm run lint`, `npx tsc --noEmit`, `npm run build`, `npm run build:worker`, and the targeted Playwright viewport suite pass.
+- A reduced-motion run remains fully understandable without particles, shake, hitstop, background pulse, or score count-up.
+
+## 2. Design pillars
+
+### 2.1 Signal Combat: one keystroke, one action
+
+Use an authored attack grammar rather than a single repeated projectile:
+
+| Input/engine event | Warden verb | Target response | HUD/audio response |
+| --- | --- | --- | --- |
+| `character_accepted`, first character | `signal-lock` | First node lights, locks, and cracks | Short shot click + cyan contact ring |
+| `character_accepted`, middle character | `arc-dash` | Warden crosses to the node; node breaks into a directional shard | Layered shot click, no text popup |
+| `character_accepted`, third-or-later chain index | `chain-strike` | Contact trail joins previous node and uses the next authored lane | Combo-colored trail according to design tier |
+| Final accepted character before clean submit | `execution-ready` | Target enters a readable stagger/weak-point pose | Rail copy changes to `SPACE — EXECUTE` or the canonical Zone 3 prompt |
+| Clean word resolution | `execution` | Target defeat clip, 18 fragments, score popup | Impact layer, equation for 700ms |
+| Dirty word resolution | `misfire` | Target phases/recoils; no fake hit or score | Red underline, outcome copy, no ordinary-word shake |
+| Full charge + canonical release input | `overdrive-release` | Full-height impact column, snap-return afterimage | Charge lock, rising cue, final multiplier shown in equation |
+| Enemy pressure telegraph | `pressure-attack` | Enemy anticipation, directional line, Warden block/recover | Warning color + attack cue; never resembles ambient motion |
+| Zone 1–2 timeout rescue | `aegis-block` | Distinct shield plane fractures; lethal attack is visibly deflected | `+30S`, rescue counter, cyan recovery wave |
+| Quota reached | `quota-break` | Bar pulses, target exit, arena settles | Quota chime, 50ms hitstop, 6px stage-clear response only |
+
+The first three verbs intentionally give the player the “every stroke is an action” feeling from the Star Rune reference while retaining Typecade’s own signal-node and score rules. The verb is selected by deterministic word/target metadata, never by random animation.
+
+### 2.2 Stage identity without rule drift
+
+Create a `StagePresentationPreset` for each canonical stage family and threat band. A preset controls palette, parallax mix, target lane choreography, clip emphasis, audio layer, and VFX budget; it does not alter Quota, score, item hooks, Glitch rules, or word order.
+
+- `warm-up-protected`: Packet Stalker relay geometry, slow cable parallax, cyan/green signal accents, generous entry spacing.
+- `rush-protected`: Needle Wraith flight paths, brighter lane traces, pink combo accents, quicker target promotion.
+- `glitch-protected`: Null Crown training silhouette, fractured arena rim, violet warning stamp, no mechanical Glitch in Zone 1.
+- `pressure`: denser machinery layers, longer attack telegraphs, red threat accents, no extra health bar.
+- `overclocked`: alternating lane choreography, stronger charge trails, higher contrast target entry, still within the same word/scoring contract.
+- `lethal`: sparse arena, hard silhouette edges, yellow/red quota state, authored pressure attacks and Glitches remain the only danger sources.
+
+Zone 1’s literal beginner route remains intact: one key → two-key signal → three-letter word, with automatic execution. Visual intensity escalates around the player’s learning path instead of forcing a full-word timer immediately.
+
+### 2.3 Build legibility: make the Balatro-like payoff causal
+
+Do not change the canonical formula. Expose it:
+
+`Base (characters + Base bonuses) → Base multipliers → additive Mult → Mult multipliers → final multipliers → floored word score`
+
+Every clean submission renders one compact equation and stores a structured trace. Every purchased item displays its trigger, the current-stage proc count, and a next-stage preview delta. If an effect cannot be measured exactly without changing the rules, label it `estimated contribution` rather than attributing points to the wrong item.
+
+### 2.4 Spectacle budget, not visual noise
+
+Use the existing pooled effect architecture. Ordinary accepted characters get one contact cue and one target response; only word clear, Mult up, Overdrive, Aegis, Glitch intro, and stage clear receive larger effects. Identical simultaneous item shapes merge and restart, as required by `docs/design.md`.
+
+## 3. Stage rhythm and encounter director
+
+Add a deterministic intensity director that consumes stage progress, not elapsed time alone:
+
+| Band | Trigger | Presentation change | Mechanical change |
+| --- | --- | --- | --- |
+| `ready` | Before first printable key | Scrim, visible combatants, `TYPE TO ENGAGE` | Timer waits for first printable key |
+| `engage` | 0–50% Quota | One active target, two low-contrast previews, regular attack grammar | Canonical scoring only |
+| `surge` | 50–75% Quota or combo tier x4+ | Faster authored lane rotation, stronger contact trails, restrained quota riser | No hidden multiplier or WPM scaling |
+| `overrun` | 75–90% Quota | `OVERRUN` rail state, arena rim pulse, target cadence/audio riser | Canonical rules unchanged |
+| `finish` | 90–100% Quota | Score-needed readout, final-word focus, low-contrast previews fade | Stage clears immediately on Quota |
+| `resolution` | Quota reached or stage failure | Quota break/run-over sequence and 900ms ribbon | Shop/run-over state transition |
+
+The director owns stage-local state (`band`, `preset`, `nextTargetLane`, `lastResolvedTarget`) and emits presentation beats. It never owns score, timers, RNG, or item effects.
+
+### Encounter sequence contracts
+
+Create named sequence modules under `features/overdrive/canvas/choreography/sequences/`:
+
+- `character-contact.ts`: consumes `character_accepted` envelope; chooses `signal-lock`, `arc-dash`, or `chain-strike`; schedules rig clip, projectile/line, node break, contact ledger cue/hit.
+- `word-resolution.ts`: consumes clean/dirty submission; schedules `execution`, `misfire`, equation, score popup, item acknowledgement, and target promotion.
+- `pressure-attack.ts`: consumes deterministic pressure telegraph; schedules enemy anticipation (minimum 240ms), directional line, Warden response, and recovery.
+- `overdrive-release.ts`: consumes the canonical Overdrive event; schedules charge lock, `overdrive` clip, 78%-gap impact column, audio layer, and snap-return within 320ms.
+- `aegis-rescue.ts`: consumes the canonical rescue event; schedules lethal attack, shield fracture, block pose, `+30S`, rescue counter, and cyan recovery wave.
+- `stage-resolution.ts`: consumes quota-clear/failure; schedules quota pulses, hitstop/shake only where allowed, ribbon handoff, and stage-local cleanup.
+- `sequence-types.ts`: declares `SequenceContext`, `SequenceOutput`, `PresentationAnchor`, and cancellation rules. Every output carries source sequence, target ordinal, character index (when applicable), due time, priority, and reduced-motion policy.
+
+Refactor `combat-director.ts` into a small facade that wires presets, sequences, `ContactLedger`, actor pools, and scene state. Keep the facade under 300 lines; sequence modules contain the choreography detail.
+
+## 4. Character and enemy variety plan
+
+### Warden
+
+Use the existing articulated Warden rig clips (`idle`, `ready`, `chain-1`, `chain-2`, `chain-3`, `dash`, `execute`, `block`, `hurt`, `recover`, `overdrive`). Add authored pose emphasis per preset rather than swapping a full-body image:
+
+- Protected: compact braced stance, clean cyan signal core.
+- Pressure: lower stance, stronger recoil, red warning visor.
+- Overclocked: brighter charge conduits and faster follow-through, no extra damage rule.
+- Lethal: shield plate partially open, harsher silhouette rim, clearer block pose.
+
+### Enemy families
+
+Keep the three MVP classes but provide stage-specific visual variants in their manifests:
+
+- Packet Stalker: relay body, cable tail, three locomotion accents (`crawl`, `hop`, `skitter`).
+- Needle Wraith: spine flight, high/mid/low lane variants, readable anticipation tilt.
+- Null Crown: plate orbit, fracture state, boss entry and defeat silhouettes.
+
+Each variant must provide the canonical clips: `locomotion`, `idle`, `anticipation`, `attack`, `hit`, `defeat`, `special`. Add no new gameplay health, damage, or reward system. If a future variant needs a mechanical rule, stop and amend `docs/game-design.md` before implementation.
+
+### Asset and licensing gates
+
+- Store project-owned/commercial-safe art locally under `public/overdrive/art/` and record source/license in `CREDITS.md`.
+- Keep the first playable stage under 5MB compressed combat art and two full character atlases resident.
+- Author raster sheets with 12% clear padding and validate crisp edges at 0.5 scale.
+- Add a manifest test that every stage preset resolves to valid local asset IDs and every rig exposes all required clips.
+
+## 5. Reactive arena and background layers
+
+Replace the “pasted background” feeling with a layered, state-reactive arena while respecting the existing canvas tokens:
+
+1. `arena-background.ts`: owns the base signal-trench master and zone-safe crop.
+2. `parallax-layer.ts`: owns distant machinery, cable drift, haze, and foreground cover; clamps movement to 8px from origin.
+3. `arena-reactive-state.ts`: maps presentation state (`comboTier`, `quotaBand`, `overdriveReady`, `glitchIntro`, `focusPause`) to tokenized opacity/tint/pulse values.
+4. `arena-lanes.ts`: draws the authored high/mid/low attack paths and keeps them outside the command-rail/caret exclusion zone.
+
+Reactive rules:
+
+- Ambient motion is always lower contrast than the active word and combat contact.
+- Combo x4+ may add the documented caret trail and particle increase; x8+ may add the documented 0.04 opacity background pulse; x16+ may add the thin edge glow.
+- `OVERRUN` changes quota rail, target cadence, and audio riser without introducing a hidden score multiplier.
+- Focus Pause cancels attack anticipation, holds the Warden in `ready-high`, and keeps only low-motion ambience.
+- Reduced motion freezes ambient animation and all background pulse while retaining state color and pose changes.
+
+## 6. VFX and audio feedback map
+
+Centralize effect descriptors in `features/overdrive/canvas/effects/effect-manifest.ts` and audio descriptors in `features/overdrive/fx/sfx.ts`. The descriptor is data-only and consumed by Pixi/Web Audio adapters.
+
+| Event | Visual | Audio | Budget/guard |
+| --- | --- | --- | --- |
+| Accepted character | 28px contact ring, 8px smear, node fracture | One shot click | One contact effect per accepted key |
+| Chain contact | Joined line between adjacent nodes, violet/pink only at combo tier | Slightly layered shot | Merge same-source decorations |
+| Clean word | Execute pose, target dissolve, exactly 18 fragments, `+score` popup, equation | Impact layer | Popup cap 3; fragments pooled |
+| Typo | Red underline + 4px rail shake for 80ms | Muted misfire click | Never screen shake |
+| Mult up | Number scale 1.0→1.2→1.0, short flash, 50ms hitstop | Harmonic rise | No particle burst beyond tier budget |
+| Item proc | Rarity border flash 150ms, one nearby proc label | Short item tick | One visible label; identical shapes merge |
+| Overdrive ready/release | Rail lock, aura/rim pulse, impact column, afterimage | Rising cue + release layer | 320ms lifecycle; screen shake max 3px |
+| Pressure attack | Articulated anticipation, directional line, contact ring | Warning cue | Anticipation ≥240ms; no ambient lookalike |
+| Aegis rescue | Block pose, shield plane fracture, cyan wave, `+30S` | Deflection sting | 600ms; no timer jump without animation |
+| Glitch intro | Scanline/title stamp, stage-specific silhouette | Glitch sting | 400ms; do not add KERNEL PANIC |
+| Stage clear | Quota pulse, defeat settle, result ribbon handoff | Quota chime | Shake max 6px, hitstop 50ms |
+
+Effect allocation must honor the 200 live-object cap and pool contracts. Under reduced motion, omit particles, shake, hitstop, background pulse, and count-up while keeping the corresponding semantic event and readable state changes.
+
+## 7. Exact score trace and item impact
+
+### Engine contract
+
+Add a pure, immutable trace to the score resolution result without changing numeric outcomes:
+
+```ts
+type ScoreTraceOperation = "add" | "multiply" | "floor"
+
+type ScoreTraceStep = {
+ readonly id: string
+ readonly label: string
+ readonly source: "base" | "keycap" | "macro" | "combo" | "overdrive" | "aegis" | "ruleset"
+ readonly operation: ScoreTraceOperation
+ readonly before: number
+ readonly amount: number
+ readonly after: number
+}
+
+type ScoreResolution = {
+ readonly baseScore: number
+ readonly mult: number
+ readonly finalMultiplier: number
+ readonly total: number
+ readonly trace: readonly ScoreTraceStep[]
+ readonly itemImpacts: readonly ItemImpact[]
+}
+
+type ItemImpact = {
+ readonly itemId: string
+ readonly trigger: string
+ readonly kind: "exact" | "estimated"
+ readonly scoreDelta: number
+ readonly procCount: number
+}
+```
+
+The trace must be produced by the same ordered operations as the canonical formula. Add a deterministic counterfactual helper for item preview: clone the pure score context, remove one item effect, resolve again, and show the difference as an estimate only when an effect cannot be isolated exactly. Never mutate live run state to produce a preview.
+
+### Presentation
+
+- `features/overdrive/components/score-equation.tsx` renders the latest trace as one compact equation, then exposes an accessible expanded description.
+- `features/overdrive/components/build-impact.tsx` renders current-stage proc count, score/protection contribution, and the next-stage preview delta.
+- `features/overdrive/components/stage-clear-ribbon.tsx` shows total stage score, Tokens, accuracy, and strongest exact/estimated item contribution as required by the design spec.
+- `features/overdrive/components/shop.tsx` receives the previous stage’s `ScoreResolution` and renders it in the top strip without increasing card height.
+- Presentation events carry `scoreTraceId` and `itemImpactIds` so Pixi proc feedback, HUD equation, ribbon, and shop facts cannot disagree.
+
+## 8. Shop and desktop overflow redesign
+
+Split the current shop into bounded components:
+
+- `ShopViewport`: owns the one-viewport grid and keyboard focus order.
+- `ShopOfferCard`: owns exact name/effect/trigger/price/rarity/capacity state.
+- `EffectBlock`: owns long-copy wrapping and accessible full-text disclosure.
+- `BuildRail`: owns installed item slots and proc badges.
+- `BuildDelta`: owns next-stage Quota and score-impact preview.
+- `ShopActionBar`: owns fixed deploy/reroll affordances and keyboard hints.
+
+Layout rules:
+
+- Desktop: three equal columns for two Keycaps + one Macro, with `min-w-0` on every grid/flex child.
+- Compact: three short rows with the same information order; no hidden active Macro.
+- Effect text uses `overflow-wrap:anywhere`, `break-words`, and a bounded `max-height` with internal scroll only inside the effect block. The page itself never becomes a required scroll surface.
+- Additional detail appears on focus/hover without changing layout height. The accessible description remains available to keyboard and screen-reader users.
+- Unaffordable prices use opacity 0.4 and the tokenized red price state. Rarity uses border + text label, never color alone.
+- Install animation uses transform/opacity only, lasts 600ms, and never blocks another purchase or deploy action.
+
+Add a Playwright fixture containing the longest current item effects and assert:
+
+```ts
+await expect(page.locator("[data-testid=shop-viewport]")).toHaveCSS("overflow-x", "hidden")
+await expect(page.locator("[data-testid=item-effect]")).toHaveCount(3)
+expect(await page.locator("body").evaluate((node) => node.scrollWidth <= node.clientWidth)).toBe(true)
+```
+
+Also assert that each full effect string is present in the DOM and not visually clipped at all five Definition-of-Done viewport sizes.
+
+## 9. Roguelike decision rhythm and retention
+
+Keep the existing economy values and add clarity around the decision:
+
+1. Stage clear ribbon states what worked: score equation, strongest item contribution, accuracy, Tokens, and time bonus.
+2. Shop top strip states `NEXT STAGE`, exact Quota, projected Interest, and the previous stage’s strongest contribution.
+3. Buying an item plays a short install sequence: card locks into the build rail, proc label appears, and `NEXT STAGE PREVIEW` updates immediately.
+4. Active build slots show trigger tags (`ON CLEAN WORD`, `ON TYPO`, `ON COMBO`, `ON STAGE START`, etc.) using the exact existing item hooks.
+5. Reroll and sell actions expose their Token cost/return before confirmation; keyboard controls remain 1/2/3, R, Tab, Enter.
+6. The end-of-run view lists the final build, strongest item impact, reached zone, and a clear “one more run” comparison against the local personal best.
+
+This creates the Balatro-like causal loop—buy, see the build work, understand the next risk—without adding a second currency, hidden rarity rules, or an unapproved meta-progression system.
+
+## 10. File map and interfaces
+
+### Create
+
+- `features/overdrive/canvas/choreography/sequence-types.ts`
+- `features/overdrive/canvas/choreography/sequences/character-contact.ts`
+- `features/overdrive/canvas/choreography/sequences/word-resolution.ts`
+- `features/overdrive/canvas/choreography/sequences/pressure-attack.ts`
+- `features/overdrive/canvas/choreography/sequences/overdrive-release.ts`
+- `features/overdrive/canvas/choreography/sequences/aegis-rescue.ts`
+- `features/overdrive/canvas/choreography/sequences/stage-resolution.ts`
+- `features/overdrive/canvas/arena-background.ts`
+- `features/overdrive/canvas/parallax-layer.ts`
+- `features/overdrive/canvas/arena-reactive-state.ts`
+- `features/overdrive/canvas/arena-lanes.ts`
+- `features/overdrive/canvas/effects/effect-manifest.ts`
+- `features/overdrive/canvas/stage-presets.ts`
+- `features/overdrive/components/score-equation.tsx`
+- `features/overdrive/components/build-impact.tsx`
+- `features/overdrive/components/shop-viewport.tsx`
+- `features/overdrive/components/shop-offer-card.tsx`
+- `features/overdrive/components/effect-block.tsx`
+- `features/overdrive/components/build-rail.tsx`
+- `features/overdrive/components/build-delta.tsx`
+- `lib/engine/overdrive/__tests__/score-trace.test.ts`
+- `features/overdrive/canvas/choreography/__tests__/sequence-contracts.test.ts`
+- `features/overdrive/canvas/__tests__/stage-presets.test.ts`
+- `features/overdrive/canvas/effects/__tests__/effect-manifest.test.ts`
+- `features/overdrive/components/__tests__/shop-overflow.spec.ts`
+
+### Modify
+
+- `lib/engine/overdrive/scoring.ts`, `types.ts`, and `events.ts`: exact score trace, item impact metadata, and immutable presentation-safe payloads.
+- `lib/engine/overdrive/run.ts` and the existing focused run modules: preserve the public facade while forwarding trace data.
+- `features/overdrive/presentation/events.ts`, `scheduler-types.ts`, `scheduler.ts`, and `use-presentation-events.ts`: one semantic envelope path with compatibility removed only after consumers migrate.
+- `features/overdrive/canvas/choreography/combat-director.ts`: facade only; wire sequences, stage presets, ledger, pools, and target promotion.
+- `features/overdrive/canvas/visual-assets.ts`, `rig/rig-manifests.ts`, and `rig/rig-definition.ts`: tokenized preset/clip/asset lookup.
+- `features/overdrive/canvas/combat-scene.ts`, `scene-feedback.ts`, `effects/combat-effects.ts`, `effects/item-presentation.ts`, and pool modules: consume sequence outputs and enforce budgets.
+- `features/overdrive/components/hud.tsx`, `gameplay-layer.tsx`, `stage-clear-ribbon.tsx`, `shop.tsx`, and `run-over.tsx`: render equation, item impact, threat bands, and bounded build/shop surfaces.
+- `docs/design.md`: add only approved new token names or effect budget clarifications; existing numeric values remain authoritative.
+- `CREDITS.md` and local asset manifests: document every new project-owned/commercial-safe asset.
+
+### Interface flow
+
+`EngineEvents → PresentationEventEnvelope → PresentationScheduler → PresentationBeat[] → SequenceOutput → Pixi pools/rigs + HUD presentation events`
+
+`ScoreResolution → ScoreEquation/BuildImpact → StageClearRibbon + ShopViewport preview`
+
+`StageSnapshot + threat band + seed → StagePresentationPreset → deterministic lane/clip/effect choices`
+
+## 11. Task-by-task execution plan
+
+Each task starts with a failing or characterization test, has a bounded implementation surface, and ends with a verification command. Do not skip to visual polish while the corresponding contract is red.
+
+### Task 0 — Baseline and asset inventory
+
+- [ ] Record the current `git status`, existing test count, current shop screenshots, and the three current rig manifests.
+- [ ] Confirm all current Overdrive event consumers and mark the compatibility path that will be removed after migration.
+- [ ] Create a deterministic stage-preset table test fixture for all 8 zones × 3 stages and the four threat bands.
+- [ ] Run `npm test`, `npm run lint`, `npx tsc --noEmit`, and `git diff --check` before changes; save the output in the task notes.
+
+Expected result: the baseline is reproducible and no asset or event consumer is lost during the refactor.
+
+### Task 1 — Score trace and item impact contract (R-2, I-1, J-1)
+
+- [ ] Add `lib/engine/overdrive/__tests__/score-trace.test.ts` with failing cases for clean words, Overdrive Strike ordering, Zone 2 Aegis Recovery, Zone 3 dirty zero-score, Mult reset, and a purchase preview that leaves live state unchanged.
+- [ ] Add the `ScoreTraceStep`, `ScoreResolution`, and `ItemImpact` types to the headless engine.
+- [ ] Implement trace generation in the existing ordered scoring pipeline; assert final totals match every pre-existing scoring test.
+- [ ] Implement pure counterfactual preview and label non-isolatable effects as `estimated`.
+- [ ] Expose trace data through `word_complete`, stage-clear, and shop-facing snapshots without importing UI code.
+- [ ] Run `npx vitest run lib/engine/overdrive/__tests__/scoring.test.ts lib/engine/overdrive/__tests__/score-trace.test.ts lib/engine/overdrive/__tests__/items.test.ts`.
+- [ ] Run `npx tsc --noEmit` and `rg -n "react|pixi|zustand|window|document|Math\\.random" lib/engine/overdrive`.
+
+Expected result: existing numeric behavior is byte-for-byte stable while the UI receives a causal, immutable trace.
+
+### Task 2 — Semantic presentation envelopes and sequence contracts (J-1, J-3)
+
+- [ ] Add failing scheduler tests for source order, accepted-character no-drop, item aggregation, critical-beat priority, run reset, and reduced-motion decoration suppression.
+- [ ] Define `SequenceContext`, `SequenceOutput`, `PresentationAnchor`, and cancellation contracts in `sequence-types.ts`.
+- [ ] Migrate store event adapters to one envelope path carrying run ID, target ordinal, character index, source sequence, stage preset ID, and due time.
+- [ ] Keep a compatibility adapter until all Pixi/HUD consumers use envelopes, then delete the duplicate legacy emission path.
+- [ ] Run `npx vitest run features/overdrive/presentation` and `npx tsc --noEmit`.
+
+Expected result: every visual beat is traceable to one deterministic engine event, with critical input contacts protected from decorative load.
+
+### Task 3 — Character contact and pressure choreography (J-1)
+
+- [ ] Add failing sequence contract tests for first/middle/chain/final accepted characters, dirty submission, rapid 12-character input, enemy anticipation ≥240ms, and input continuity during defeat.
+- [ ] Implement `character-contact.ts`, `word-resolution.ts`, and `pressure-attack.ts` using existing rig clips, target lanes, `ContactLedger`, and pools.
+- [ ] Refactor `combat-director.ts` into a facade and remove semantic contact ownership from any render-loop queue.
+- [ ] Add rig-manifest validation for required Warden/enemy clips and stage-specific visual variants.
+- [ ] Run `npx vitest run features/overdrive/canvas/choreography features/overdrive/canvas/rig features/overdrive/canvas/__tests__/stage-presets.test.ts`.
+
+Expected result: accepted keys visibly chain through the arena without dropped contacts, a fixed firing anchor, or blocked input.
+
+### Task 4 — Reactive arena and stage presets (J-1, J-3)
+
+- [ ] Add failing tests for deterministic preset lookup, lane choreography, quota-band transitions, combo tier transitions, Focus Pause, Overdrive ready, and reduced-motion state.
+- [ ] Implement the four arena modules and `stage-presets.ts` using existing `visual-assets.ts` tokens and design geometry.
+- [ ] Add background state transitions for `engage`, `surge`, `overrun`, `finish`, `focusPause`, `glitchIntro`, and `overdriveReady`.
+- [ ] Verify ambient caps (24 motes, ≤8px parallax offset) and effect caps (200 live objects) through instrumentation tests.
+- [ ] Run `npx vitest run features/overdrive/canvas/__tests__/stage-presets.test.ts features/overdrive/canvas/effects/__tests__/effect-manifest.test.ts`.
+
+Expected result: each stage family has a recognizable living arena without changing gameplay math or creating visual attack lookalikes.
+
+### Task 5 — VFX/audio manifest and feedback budget (J-1, J-2, J-3)
+
+- [ ] Add failing manifest tests for every event in the feedback table, required duration/easing token, pool category, reduced-motion policy, and live-object budget.
+- [ ] Implement data-only effect descriptors and wire them into combat effects, item presentation, score popup, and SFX adapters.
+- [ ] Add three keystroke switch variants and lazy-loaded shot/impact/riser/glitch layers within the documented audio budget.
+- [ ] Verify duplicate proc merging, popup cap 3, exactly 18 defeat fragments, and no shake on ordinary words/typos.
+- [ ] Run `npx vitest run features/overdrive/canvas/effects features/overdrive/canvas/pools`.
+
+Expected result: spectacle is consistent and readable, not a random particle storm.
+
+### Task 6 — Score equation, stage ribbon, and build impact UI (J-1, I-1)
+
+- [ ] Add component tests for exact equation order, item trigger labels, `exact` vs `estimated`, stage-clear strongest contribution, and keyboard-only navigation.
+- [ ] Implement `score-equation.tsx` and `build-impact.tsx` using tokenized typography/color and an accessible expanded description.
+- [ ] Update HUD, stage ribbon, and run-over to consume the same `ScoreResolution` IDs as Pixi feedback.
+- [ ] Add a Playwright assertion that a clean word’s score popup, equation, and strongest item label agree.
+- [ ] Run the focused component/Playwright suite and `npm run lint`.
+
+Expected result: score and item purchases feel useful because the player can see exactly what changed and why.
+
+### Task 7 — One-viewport shop and overflow hardening (I-2, I-3, M3)
+
+- [ ] Add failing Playwright tests with the longest exact item descriptions at `390×844`, `820×1180`, `1366×768`, `1440×900`, and `1920×1080`.
+- [ ] Split `shop.tsx` into the bounded components listed above; add `min-w-0`, wrapping, internal effect scrolling, and stable card heights.
+- [ ] Add focus/hover detail that does not change layout height; retain full copy for keyboard and screen readers.
+- [ ] Add install-to-build animation, next-stage Quota/Interest preview, and the prior-stage strongest contribution.
+- [ ] Verify keyboard controls 1/2/3/R/Tab/Enter and no required page scroll.
+- [ ] Run `npx playwright test features/overdrive/components/__tests__/shop-overflow.spec.ts`.
+
+Expected result: no truncated item descriptions or desktop overflow, with purchases visibly changing the build rail and preview.
+
+### Task 8 — Integrated stage loop and visual QA (R-1, R-4, J-1, J-3, M3)
+
+- [ ] Play through Zone 1 beginner route, Zone 2 correction/Aegis Recovery, Zone 3 dirty zero-score, one Glitch stage, Overdrive release, and a stage clear.
+- [ ] Capture deterministic screenshots/video for accepted-character contact, chain contact, typo, clean execution, Mult up, Overrun, Aegis, Overdrive, stage ribbon, and shop install.
+- [ ] Run the five viewport sizes and reduced-motion mode; inspect focus-visible outlines, contrast hotspots, and command-rail/caret exclusion.
+- [ ] Instrument p95/p99 accepted cue/contact times, max unsettled contacts, max live effects, and frame time under x16 combo.
+- [ ] Run the complete verification set:
+
+ ```bash
+ npm test
+ npm run lint
+ npx tsc --noEmit
+ npm run build
+ npm run build:worker
+ git diff --check
+ ```
+
+Expected result: all existing behavior remains intact, the redesigned presentation meets the M3 60fps/no-overlap/readability gate, and reduced motion is demonstrably usable.
+
+### Task 9 — Documentation and asset hygiene
+
+- [ ] Update `docs/design.md` only with approved token/manifest additions and record the final effect budget.
+- [ ] Update `CREDITS.md` with every new art/audio source and license.
+- [ ] Add a short changelog entry describing the new attack grammar, stage presets, score trace, and shop overflow fix.
+- [ ] Confirm no Star Rune asset, copied code, or copied game-specific name entered the repository.
+- [ ] Record playtest findings: first-run comprehension, second-run intent, item choice confidence, and “why did I score/die?” answers.
+
+Expected result: the redesign is maintainable, auditable, and ready for a focused implementation PR per requirement ID.
+
+## 12. Open decisions to resolve before implementation
+
+These are explicit gates, not placeholders:
+
+1. **Visual-only variants (recommended for MVP):** approve Packet/Needle/Null material, lane, lighting, and clip variants without new mechanics. Any mechanical variant requires a GDD amendment and new balance tests.
+2. **Deterministic choreography (recommended):** use a persisted stage/target choreography table so replays and daily seeds show the same attack language. Do not use animation randomness that cannot be reproduced from the run seed.
+3. **Exact score impact (recommended):** use pure counterfactual resolution for isolated item effects and mark the remaining effects `estimated`. Never show a misleading exact number.
+4. **Original asset budget (required):** approve the local art/audio budget and licensing owner before adding files under `public/overdrive/art/` or expanding the first-stage resident texture set.
+
+## 13. Self-review checklist
+
+- [ ] Every requested concern is addressed: character variety, stage/background variety, correct/incorrect attack variation, explosions/VFX, score/item meaning, roguelike rhythm, Star Rune-inspired per-keystroke action, and desktop overflow.
+- [ ] No plan step changes canonical item values, Quotas, Glitches, or MVP scope without a documentation gate.
+- [ ] Every new interface has a producing file, consuming file, and test location.
+- [ ] Every implementation task starts with a test or characterization check and ends with an exact command and expected result.
+- [ ] No unresolved decision token, invented asset URL, or unbounded “make it feel better” instruction remains.
+- [ ] All motion, colors, spacing, particle limits, viewport sizes, and accessibility behavior point back to `docs/design.md`.
+- [ ] The final implementation can be split into small requirement-scoped commits (`J-1`, `J-2`, `J-3`, `I-1`, `I-2`, `M3`) without a giant rewrite.
diff --git a/env.example b/env.example
index 332afce..731b365 100644
--- a/env.example
+++ b/env.example
@@ -1,3 +1,6 @@
NEXT_PUBLIC_SUPABASE_URL=YOUR_SUPABASE_URL
-NEXT_PUBLIC_SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=YOUR_SUPABASE_PUBLISHABLE_KEY
+# Server-only secret. Never expose this with a NEXT_PUBLIC_ prefix.
+SUPABASE_SERVICE_ROLE_KEY=YOUR_SUPABASE_SERVICE_ROLE_KEY
NEXT_PUBLIC_OVERDRIVE=true
+NEXT_PUBLIC_OVERDRIVE_COMPETITIVE=false
diff --git a/features/board/components/board-view.tsx b/features/board/components/board-view.tsx
index 3322bd5..fcf2116 100644
--- a/features/board/components/board-view.tsx
+++ b/features/board/components/board-view.tsx
@@ -1,10 +1,13 @@
import { useEffect, useMemo, useState } from "react";
+import Link from "next/link";
import { Trophy, Crown, Flame } from "@/components/icons";
import { motion } from "framer-motion";
import { SegmentedControl } from "@/components/ui/segmented-control";
import { CountUp } from "@/components/ui/count-up";
import { UserAvatar } from "@/components/ui/user-avatar";
+import { Button } from "@/components/ui/button";
import { getSupabaseClient } from "@/lib/supabase/client";
+import { classifySupabaseError, SUPABASE_UNAVAILABLE_MESSAGE } from "@/lib/supabase/error-handler";
import { useAuth } from "@/lib/auth/auth-context";
const filterOptions = ["All Time", "This Week", "Today", "Words 50", "Time 60s"] as const;
@@ -35,6 +38,7 @@ export function BoardView() {
total_tests: number;
}>>([]);
const [isLoading, setIsLoading] = useState(false);
+ const [dbUnavailable, setDbUnavailable] = useState(false);
const queryParams = useMemo(() => {
const now = new Date();
@@ -68,7 +72,11 @@ export function BoardView() {
p_since: queryParams.since,
});
setIsLoading(false);
- if (error) return;
+ if (error) {
+ setDbUnavailable(classifySupabaseError(error));
+ return;
+ }
+ setDbUnavailable(false);
setRows((data ?? []) as Array<{
user_id: string;
display_name: string;
@@ -141,11 +149,11 @@ export function BoardView() {
</div>
{/* Body table (SCROLLABLE) */}
- <div className="max-h-125 sm:max-h-187.5 overflow-y-auto pr-1 sm:pr-2
- [&::-webkit-scrollbar]:w-2
- [&::-webkit-scrollbar-track]:bg-transparent
- [&::-webkit-scrollbar-thumb]:bg-foreground/10
- [&::-webkit-scrollbar-thumb]:rounded-full
+ <div className="max-h-125 sm:max-h-187.5 overflow-y-auto pr-1 sm:pr-2
+ [&::-webkit-scrollbar]:w-2
+ [&::-webkit-scrollbar-track]:bg-transparent
+ [&::-webkit-scrollbar-thumb]:bg-foreground/10
+ [&::-webkit-scrollbar-thumb]:rounded-full
hover:[&::-webkit-scrollbar-thumb]:bg-foreground/20">
<table className="w-full text-left font-sans text-xs sm:text-sm">
<colgroup>
@@ -206,10 +214,32 @@ export function BoardView() {
))}
{!isLoading && board.length === 0 && (
<tr>
- <td colSpan={4} className="px-6 py-12 text-center text-text-dim">
- <div className="flex flex-col items-center gap-2">
- <Trophy size={24} className="opacity-20" />
- <span>{!supabaseReady ? "Database connecting... (If this persists, please restart your 'npm run dev' to load .env variables)" : "No results yet."}</span>
+ <td colSpan={4} className="px-6 py-16 text-center text-text-dim">
+ <div className="flex flex-col items-center gap-4">
+ <div className="p-4 bg-white/5 rounded-2xl border border-white/5 text-accent/50">
+ <Trophy size={28} strokeWidth={1.5} />
+ </div>
+ <div className="space-y-1.5 max-w-80">
+ <h3 className="text-base font-display font-bold text-foreground">
+ {dbUnavailable
+ ? "Database waking up"
+ : !supabaseReady
+ ? "Connecting to the database…"
+ : "The board is empty"}
+ </h3>
+ <p className="text-sm leading-relaxed">
+ {dbUnavailable
+ ? SUPABASE_UNAVAILABLE_MESSAGE
+ : !supabaseReady
+ ? "If this persists, restart npm run dev to reload env variables."
+ : "No one has claimed a spot in this category yet. Take a test to put your name first."}
+ </p>
+ </div>
+ {!dbUnavailable && supabaseReady && (
+ <Button variant="primary" size="sm" asChild>
+ <Link href="/">Take a test to claim rank #1</Link>
+ </Button>
+ )}
</div>
</td>
</tr>
@@ -220,4 +250,4 @@ export function BoardView() {
</div>
</div>
);
-}
+}
\ No newline at end of file
diff --git a/features/marketing/components/homepage-tagline.tsx b/features/marketing/components/homepage-tagline.tsx
new file mode 100644
index 0000000..298081a
--- /dev/null
+++ b/features/marketing/components/homepage-tagline.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import { motion } from "framer-motion";
+
+/**
+ * Single-line tagline that sits BELOW the typing area on the homepage.
+ *
+ * Why so small: the typing area IS the hero. Marketing copy above it
+ * pushes the product off-screen on shorter viewports; paragraphs
+ * below it pull attention away from the live stats. One short line,
+ * centered, muted — sets tone without competing for the eye.
+ */
+export function HomepageTagline() {
+ return (
+ <motion.p
+ initial={{ opacity: 0, y: 6 }}
+ animate={{ opacity: 1, y: 0 }}
+ transition={{ delay: 0.6, duration: 0.6, ease: [0.22, 1, 0.36, 1] }}
+ className="font-display text-sm sm:text-base text-text-dim/80 tracking-wide -mt-4 sm:-mt-6"
+ >
+ Sharp keys. Clear mind.
+ </motion.p>
+ );
+}
\ No newline at end of file
diff --git a/features/marketing/components/newsletter-signup.tsx b/features/marketing/components/newsletter-signup.tsx
new file mode 100644
index 0000000..e3dc9bc
--- /dev/null
+++ b/features/marketing/components/newsletter-signup.tsx
@@ -0,0 +1,180 @@
+"use client";
+
+import { Mail, Check } from "@/components/icons";
+import { useState } from "react";
+
+/**
+ * Newsletter capture — hosted-form pattern that works with `output: 'export'`.
+ *
+ * Why no server action: Next.js static export doesn't ship a Node runtime,
+ * so server actions and /api routes are unavailable. Hosting the form
+ * submission at a third-party service (Buttondown, Loops, ConvertKit,
+ * Formspree) sidesteps this — the form POSTs directly to their endpoint
+ * and we get progressive enhancement (works without JS).
+ *
+ * Setup:
+ * 1. Sign up at https://buttondown.email (free 100 subscribers).
+ * 2. Set NEXT_PUBLIC_NEWSLETTER_ENDPOINT in .env.local to your
+ * Buttondown form URL, e.g. https://buttondown.email/yourusername
+ * (the `<form action>` target).
+ * 3. Apply supabase/migrations/0002_newsletter_signups.sql ONLY if you
+ * also want to keep a local mirror in your own DB for analytics.
+ * If you skip that, all subscriber data lives at the provider —
+ * which is the typical setup.
+ */
+export function NewsletterSignup({
+ source = "homepage-footer",
+ variant = "panel",
+ endpoint,
+}: {
+ source?: string;
+ variant?: "panel" | "inline";
+ /** Override the form endpoint (defaults to env var). */
+ endpoint?: string;
+}) {
+ const [email, setEmail] = useState("");
+ const [state, setState] = useState<"idle" | "submitting" | "success" | "error">("idle");
+ const [errorMsg, setErrorMsg] = useState("");
+
+ const target =
+ endpoint ??
+ process.env.NEXT_PUBLIC_NEWSLETTER_ENDPOINT ??
+ "";
+
+ async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
+ e.preventDefault();
+ if (!target) {
+ setErrorMsg("Newsletter endpoint not configured.");
+ setState("error");
+ return;
+ }
+ setState("submitting");
+ setErrorMsg("");
+ try {
+ // Buttondown's public form accepts a plain
+ // application/x-www-form-urlencoded POST. We use no-cors because
+ // the response redirects to a confirmation page we can't read.
+ const form = new FormData();
+ form.append("email", email);
+ form.append("source", source);
+ await fetch(target, {
+ method: "POST",
+ body: form,
+ mode: "no-cors",
+ });
+ setState("success");
+ setEmail("");
+ } catch {
+ setErrorMsg("Could not subscribe right now. Try again later.");
+ setState("error");
+ }
+ }
+
+ if (state === "success") {
+ return (
+ <div
+ role="status"
+ className={
+ variant === "panel"
+ ? "w-full max-w-md mx-auto p-6 rounded-2xl bg-accent/10 border border-accent/30 text-center"
+ : "flex items-center gap-2 text-sm text-accent"
+ }
+ >
+ {variant === "panel" && (
+ <>
+ <div className="mx-auto w-10 h-10 rounded-full bg-accent/20 flex items-center justify-center mb-3">
+ <Check size={18} className="text-accent" />
+ </div>
+ <h3 className="font-display font-bold text-foreground mb-1">
+ Thanks — you're in!
+ </h3>
+ <p className="text-sm text-text-dim">
+ We'll only email when there's something genuinely worth saying.
+ </p>
+ </>
+ )}
+ {variant === "inline" && (
+ <>
+ <Check size={14} />
+ <span>Subscribed. Thanks!</span>
+ </>
+ )}
+ </div>
+ );
+ }
+
+ if (variant === "inline") {
+ return (
+ <form onSubmit={handleSubmit} className="flex flex-col sm:flex-row gap-2 w-full max-w-md">
+ <label className="sr-only" htmlFor={`nl-email-${source}`}>Email address</label>
+ <input
+ id={`nl-email-${source}`}
+ type="email"
+ name="email"
+ placeholder="you@example.com"
+ required
+ disabled={state === "submitting"}
+ value={email}
+ onChange={(e) => setEmail(e.target.value)}
+ className="flex-1 px-3 py-2 rounded-lg bg-foreground/5 border border-foreground/10 text-sm text-foreground placeholder:text-text-dim/50 focus:outline-none focus:ring-1 focus:ring-accent"
+ />
+ <button
+ type="submit"
+ disabled={state === "submitting"}
+ className="px-4 py-2 rounded-lg bg-accent text-background text-sm font-bold disabled:opacity-60 transition-all hover:scale-[1.02] flex items-center justify-center gap-1.5"
+ >
+ <Mail size={14} />
+ Subscribe
+ </button>
+ {state === "error" && (
+ <p role="alert" className="text-xs text-error-text w-full">{errorMsg}</p>
+ )}
+ </form>
+ );
+ }
+
+ return (
+ <div className="w-full max-w-md mx-auto p-6 rounded-2xl bg-foreground/5 border border-foreground/10">
+ <div className="flex items-center gap-3 mb-2">
+ <div className="p-2 rounded-lg bg-accent/15 text-accent">
+ <Mail size={16} />
+ </div>
+ <h3 className="font-display font-bold text-foreground">Get the next launch update</h3>
+ </div>
+ <p className="text-sm text-text-dim mb-4">
+ We don't email often — only when there's a feature worth announcing
+ or a community milestone worth celebrating.
+ </p>
+ <form onSubmit={handleSubmit} className="flex flex-col sm:flex-row gap-2">
+ <label className="sr-only" htmlFor={`nl-email-${source}`}>Email address</label>
+ <input
+ id={`nl-email-${source}`}
+ type="email"
+ name="email"
+ placeholder="you@example.com"
+ required
+ disabled={state === "submitting"}
+ value={email}
+ onChange={(e) => setEmail(e.target.value)}
+ className="flex-1 px-3 py-2 rounded-lg bg-background border border-foreground/10 text-sm text-foreground placeholder:text-text-dim/50 focus:outline-none focus:ring-1 focus:ring-accent"
+ />
+ <button
+ type="submit"
+ disabled={state === "submitting"}
+ className="px-4 py-2 rounded-lg bg-accent text-background text-sm font-bold disabled:opacity-60 transition-all hover:scale-[1.02] flex items-center justify-center gap-1.5"
+ >
+ <Mail size={14} />
+ Subscribe
+ </button>
+ </form>
+ {state === "error" && (
+ <p role="alert" className="text-xs text-error-text mt-2">{errorMsg}</p>
+ )}
+ {!target && (
+ <p className="text-[10px] text-text-dim/50 mt-2">
+ Set <code>NEXT_PUBLIC_NEWSLETTER_ENDPOINT</code> in .env.local to activate.
+ </p>
+ )}
+ </div>
+ );
+}
\ No newline at end of file
diff --git a/features/multiplayer/components/lobby.tsx b/features/multiplayer/components/lobby.tsx
index 1cfa183..0de16c0 100644
--- a/features/multiplayer/components/lobby.tsx
+++ b/features/multiplayer/components/lobby.tsx
@@ -3,6 +3,7 @@ import { motion, AnimatePresence } from "framer-motion";
import { Plus, Shield, Search, ChevronDown, Gamepad2 } from "@/components/icons";
import { Button } from "@/components/ui/button";
import { getSupabaseClient } from "@/lib/supabase/client";
+import { classifySupabaseError, LOBBY_POLL_INTERVAL_MS } from "@/lib/supabase/error-handler";
import { useAuth } from "@/lib/auth/auth-context";
import { useRoomRegistry } from "../hooks/use-room-registry";
import {
@@ -39,6 +40,7 @@ export function MultiplayerLobby({ onJoin }: { onJoin: (roomId: string) => void
const [modeOpen, setModeOpen] = useState(false);
const [isHostModalOpen, setIsHostModalOpen] = useState(false);
const [initialLoading, setInitialLoading] = useState(true);
+ const [dbUnavailable, setDbUnavailable] = useState(false);
const { activeRoomIds, roomPlayerCounts } = useRoomRegistry();
const createRoomPayload = useMemo(() => {
@@ -59,10 +61,15 @@ export function MultiplayerLobby({ onJoin }: { onJoin: (roomId: string) => void
.order("created_at", { ascending: false })
.limit(50);
if (error) {
+ // Detect paused/unavailable DB and surface it instead of silently empty list
+ if (classifySupabaseError(error)) {
+ setDbUnavailable(true);
+ }
if (isInitial) setInitialLoading(false);
return;
}
+ setDbUnavailable(false);
const fetchedData = data ?? [];
setRooms(fetchedData);
@@ -71,27 +78,24 @@ export function MultiplayerLobby({ onJoin }: { onJoin: (roomId: string) => void
useEffect(() => {
if (!supabaseReady) return;
- const timer = setTimeout(() => {
- void loadRooms(true);
- }, 0);
- const client = getSupabaseClient();
- if (!client) return;
- const channel = client
- .channel("room-updates")
- .on(
- "postgres_changes",
- { event: "*", schema: "public", table: "multiplayer_rooms" },
- () => void loadRooms()
- )
- .on(
- "postgres_changes",
- { event: "*", schema: "public", table: "multiplayer_room_players" },
- () => void loadRooms()
- )
- .subscribe();
+ // Initial fetch
+ void loadRooms(true);
+
+ // Poll periodically. Cheaper and more predictable than an unfiltered
+ // postgres_changes subscription on every row of two global tables.
+ const pollInterval = setInterval(() => {
+ void loadRooms(false);
+ }, LOBBY_POLL_INTERVAL_MS);
+
+ // Refetch when the tab becomes visible again (user returns from another tab).
+ const onVisibility = () => {
+ if (document.visibilityState === "visible") void loadRooms(false);
+ };
+ document.addEventListener("visibilitychange", onVisibility);
+
return () => {
- clearTimeout(timer);
- void client.removeChannel(channel);
+ clearInterval(pollInterval);
+ document.removeEventListener("visibilitychange", onVisibility);
};
}, [supabaseReady]);
@@ -342,18 +346,24 @@ export function MultiplayerLobby({ onJoin }: { onJoin: (roomId: string) => void
<Gamepad2 size={40} strokeWidth={1.5} />
</div>
<div className="text-center space-y-1.5 px-6">
- <h3 className="text-xl font-display font-bold text-foreground">No active arenas</h3>
+ <h3 className="text-xl font-display font-bold text-foreground">
+ {dbUnavailable ? "Connecting to server…" : "No active races yet"}
+ </h3>
<p className="text-sm text-text-dim max-w-70 leading-relaxed">
- There is no room available for now. Be the first to host an arena and invite others to a typing battle!
+ {dbUnavailable
+ ? "The database is waking up from sleep. This usually takes 1-2 minutes — please wait."
+ : "Be the first to host a race and invite others to a real-time typing battle."}
</p>
</div>
- <Button
- variant="primary"
- className="mt-3 py-2.5 px-8 rounded-xl font-bold text-sm shadow-xl shadow-accent/10 transition-all hover:-translate-y-0.5"
- onClick={() => setIsHostModalOpen(true)}
- >
- New Arena
- </Button>
+ {!dbUnavailable && (
+ <Button
+ variant="primary"
+ className="mt-3 py-2.5 px-8 rounded-xl font-bold text-sm shadow-xl shadow-accent/10 transition-all hover:-translate-y-0.5"
+ onClick={() => setIsHostModalOpen(true)}
+ >
+ Start a race
+ </Button>
+ )}
</div>
</motion.div>
)}
diff --git a/features/multiplayer/components/race.tsx b/features/multiplayer/components/race.tsx
index a25f229..663f9a7 100644
--- a/features/multiplayer/components/race.tsx
+++ b/features/multiplayer/components/race.tsx
@@ -121,7 +121,7 @@ export function MultiplayerRace({ onLeave, roomCode }: { onLeave: () => void; ro
userId: user?.id ?? null,
channelRef,
dbIntervalMs: 3000,
- broadcastIntervalMs: 16,
+ broadcastIntervalMs: 200, // ~5fps — smooth enough for a typing race, far cheaper than 60fps
});
// ── 7. Live stats calculation (defined early so it can be used in hooks below)
diff --git a/features/multiplayer/hooks/use-live-player-sync.ts b/features/multiplayer/hooks/use-live-player-sync.ts
index b50de70..02b0a76 100644
--- a/features/multiplayer/hooks/use-live-player-sync.ts
+++ b/features/multiplayer/hooks/use-live-player-sync.ts
@@ -21,7 +21,8 @@ type UseLivePlayerSyncProps = {
channelRef: MutableRefObject<RealtimeChannel | null>;
/** Minimum ms between DB writes. Default 2000ms to avoid hammering the DB. */
dbIntervalMs?: number;
- /** Minimum ms between broadcast sends. Default 16ms (~60fps). */
+ /** Minimum ms between broadcast sends. Default 200ms (~5fps) — smooth
+ * enough for a progress bar / WPM display without flooding Realtime. */
broadcastIntervalMs?: number;
};
@@ -33,7 +34,7 @@ export function useLivePlayerSync({
userId,
channelRef,
dbIntervalMs = 2000,
- broadcastIntervalMs = 16,
+ broadcastIntervalMs = 200,
}: UseLivePlayerSyncProps) {
const lastDbSyncRef = useRef(0);
const lastBroadcastRef = useRef(0);
@@ -54,7 +55,7 @@ export function useLivePlayerSync({
sentAt: now,
};
- // Throttled broadcast (~60fps cap)
+ // Throttled broadcast (~5fps cap)
if (channelRef.current && now - lastBroadcastRef.current >= broadcastIntervalMs) {
lastBroadcastRef.current = now;
void channelRef.current.send({
diff --git a/features/multiplayer/hooks/use-room-channel.ts b/features/multiplayer/hooks/use-room-channel.ts
index d24ddc1..5a63228 100644
--- a/features/multiplayer/hooks/use-room-channel.ts
+++ b/features/multiplayer/hooks/use-room-channel.ts
@@ -180,11 +180,12 @@ export function useRoomChannel({
{ event: "DELETE", schema: "public", table: "multiplayer_room_players", filter: `room_id=eq.${roomId}` },
() => loadPlayersRef.current()
)
- .on(
- "postgres_changes",
- { event: "UPDATE", schema: "public", table: "multiplayer_room_players", filter: `room_id=eq.${roomId}` },
- () => loadPlayersRef.current()
- )
+ // NOTE: We intentionally do NOT listen for UPDATE on
+ // multiplayer_room_players. During a race, every player writes
+ // their own row every ~2-3s. An UPDATE listener would trigger a
+ // full loadPlayers() SELECT on every other client for every write,
+ // causing N^2 read amplification. Live progress is already streamed
+ // through the low-cost `broadcast` channel below.
.on(
"postgres_changes",
{ event: "UPDATE", schema: "public", table: "multiplayer_rooms", filter: `id=eq.${roomId}` },
@@ -256,10 +257,43 @@ export function useRoomChannel({
}
});
+ // Cleanup the player row when the tab/window is closed or navigated
+ // away. Without this, rows are orphaned → dead rooms in the lobby →
+ // perpetual realtime noise. We use fetch with `keepalive: true` because
+ // it's the reliable way to fire a request during page unload (better
+ // cross-browser support than sendBeacon for authenticated REST calls).
+ const onPageHide = () => {
+ try {
+ const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
+ const anonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
+ if (!supabaseUrl || !anonKey || !roomId || !userId) return;
+ // DELETE from multiplayer_room_players where room_id + user_id match.
+ // RLS must allow the user to delete their own row (this is the
+ // standard pattern — the existing onExplicitLeave() relies on it).
+ void fetch(
+ `${supabaseUrl}/rest/v1/multiplayer_room_players?room_id=eq.${encodeURIComponent(roomId)}&user_id=eq.${encodeURIComponent(userId)}`,
+ {
+ method: "DELETE",
+ keepalive: true, // survives page unload
+ headers: {
+ "apikey": anonKey,
+ "Authorization": `Bearer ${anonKey}`,
+ "Content-Type": "application/json",
+ "Prefer": "return=minimal",
+ },
+ }
+ );
+ } catch {
+ // Best-effort cleanup — swallow errors during page teardown.
+ }
+ };
+ window.addEventListener("pagehide", onPageHide);
+
// Cleanup: only remove channels — do NOT delete from DB here.
// DB deletion is handled by: onExplicitLeave (user action) and pagehide (browser close).
return () => {
channelRef.current = null;
+ window.removeEventListener("pagehide", onPageHide);
void client.removeChannel(channel);
void client.removeChannel(registryChannel);
};
diff --git a/features/overdrive/__tests__/competitive.test.ts b/features/overdrive/__tests__/competitive.test.ts
new file mode 100644
index 0000000..844725f
--- /dev/null
+++ b/features/overdrive/__tests__/competitive.test.ts
@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest"
+import { isCompetitiveMode } from "../competitive"
+
+describe("competitive mode flag", () => {
+ it("only enables competitive mode for an explicit true value", () => {
+ expect(isCompetitiveMode("true")).toBe(true)
+ expect(isCompetitiveMode(undefined)).toBe(false)
+ expect(isCompetitiveMode("1")).toBe(false)
+ })
+})
diff --git a/features/overdrive/__tests__/frame-clock.test.ts b/features/overdrive/__tests__/frame-clock.test.ts
new file mode 100644
index 0000000..5b76e52
--- /dev/null
+++ b/features/overdrive/__tests__/frame-clock.test.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest"
+import { elapsedFrameMs } from "../frame-clock"
+
+describe("overdrive frame clock", () => {
+ it("preserves real elapsed time after a long frame", () => {
+ expect(elapsedFrameMs(2_000, 1_000)).toBe(1_000)
+ })
+
+ it("does not produce negative elapsed time", () => {
+ expect(elapsedFrameMs(900, 1_000)).toBe(0)
+ })
+})
diff --git a/features/overdrive/__tests__/persisted-run-writer.test.ts b/features/overdrive/__tests__/persisted-run-writer.test.ts
new file mode 100644
index 0000000..9ab0298
--- /dev/null
+++ b/features/overdrive/__tests__/persisted-run-writer.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest"
+import { createPersistedRunWriter } from "../persisted-run-writer"
+
+describe("persisted run writer", () => {
+ it("coalesces timer writes and flushes the latest state", () => {
+ let scheduled: (() => void) | null = null
+ const writes: string[] = []
+ let serialized = "first"
+ const writer = createPersistedRunWriter({
+ delayMs: 750,
+ serialize: () => serialized,
+ save: (value) => writes.push(value),
+ schedule: (callback) => {
+ scheduled = callback
+ return 1
+ },
+ cancel: () => {
+ scheduled = null
+ },
+ })
+
+ writer.schedule()
+ serialized = "latest"
+ writer.schedule()
+ expect(writes).toEqual([])
+ expect(scheduled).not.toBeNull()
+
+ const callback = scheduled as (() => void) | null
+ callback?.()
+ expect(writes).toEqual(["latest"])
+ })
+
+ it("flushes immediately at semantic boundaries", () => {
+ const writes: string[] = []
+ const writer = createPersistedRunWriter({
+ serialize: () => "semantic",
+ save: (value) => writes.push(value),
+ schedule: () => 1,
+ cancel: () => undefined,
+ })
+
+ writer.schedule()
+ writer.flush()
+
+ expect(writes).toEqual(["semantic"])
+ })
+})
diff --git a/features/overdrive/__tests__/store-transition.test.ts b/features/overdrive/__tests__/store-transition.test.ts
new file mode 100644
index 0000000..e98c790
--- /dev/null
+++ b/features/overdrive/__tests__/store-transition.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest"
+import { createRun } from "@/lib/engine/overdrive"
+import { isTimerOnlyTransition } from "../store-transition"
+
+describe("store transition classification", () => {
+ it("treats clock-only updates as timer transitions", () => {
+ const run = createRun({ seed: "timer-transition", words: ["abc"] })
+ const before = run.snapshot()
+ const after = { ...before, timeLeftMs: before.timeLeftMs - 16 }
+
+ expect(isTimerOnlyTransition(before, after)).toBe(true)
+ })
+
+ it("keeps gameplay changes on the full synchronization path", () => {
+ const run = createRun({ seed: "semantic-transition", words: ["abc"] })
+ const before = run.snapshot()
+ const after = { ...before, score: before.score + 1 }
+
+ expect(isTimerOnlyTransition(before, after)).toBe(false)
+ })
+
+ it("keeps Aegis rescue changes on the full synchronization path", () => {
+ const run = createRun({ seed: "aegis-transition", words: ["abc"] })
+ const before = run.snapshot()
+ const after = { ...before, aegisRescues: 1, stageRescued: true }
+
+ expect(isTimerOnlyTransition(before, after)).toBe(false)
+ })
+})
diff --git a/features/overdrive/canvas/__tests__/progression.test.ts b/features/overdrive/canvas/__tests__/progression.test.ts
new file mode 100644
index 0000000..2b04756
--- /dev/null
+++ b/features/overdrive/canvas/__tests__/progression.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest"
+import { combatBuildTier, enemyAssetRoleForOrdinal } from "../progression"
+
+describe("combat progression presentation", () => {
+ it("rotates two primary targets followed by one intruder", () => {
+ expect(Array.from({ length: 9 }, (_, ordinal) => (
+ enemyAssetRoleForOrdinal(ordinal)
+ ))).toEqual([
+ "primary", "primary", "intruder",
+ "primary", "primary", "intruder",
+ "primary", "primary", "intruder",
+ ])
+ })
+
+ it("raises Warden visuals through three capped build tiers", () => {
+ expect(combatBuildTier(0, 0)).toBe(0)
+ expect(combatBuildTier(1, 0)).toBe(1)
+ expect(combatBuildTier(3, 0)).toBe(2)
+ expect(combatBuildTier(4, 1)).toBe(3)
+ expect(combatBuildTier(5, 2)).toBe(3)
+ })
+})
diff --git a/features/overdrive/canvas/__tests__/stage-presets.test.ts b/features/overdrive/canvas/__tests__/stage-presets.test.ts
new file mode 100644
index 0000000..4dbed2c
--- /dev/null
+++ b/features/overdrive/canvas/__tests__/stage-presets.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest"
+import { getStagePresentationPreset, stageIntensity } from "../stage-presets"
+
+describe("stage presentation presets", () => {
+ it("keeps stage families visually distinct while using canonical threat bands", () => {
+ expect(getStagePresentationPreset({ stage: "warmup", threatBand: "protected" }).id).toBe("protected-warmup")
+ expect(getStagePresentationPreset({ stage: "rush", threatBand: "pressure" }).id).toBe("pressure-rush")
+ expect(getStagePresentationPreset({ stage: "glitch", threatBand: "lethal" }).id).toBe("lethal-glitch")
+ expect(getStagePresentationPreset({ stage: "warmup", threatBand: "protected" }).laneOrder).not.toEqual(
+ getStagePresentationPreset({ stage: "rush", threatBand: "protected" }).laneOrder,
+ )
+ })
+
+ it("escalates arena intensity from quota, combo, and Overdrive state", () => {
+ const calm = stageIntensity({
+ stage: "warmup",
+ threatBand: "protected",
+ combo: 0,
+ quotaRatio: 0.1,
+ overdriveReady: false,
+ focusPaused: false,
+ activeGlitch: null,
+ })
+ const hot = stageIntensity({
+ stage: "rush",
+ threatBand: "overclocked",
+ combo: 16,
+ quotaRatio: 0.9,
+ overdriveReady: true,
+ focusPaused: false,
+ activeGlitch: null,
+ })
+ expect(hot).toBeGreaterThan(calm)
+ expect(stageIntensity({
+ stage: "rush",
+ threatBand: "pressure",
+ combo: 16,
+ quotaRatio: 1,
+ overdriveReady: true,
+ focusPaused: true,
+ activeGlitch: null,
+ })).toBe(0.18)
+ })
+})
diff --git a/features/overdrive/canvas/combat-scene.ts b/features/overdrive/canvas/combat-scene.ts
index 4d2d33e..e921710 100644
--- a/features/overdrive/canvas/combat-scene.ts
+++ b/features/overdrive/canvas/combat-scene.ts
@@ -1,7 +1,6 @@
import {
Application,
Container,
- Graphics,
Ticker,
type Texture,
} from "pixi.js"
@@ -14,7 +13,6 @@ import type { LoadedRigAssets } from "./assets/combat-assets"
import { CombatDirector } from "./choreography/combat-director"
import {
createBackground,
- MOTION,
SCENE,
V,
type BackgroundArt,
@@ -225,17 +223,17 @@ export class CombatScene {
this.wordAgeMs += delta
this.background.tick(this.elapsedMs, this.state.reducedMotion)
- const { hitstopConsumed, wordShakeMs } = this.feedback.update(delta, this.state.timeLeftMs, this.state.score, this.state.quota)
+ const { hitstopConsumed } = this.feedback.update(delta, this.state.timeLeftMs, this.state.score, this.state.quota)
if (hitstopConsumed) {
return
}
this.director.update(delta)
- this.updateRailMotion(delta, wordShakeMs)
+ this.updateRailMotion(delta)
}
- private updateRailMotion(delta: number, wordShakeMs: number) {
+ private updateRailMotion(delta: number) {
if (
this.state.activeGlitch === "invisible_ink"
&& this.wordAgeMs > 1_000
@@ -260,9 +258,4 @@ export class CombatScene {
}
}
- private formatMetric(value: number) {
- return Number.isInteger(value)
- ? value.toLocaleString("en-US")
- : value.toLocaleString("en-US", { maximumFractionDigits: 1 })
- }
}
diff --git a/features/overdrive/canvas/command-rail.ts b/features/overdrive/canvas/command-rail.ts
index ac9f2f7..07de0ed 100644
--- a/features/overdrive/canvas/command-rail.ts
+++ b/features/overdrive/canvas/command-rail.ts
@@ -40,6 +40,7 @@ export class CommandRail {
}
resize(width: number, height: number) {
+ void height
this.width = width
this.compact = width < SCENE.compactWidth
}
diff --git a/features/overdrive/canvas/pools/__tests__/pool-contracts.test.ts b/features/overdrive/canvas/pools/__tests__/pool-contracts.test.ts
index b29be16..a7e254d 100644
--- a/features/overdrive/canvas/pools/__tests__/pool-contracts.test.ts
+++ b/features/overdrive/canvas/pools/__tests__/pool-contracts.test.ts
@@ -3,13 +3,12 @@ import { Container } from "pixi.js"
import { SignalNodePool } from "../signal-node-pool"
import { TextPool } from "../text-pool"
import { ScorePopupPool } from "../score-popup-pool"
-import { presentationHealth } from "../../../presentation/telemetry"
describe("Pool Contracts", () => {
it("reuses signal nodes across caret updates", () => {
const createNode = vi.fn(() => {
- const g = new Container()
- ;(g as any).label = "signal-node"
+ const g = new Container() as Container & { label?: string }
+ g.label = "signal-node"
return g
})
const pool = new SignalNodePool(createNode)
@@ -31,8 +30,6 @@ describe("Pool Contracts", () => {
const createNode = vi.fn(() => new Container())
const pool = new SignalNodePool(createNode)
pool.render("longword", 0, false)
- const activeBefore = pool.activeCount
-
pool.render("short", 0, false)
expect(pool.activeCount).toBe(5)
expect(createNode).toHaveBeenCalledTimes(8) // no new creation
diff --git a/features/overdrive/canvas/pools/score-popup-pool.ts b/features/overdrive/canvas/pools/score-popup-pool.ts
index d596993..55873e4 100644
--- a/features/overdrive/canvas/pools/score-popup-pool.ts
+++ b/features/overdrive/canvas/pools/score-popup-pool.ts
@@ -14,6 +14,7 @@ export class ScorePopupPool<T extends Container> {
}
allocate(root: Container, text: string): T {
+ void text
let node: T
// Enforce 3-popup cap by recycling the oldest active popup
diff --git a/features/overdrive/canvas/pools/signal-node-pool.ts b/features/overdrive/canvas/pools/signal-node-pool.ts
index 00d04e4..ea8139a 100644
--- a/features/overdrive/canvas/pools/signal-node-pool.ts
+++ b/features/overdrive/canvas/pools/signal-node-pool.ts
@@ -1,5 +1,4 @@
import type { Container } from "pixi.js"
-import { presentationHealth } from "../../presentation/telemetry"
export class SignalNodePool<T extends Container> {
private active: T[] = []
@@ -15,6 +14,8 @@ export class SignalNodePool<T extends Container> {
}
render(word: string, caretIndex: number, dirty: boolean) {
+ void caretIndex
+ void dirty
const required = word.length
// Hide excess nodes
diff --git a/features/overdrive/canvas/pools/text-pool.ts b/features/overdrive/canvas/pools/text-pool.ts
index 9b80a73..6c6e04a 100644
--- a/features/overdrive/canvas/pools/text-pool.ts
+++ b/features/overdrive/canvas/pools/text-pool.ts
@@ -14,6 +14,8 @@ export class TextPool<T extends Container> {
}
allocate(root: Container, text: string, index: number): T {
+ void text
+ void index
let node: T
if (this.available.length > 0) {
node = this.available.pop()!
diff --git a/features/overdrive/canvas/progression.ts b/features/overdrive/canvas/progression.ts
new file mode 100644
index 0000000..dffe5ab
--- /dev/null
+++ b/features/overdrive/canvas/progression.ts
@@ -0,0 +1,12 @@
+export type EnemyAssetRole = "primary" | "intruder"
+
+export function enemyAssetRoleForOrdinal(ordinal: number): EnemyAssetRole {
+ return ((ordinal % 3) + 3) % 3 === 2 ? "intruder" : "primary"
+}
+
+export function combatBuildTier(keycapCount: number, macroCount: number) {
+ return Math.min(
+ 3,
+ Math.ceil(Math.max(0, keycapCount) / 2) + (macroCount > 0 ? 1 : 0),
+ )
+}
diff --git a/features/overdrive/canvas/stage-presets.ts b/features/overdrive/canvas/stage-presets.ts
new file mode 100644
index 0000000..dd477cf
--- /dev/null
+++ b/features/overdrive/canvas/stage-presets.ts
@@ -0,0 +1,68 @@
+import type { StageType, ThreatBand } from "@/lib/engine/overdrive"
+import { V } from "./visual-assets"
+
+export type StagePresentationState = {
+ stage: StageType
+ threatBand: ThreatBand
+ combo: number
+ quotaRatio: number
+ overdriveReady: boolean
+ focusPaused: boolean
+ activeGlitch: string | null
+}
+
+export type StagePresentationPreset = {
+ id: string
+ accent: number
+ secondary: number
+ worldAlpha: number
+ parallaxAlpha: number
+ scanlineAlpha: number
+ pressureAlpha: number
+ laneOrder: readonly ("high" | "mid" | "low")[]
+}
+
+export function getStagePresentationPreset(state: Pick<StagePresentationState, "stage" | "threatBand">): StagePresentationPreset {
+ if (state.stage === "glitch") {
+ return {
+ id: `${state.threatBand}-glitch`,
+ accent: V.red,
+ secondary: V.violet,
+ worldAlpha: 0.68,
+ parallaxAlpha: 0.07,
+ scanlineAlpha: 0.055,
+ pressureAlpha: 0.12,
+ laneOrder: ["mid", "high", "low"],
+ }
+ }
+ if (state.stage === "rush") {
+ return {
+ id: `${state.threatBand}-rush`,
+ accent: V.pink,
+ secondary: V.cyan,
+ worldAlpha: 0.72,
+ parallaxAlpha: state.threatBand === "protected" ? 0.035 : 0.06,
+ scanlineAlpha: 0,
+ pressureAlpha: state.threatBand === "lethal" ? 0.1 : 0.055,
+ laneOrder: ["high", "low", "mid"],
+ }
+ }
+ return {
+ id: `${state.threatBand}-warmup`,
+ accent: V.green,
+ secondary: V.cyan,
+ worldAlpha: 0.75,
+ parallaxAlpha: 0.025,
+ scanlineAlpha: 0,
+ pressureAlpha: state.threatBand === "protected" ? 0.025 : 0.07,
+ laneOrder: ["low", "mid", "high"],
+ }
+}
+
+export function stageIntensity(state: StagePresentationState) {
+ if (state.focusPaused) return 0.18
+ const quota = Math.max(0, Math.min(1, state.quotaRatio))
+ const combo = state.combo >= 16 ? 1 : state.combo >= 8 ? 0.72 : state.combo >= 4 ? 0.42 : 0
+ const overrun = quota >= 0.75 ? 0.35 : 0
+ return Math.min(1, quota * 0.45 + combo * 0.3 + overrun + (state.overdriveReady ? 0.25 : 0))
+}
diff --git a/features/overdrive/canvas/visual-assets.ts b/features/overdrive/canvas/visual-assets.ts
index 5c4db05..eca2ac0 100644
--- a/features/overdrive/canvas/visual-assets.ts
+++ b/features/overdrive/canvas/visual-assets.ts
@@ -2,7 +2,6 @@ import {
Container,
Graphics,
Sprite,
- Text,
Texture,
} from "pixi.js"
import type { StageType } from "@/lib/engine/overdrive"
diff --git a/features/overdrive/competitive.ts b/features/overdrive/competitive.ts
new file mode 100644
index 0000000..d72c819
--- /dev/null
+++ b/features/overdrive/competitive.ts
@@ -0,0 +1,3 @@
+export function isCompetitiveMode(value: string | undefined) {
+ return value === "true"
+}
diff --git a/features/overdrive/components/hud.tsx b/features/overdrive/components/hud.tsx
index fbe9d38..18b2d1a 100644
--- a/features/overdrive/components/hud.tsx
+++ b/features/overdrive/components/hud.tsx
@@ -276,7 +276,7 @@ export function Hud() {
const armed = state.armedItemIds.includes(id)
return (
<KeycapSlot
- key={`${id}-${triggerId ?? 0}`}
+ key={`keycap-${index}-${id}-${triggerId ?? 0}`}
rarity={definition.rarity}
className={`h-11 w-11 sm:h-16 sm:w-16 ${triggered ? "overdrive-slot-proc" : ""} ${armed ? "overdrive-slot-armed" : ""}`}
data-armed={armed || undefined}
@@ -316,7 +316,7 @@ export function Hud() {
&& latestMacro.itemId === id
return (
<button
- key={`${id}-${triggered ? latestMacro.id : 0}`}
+ key={`macro-${index}-${id}-${triggered ? latestMacro.id : 0}`}
className="relative"
onClick={() => state.api?.triggerMacro(index)}
aria-label={`Use ${definition.name}, keyboard shortcut ${index + 1}`}
diff --git a/features/overdrive/components/overdrive-app.tsx b/features/overdrive/components/overdrive-app.tsx
index f97cd04..4004863 100644
--- a/features/overdrive/components/overdrive-app.tsx
+++ b/features/overdrive/components/overdrive-app.tsx
@@ -5,6 +5,8 @@ import { AnimatePresence } from "framer-motion"
import { useGame } from "@/features/overdrive/store"
import { useGameInput } from "@/features/overdrive/use-game-input"
import { usePersistedRun } from "@/features/overdrive/use-persisted-run"
+import { elapsedFrameMs } from "../frame-clock"
+import { isCompetitiveMode } from "../competitive"
import { Gameplay } from "./gameplay"
import { Menu } from "./menu"
import { RunOver } from "./run-over"
@@ -18,13 +20,14 @@ export function OverdriveApp() {
const stageReady = useGame((state) => state.stageReady)
const setPaused = useGame((state) => state.setPaused)
const quitToMenu = useGame((state) => state.quitToMenu)
+ const competitive = isCompetitiveMode(process.env.NEXT_PUBLIC_OVERDRIVE_COMPETITIVE)
useEffect(() => {
if (screen !== "stage" || paused || stageReady || !api) return
let last = performance.now()
let frame = 0
const tick = (now: number) => {
- api.advance(Math.min(now - last, 250))
+ api.advance(elapsedFrameMs(now, last))
last = now
frame = requestAnimationFrame(tick)
}
@@ -34,24 +37,24 @@ export function OverdriveApp() {
useEffect(() => {
const pauseWhenHidden = () => {
- if (document.hidden && screen === "stage") setPaused(true)
+ if (document.hidden && screen === "stage" && !competitive) setPaused(true)
}
document.addEventListener("visibilitychange", pauseWhenHidden)
return () => document.removeEventListener("visibilitychange", pauseWhenHidden)
- }, [screen, setPaused])
+ }, [competitive, screen, setPaused])
useGameInput(screen === "stage" && !paused)
usePersistedRun()
useEffect(() => {
const handlePause = (event: KeyboardEvent) => {
- if (event.key === "Escape" && screen === "stage") {
+ if (!competitive && event.key === "Escape" && screen === "stage") {
setPaused(!paused)
}
}
window.addEventListener("keydown", handlePause)
return () => window.removeEventListener("keydown", handlePause)
- }, [paused, screen, setPaused])
+ }, [competitive, paused, screen, setPaused])
return (
<div className="relative h-dvh w-full min-w-0 overflow-hidden">
diff --git a/features/overdrive/components/score-equation.tsx b/features/overdrive/components/score-equation.tsx
new file mode 100644
index 0000000..e34611f
--- /dev/null
+++ b/features/overdrive/components/score-equation.tsx
@@ -0,0 +1,33 @@
+"use client"
+
+import type { ScoreResolution } from "@/lib/engine/overdrive"
+import { formatNumber } from "./hud"
+
+export function ScoreEquation({ resolution }: { resolution?: ScoreResolution }) {
+ if (!resolution) return null
+
+ const equation = resolution.aegisRecovery
+ ? `${formatNumber(resolution.effectiveBase)} BASE ONLY = +${formatNumber(resolution.total)}`
+ : `${formatNumber(resolution.effectiveBase)} BASE x ${formatNumber(resolution.effectiveMult)} MULT x ${formatNumber(resolution.finalMultiplier)} FINAL = +${formatNumber(resolution.total)}`
+
+ return (
+ <details className="min-w-0 text-sm" data-testid="score-equation">
+ <summary className="cursor-pointer list-none truncate font-bold text-text-hi">
+ <span className="text-text-mid">SCORE </span>{equation}
+ </summary>
+ <div className="mt-2 max-h-24 overflow-y-auto border-l-2 border-acc-violet pl-3 text-xs leading-5 text-text-mid">
+ {resolution.trace.map((step) => (
+ <div className="flex min-w-0 items-baseline justify-between gap-3" key={step.id}>
+ <span className="min-w-0 break-words">{step.label}</span>
+ <span className="shrink-0 tabular-nums text-text-hi">{formatNumber(step.after)}</span>
+ </div>
+ ))}
+ {resolution.itemImpacts.length > 0 && (
+ <div className="mt-1 break-words text-acc-cyan">
+ {resolution.itemImpacts.map((impact) => `${impact.itemId} +${formatNumber(impact.scoreDelta)} ${impact.kind}`).join(" / ")}
+ </div>
+ )}
+ </div>
+ </details>
+ )
+}
diff --git a/features/overdrive/frame-clock.ts b/features/overdrive/frame-clock.ts
new file mode 100644
index 0000000..bd71c15
--- /dev/null
+++ b/features/overdrive/frame-clock.ts
@@ -0,0 +1,4 @@
+export function elapsedFrameMs(now: number, previous: number) {
+ if (!Number.isFinite(now) || !Number.isFinite(previous)) return 0
+ return Math.max(0, now - previous)
+}
diff --git a/features/overdrive/persisted-run-writer.ts b/features/overdrive/persisted-run-writer.ts
new file mode 100644
index 0000000..6c3dfa7
--- /dev/null
+++ b/features/overdrive/persisted-run-writer.ts
@@ -0,0 +1,48 @@
+export type PersistedRunWriterOptions = {
+ delayMs?: number
+ serialize: () => string | null
+ save: (serialized: string) => void
+ schedule: (callback: () => void, delayMs: number) => unknown
+ cancel: (handle: unknown) => void
+}
+
+export function createPersistedRunWriter({
+ delayMs = 750,
+ serialize,
+ save,
+ schedule,
+ cancel,
+}: PersistedRunWriterOptions) {
+ let pending: unknown = null
+ let disposed = false
+
+ function flush() {
+ if (disposed) return
+ if (pending !== null) {
+ cancel(pending)
+ pending = null
+ }
+ const serialized = serialize()
+ if (serialized !== null) save(serialized)
+ }
+
+ function scheduleWrite() {
+ if (disposed || pending !== null) return
+ pending = schedule(() => {
+ pending = null
+ flush()
+ }, delayMs)
+ }
+
+ function dispose() {
+ if (pending !== null) cancel(pending)
+ pending = null
+ disposed = true
+ }
+
+ return {
+ schedule: scheduleWrite,
+ flush,
+ dispose,
+ }
+}
diff --git a/features/overdrive/presentation/__tests__/events.test.ts b/features/overdrive/presentation/__tests__/events.test.ts
index 4088640..ed2ff9c 100644
--- a/features/overdrive/presentation/__tests__/events.test.ts
+++ b/features/overdrive/presentation/__tests__/events.test.ts
@@ -2,7 +2,6 @@ import { describe, expect, it } from "vitest"
import {
emitLegacyPresentationEvent as emitPresentationEvent,
getPresentationEvents,
- subscribePresentationEvents,
resetPresentationEventsForTests,
} from "../events"
diff --git a/features/overdrive/presentation/scheduler.ts b/features/overdrive/presentation/scheduler.ts
index f100860..a267824 100644
--- a/features/overdrive/presentation/scheduler.ts
+++ b/features/overdrive/presentation/scheduler.ts
@@ -92,8 +92,6 @@ export function createPresentationScheduler(opts: SchedulerOptions): Presentatio
}
function drain(nowMs: number): readonly PresentationBeat[] {
- const active: PresentationBeat[] = []
-
// Process drops
const nextPending: PresentationBeat[] = []
for (const beat of pendingBeats) {
diff --git a/features/overdrive/store-transition.ts b/features/overdrive/store-transition.ts
new file mode 100644
index 0000000..1e2d4ac
--- /dev/null
+++ b/features/overdrive/store-transition.ts
@@ -0,0 +1,22 @@
+import type { RunSnapshot } from "@/lib/engine/overdrive"
+
+function sameArray(left: readonly string[], right: readonly string[]) {
+ return left.length === right.length && left.every((value, index) => value === right[index])
+}
+
+export function isTimerOnlyTransition(before: RunSnapshot, after: RunSnapshot) {
+ return before.screen === after.screen
+ && before.score === after.score
+ && before.caretIndex === after.caretIndex
+ && before.tokens === after.tokens
+ && before.currentWord === after.currentWord
+ && before.wordDirty === after.wordDirty
+ && before.overdriveCharge === after.overdriveCharge
+ && before.targetOrdinal === after.targetOrdinal
+ && before.aegisRescues === after.aegisRescues
+ && before.stageRescued === after.stageRescued
+ && before.zone === after.zone
+ && before.stage === after.stage
+ && sameArray(before.keycaps, after.keycaps)
+ && sameArray(before.macros, after.macros)
+}
diff --git a/features/overdrive/store.ts b/features/overdrive/store.ts
index b9c1dcd..31bf794 100644
--- a/features/overdrive/store.ts
+++ b/features/overdrive/store.ts
@@ -20,6 +20,7 @@ import {
emitPresentationEvent,
} from "./presentation/events"
import { presentationHealth } from "./presentation/telemetry"
+import { isTimerOnlyTransition } from "./store-transition"
export const OVERDRIVE_SAVE_KEY = "typecade_overdrive_save"
export const OVERDRIVE_BRIEFING_KEY = "typecade_overdrive_briefing_seen"
@@ -93,6 +94,19 @@ export const useGame = create<GameStore>((set, get) => {
api,
armedItemIds: api.previewItemTriggers(),
})
+ const syncTimer = () => {
+ const snapshot = api.snapshot()
+ set({
+ api,
+ focusPaused: snapshot.focusPaused,
+ timeLeftMs: snapshot.timeLeftMs,
+ runDurationMs: snapshot.runDurationMs,
+ accuracy: snapshot.accuracy,
+ runAccuracy: snapshot.runAccuracy,
+ wpm: snapshot.wpm,
+ averageWpm: snapshot.averageWpm,
+ })
+ }
const transition = (action: () => void) => {
const before = api.snapshot()
action()
@@ -280,7 +294,13 @@ export const useGame = create<GameStore>((set, get) => {
api.feedChar = (character) => transition(() => raw.feedChar(character))
api.releaseOverdrive = () => transition(raw.releaseOverdrive)
api.backspace = () => transition(raw.backspace)
- api.advance = (ms) => transition(() => raw.advance(ms))
+ api.advance = (ms) => {
+ const before = api.snapshot()
+ raw.advance(ms)
+ const after = api.snapshot()
+ if (isTimerOnlyTransition(before, after)) syncTimer()
+ else sync()
+ }
api.continueToNextStage = () => {
transition(raw.continueToNextStage)
const snapshot = api.snapshot()
@@ -486,6 +506,8 @@ export const useGame = create<GameStore>((set, get) => {
})
return true
} catch {
+ window.localStorage.removeItem(OVERDRIVE_SAVE_KEY)
+ set({ resumeAvailable: false })
return false
}
},
diff --git a/features/overdrive/use-persisted-run.ts b/features/overdrive/use-persisted-run.ts
index 2ba5915..41eee51 100644
--- a/features/overdrive/use-persisted-run.ts
+++ b/features/overdrive/use-persisted-run.ts
@@ -2,6 +2,7 @@
import { useEffect } from "react"
import type { RunSnapshot } from "@/lib/engine/overdrive"
+import { createPersistedRunWriter } from "./persisted-run-writer"
import { OVERDRIVE_SAVE_KEY, useGame } from "./store"
const RESUMABLE_SCREENS: RunSnapshot["screen"][] = [
@@ -29,6 +30,12 @@ function hasResumableSave() {
export function usePersistedRun() {
useEffect(() => {
+ const writer = createPersistedRunWriter({
+ serialize: () => useGame.getState().api?.exportState() ?? null,
+ save: (serialized) => window.localStorage.setItem(OVERDRIVE_SAVE_KEY, serialized),
+ schedule: (callback, delayMs) => window.setTimeout(callback, delayMs),
+ cancel: (handle) => window.clearTimeout(handle as number),
+ })
const updateResumeState = () => {
useGame.getState().setResumeAvailable(hasResumableSave())
}
@@ -37,21 +44,30 @@ export function usePersistedRun() {
const unsubscribe = useGame.subscribe((state, previous) => {
if (!state.api || state.screen === "menu") return
if (state.screen === "runOver") {
+ writer.flush()
window.localStorage.removeItem(OVERDRIVE_SAVE_KEY)
if (state.resumeAvailable) state.setResumeAvailable(false)
return
}
- if (
- state.screen === previous.screen
- && state.score === previous.score
- && state.caretIndex === previous.caretIndex
- && state.tokens === previous.tokens
- && state.timeLeftMs === previous.timeLeftMs
- ) return
-
- window.localStorage.setItem(OVERDRIVE_SAVE_KEY, state.api.exportState())
+ const semanticChange = state.screen !== previous.screen
+ || state.score !== previous.score
+ || state.caretIndex !== previous.caretIndex
+ || state.tokens !== previous.tokens
+ || state.paused !== previous.paused
+ const timerChange = state.timeLeftMs !== previous.timeLeftMs
+ if (!semanticChange && !timerChange) return
+ if (semanticChange) writer.flush()
+ else writer.schedule()
})
+ const flushOnPageLifecycle = () => writer.flush()
+ window.addEventListener("visibilitychange", flushOnPageLifecycle)
+ window.addEventListener("pagehide", flushOnPageLifecycle)
- return unsubscribe
+ return () => {
+ unsubscribe()
+ window.removeEventListener("visibilitychange", flushOnPageLifecycle)
+ window.removeEventListener("pagehide", flushOnPageLifecycle)
+ writer.dispose()
+ }
}, [])
}
diff --git a/features/typing/components/classic-typing-area.tsx b/features/typing/components/classic-typing-area.tsx
index af1c13c..725ebb6 100644
--- a/features/typing/components/classic-typing-area.tsx
+++ b/features/typing/components/classic-typing-area.tsx
@@ -44,6 +44,7 @@ export function ClassicTypingView({ activeTab, subOption, customText, customShuf
const duration = mode === "time" ? limit : 60;
const addTestResult = useStore(state => state.addTestResult);
+ const setLastTestCompletedAt = useStore(state => state.setLastTestCompletedAt);
const setIsTyping = useStore(state => state.setIsTyping);
const pendingResultRef = useRef<{ wpm: number; acc: number; timeTaken: number } | null>(null);
@@ -91,6 +92,7 @@ export function ClassicTypingView({ activeTab, subOption, customText, customShuf
isFocused,
onFinish: (finalWpm, finalAcc, timeTaken) => {
addTestResult({ wpm: finalWpm, accuracy: finalAcc, duration: timeTaken, mode: `${activeTab} ${subOption} ` });
+ setLastTestCompletedAt(Date.now());
pendingResultRef.current = { wpm: finalWpm, acc: finalAcc, timeTaken };
setResultKey(prev => prev + 1);
void saveResult(finalWpm, finalAcc, timeTaken).then((ok) => {
diff --git a/features/typing/components/typing-area.tsx b/features/typing/components/typing-area.tsx
index ddc80df..e459508 100644
--- a/features/typing/components/typing-area.tsx
+++ b/features/typing/components/typing-area.tsx
@@ -48,7 +48,9 @@ export function TypingView({ activeTab, subOption, customText, customShuffle }:
const duration = mode === "time" ? limit : 60;
const addTestResult = useStore(state => state.addTestResult);
+ const setLastTestCompletedAt = useStore(state => state.setLastTestCompletedAt);
const setIsTyping = useStore(state => state.setIsTyping);
+ const isTyping = useStore(state => state.isTyping);
const activeCharRef = useRef<HTMLSpanElement>(null);
const [translateY, setTranslateY] = useState(0);
@@ -101,6 +103,7 @@ export function TypingView({ activeTab, subOption, customText, customShuffle }:
isFocused,
onFinish: (finalWpm, finalAcc, timeTaken) => {
addTestResult({ wpm: finalWpm, accuracy: finalAcc, duration: timeTaken, mode: `${activeTab} ${subOption} ` });
+ setLastTestCompletedAt(Date.now());
pendingResultRef.current = { wpm: finalWpm, acc: finalAcc, timeTaken };
setResultKey(prev => prev + 1);
void saveResult(finalWpm, finalAcc, timeTaken).then((ok) => {
@@ -411,19 +414,23 @@ export function TypingView({ activeTab, subOption, customText, customShuffle }:
const index = globalIndex + cIdx;
const typedChar = typedChars[index];
- let charStatusClass = "text-text-dim/40";
+ let charStatusClass = "text-text-dim/65";
if (typedChar != null) {
if (typedChar === char) {
charStatusClass = "text-foreground";
} else if (typedChar === " " && char !== " ") {
// "Skipped" indicator: Underline instead of red text
- charStatusClass = "text-text-dim/40 border-b-2 border-error-text/80";
+ charStatusClass = "text-text-dim/65 border-b-2 border-error-text/80";
} else {
charStatusClass = "text-error-text bg-error-bg/50 rounded-sm";
}
}
const isCurrent = index === typedChars.length;
+ // Blinking caret bar on the next char to type. The bar
+ // disappears while typing (so it doesn't fight the actual
+ // keyboard caret) and reappears when the user pauses.
+ const showCaret = isCurrent && !isTyping;
return (
<span
@@ -432,6 +439,12 @@ export function TypingView({ activeTab, subOption, customText, customShuffle }:
className={`relative transition-colors duration-75 ${charStatusClass}`}
>
{char}
+ {showCaret && (
+ <span
+ aria-hidden
+ className="absolute left-0 top-0 bottom-0 w-[2px] bg-accent animate-caret-blink pointer-events-none"
+ />
+ )}
</span>
);
});
@@ -440,7 +453,7 @@ export function TypingView({ activeTab, subOption, customText, customShuffle }:
const spaceTyped = typedChars[spaceIndex];
const isSpaceCurrent = spaceIndex === typedChars.length;
- let spaceStatusClass = "text-text-dim/40";
+ let spaceStatusClass = "text-text-dim/65";
if (spaceTyped != null) {
if (spaceTyped === " ") {
spaceStatusClass = "text-foreground";
@@ -549,19 +562,19 @@ export function TypingView({ activeTab, subOption, customText, customShuffle }:
</div>
{/* Typing Area */}
- <div className="w-full relative mt-4">
+ <div className="w-full relative mt-2 sm:mt-4">
<div className="w-full relative rounded-3xl">
<div
- className="w-full font-mono text-xl sm:text-2xl leading-[1.8] tracking-tight text-left py-2 sm:py-4 relative cursor-default select-none text-text-dim/80"
+ className="w-full font-mono text-2xl sm:text-3xl md:text-4xl leading-[1.85] tracking-[0.01em] text-left py-3 sm:py-6 relative cursor-default select-none text-text-dim/90"
onContextMenu={(e) => e.preventDefault()}
>
<div
ref={textContainerRef}
- className="h-[5.4em] overflow-hidden relative w-full"
+ className="h-[6em] overflow-hidden relative w-full"
style={{
- maskImage: "linear-gradient(to bottom, transparent 0%, black 8%, black 92%, transparent 100%)",
- WebkitMaskImage: "linear-gradient(to bottom, transparent 0%, black 8%, black 92%, transparent 100%)",
+ maskImage: "linear-gradient(to bottom, transparent 0%, black 6%, black 94%, transparent 100%)",
+ WebkitMaskImage: "linear-gradient(to bottom, transparent 0%, black 6%, black 94%, transparent 100%)",
}}
>
<div
diff --git a/features/typing/components/typing-results.tsx b/features/typing/components/typing-results.tsx
index ca811fc..b02d621 100644
--- a/features/typing/components/typing-results.tsx
+++ b/features/typing/components/typing-results.tsx
@@ -1,7 +1,7 @@
import React, { useRef, useEffect, useState } from 'react';
import { motion, AnimatePresence } from 'framer-motion';
import { CountUp } from '@/components/ui/count-up';
-import { RotateCcw, ArrowRight, Download, Twitter, Send } from 'lucide-react';
+import { RotateCcw, ArrowRight, Download, Twitter, Send, Linkedin, Copy, Check, Share2 } from 'lucide-react';
import { Button } from '@/components/ui/button';
import confetti from 'canvas-confetti';
import * as htmlToImage from 'html-to-image';
@@ -18,9 +18,25 @@ interface TypingResultsProps {
onNext: () => void;
}
+// Encode the current result into the short /r/<slug> format. The matching
+// decoder lives in app/r/[slug]/page.tsx — keep the two in sync if you
+// change either side.
+function buildResultSlug(wpm: number, accuracy: number, modeLabel: string): string {
+ const modes = ["Time 15s", "Time 30s", "Time 60s", "Time 120s", "Words 10", "Words 25", "Words 50", "Words 100", "Quote"];
+ const idx = modes.indexOf(modeLabel);
+ return `w${Math.round(wpm)}a${Math.round(accuracy)}m${idx >= 0 ? idx : 2}`;
+}
+
export function TypingResults({ wpm, accuracy, mode, limit, typedCharsLength, resultKey, onRetry, onNext }: TypingResultsProps) {
const cardRef = useRef<HTMLDivElement>(null);
const [isCapturing, setIsCapturing] = useState(false);
+ const [copied, setCopied] = useState(false);
+ const [canNativeShare, setCanNativeShare] = useState(false);
+
+ useEffect(() => {
+ // Detect Web Share API support (mostly mobile Safari/Android Chrome).
+ setCanNativeShare(typeof navigator !== 'undefined' && 'share' in navigator);
+ }, []);
// We assume store.stats.wpm holds the all-time personal best WPM
const personalBestWpm = useStore(state => state.stats.wpm);
@@ -98,14 +114,55 @@ export function TypingResults({ wpm, accuracy, mode, limit, typedCharsLength, re
};
const handleTwitterShare = () => {
- const text = `I just typed ${wpm} WPM with ${accuracy}% accuracy on @typecade! \n\nCan you beat my score? Try it now: https://typecade.com`;
- window.open(`https://twitter.com/intent/tweet?text=${encodeURIComponent(text)}`, '_blank');
- };
+ const slug = buildResultSlug(wpm, accuracy, mode);
+ const url = `https://typecade.com/r/${slug}`;
+ const text = `I just typed ${wpm} WPM with ${accuracy}% accuracy on @typecade (${mode})!\n\nCan you beat my score? ${url}`;
+ window.open(`https://twitter.com/intent/tweet?text=${encodeURIComponent(text)}`, '_blank');
+ };
- const handleWhatsAppShare = () => {
- const text = `I just typed ${wpm} WPM with ${accuracy}% accuracy on Typecade! \nCan you beat my score? https://typecade.com`;
- window.open(`https://api.whatsapp.com/send?text=${encodeURIComponent(text)}`, '_blank');
- };
+ const handleWhatsAppShare = () => {
+ const slug = buildResultSlug(wpm, accuracy, mode);
+ const url = `https://typecade.com/r/${slug}`;
+ const text = `I just typed ${wpm} WPM with ${accuracy}% accuracy on Typecade (${mode})!\nCan you beat my score? ${url}`;
+ window.open(`https://api.whatsapp.com/send?text=${encodeURIComponent(text)}`, '_blank');
+ };
+
+ const handleLinkedInShare = () => {
+ const slug = buildResultSlug(wpm, accuracy, mode);
+ const url = `https://typecade.com/r/${slug}`;
+ window.open(`https://www.linkedin.com/sharing/share-offsite/?url=${encodeURIComponent(url)}`, '_blank');
+ };
+
+ const handleCopyLink = async () => {
+ const slug = buildResultSlug(wpm, accuracy, mode);
+ const url = `https://typecade.com/r/${slug}`;
+ try {
+ await navigator.clipboard.writeText(url);
+ setCopied(true);
+ setTimeout(() => setCopied(false), 2000);
+ } catch {
+ // Fallback: select-and-prompt
+ window.prompt("Copy your result link:", url);
+ }
+ };
+
+ const handleNativeShare = async () => {
+ const slug = buildResultSlug(wpm, accuracy, mode);
+ const url = `https://typecade.com/r/${slug}`;
+ if (typeof navigator !== 'undefined' && 'share' in navigator) {
+ try {
+ await navigator.share({
+ title: `${wpm} WPM on Typecade`,
+ text: `I just typed ${wpm} WPM with ${accuracy}% accuracy. Can you beat my score?`,
+ url,
+ });
+ } catch {
+ // user cancelled or share not available — ignore
+ }
+ } else {
+ handleCopyLink();
+ }
+ };
return (
<motion.div
@@ -216,18 +273,35 @@ export function TypingResults({ wpm, accuracy, mode, limit, typedCharsLength, re
</Button>
</div>
- {/* Share Actions - Smaller and compact */}
- <div className="flex flex-wrap gap-2 justify-center w-full border-t border-foreground/5 pt-4 sm:pt-6">
- <Button variant="ghost" onClick={handleDownloadShare} className="gap-2 text-text-dim hover:text-foreground text-xs py-1 h-8" title="Download Screenshot">
- <Download size={14} /> Save Image
- </Button>
- <Button variant="ghost" onClick={handleTwitterShare} className="gap-2 text-text-dim hover:text-[#1DA1F2] text-xs py-1 h-8" title="Share your result on X">
- <Twitter size={14} /> Tweet
- </Button>
- <Button variant="ghost" onClick={handleWhatsAppShare} className="gap-2 text-text-dim hover:text-[#25D366] text-xs py-1 h-8" title="Send to WhatsApp">
- <Send size={14} /> WhatsApp
- </Button>
- </div>
+ {/* Share Actions - Compact row */}
+ <div className="flex flex-wrap gap-2 justify-center w-full border-t border-foreground/5 pt-4 sm:pt-6">
+ <Button variant="ghost" onClick={handleDownloadShare} className="gap-2 text-text-dim hover:text-foreground text-xs py-1 h-8" title="Download Screenshot">
+ <Download size={14} /> Save Image
+ </Button>
+ <Button variant="ghost" onClick={handleTwitterShare} className="gap-2 text-text-dim hover:text-[#1DA1F2] text-xs py-1 h-8" title="Share your result on X">
+ <Twitter size={14} /> Tweet
+ </Button>
+ <Button variant="ghost" onClick={handleLinkedInShare} className="gap-2 text-text-dim hover:text-[#0A66C2] text-xs py-1 h-8" title="Share on LinkedIn">
+ <Linkedin size={14} /> LinkedIn
+ </Button>
+ <Button variant="ghost" onClick={handleWhatsAppShare} className="gap-2 text-text-dim hover:text-[#25D366] text-xs py-1 h-8" title="Send to WhatsApp">
+ <Send size={14} /> WhatsApp
+ </Button>
+ <Button
+ variant="ghost"
+ onClick={handleCopyLink}
+ className="gap-2 text-text-dim hover:text-foreground text-xs py-1 h-8"
+ title="Copy a shareable link to this result"
+ >
+ {copied ? <Check size={14} className="text-green-400" /> : <Copy size={14} />}
+ {copied ? "Copied!" : "Copy link"}
+ </Button>
+ {canNativeShare && (
+ <Button variant="ghost" onClick={handleNativeShare} className="gap-2 text-text-dim hover:text-foreground text-xs py-1 h-8" title="Share via your device">
+ <Share2 size={14} /> Share
+ </Button>
+ )}
+ </div>
</div>
</motion.div>
);
diff --git a/lib/engine/__tests__/rng.test.ts b/lib/engine/__tests__/rng.test.ts
index 8f5de39..10e3f11 100644
--- a/lib/engine/__tests__/rng.test.ts
+++ b/lib/engine/__tests__/rng.test.ts
@@ -56,4 +56,17 @@ describe('RNG (Mulberry32)', () => {
// words and shop should NOT match each other
expect(words1.next()).not.toBe(shop1.next());
});
+
+ it('round-trips internal state for deterministic continuation', () => {
+ const original = createRng('state-round-trip');
+ original.next();
+ original.next();
+ const savedState = original.exportState();
+
+ const restored = createRng('state-round-trip');
+ restored.importState(savedState);
+
+ expect(restored.next()).toBe(original.next());
+ expect(restored.next()).toBe(original.next());
+ });
});
diff --git a/lib/engine/overdrive/__tests__/items.test.ts b/lib/engine/overdrive/__tests__/items.test.ts
index 56091c0..6dbede0 100644
--- a/lib/engine/overdrive/__tests__/items.test.ts
+++ b/lib/engine/overdrive/__tests__/items.test.ts
@@ -137,6 +137,31 @@ describe("MVP item system", () => {
})
})
+ it("stores the score resolution used by score equation UI", () => {
+ const api = createRun({
+ seed: "score-resolution",
+ words: ["abcdefgh"],
+ startingKeycaps: ["longshot"],
+ })
+ let resolution = null as NonNullable<ReturnType<typeof api.snapshot>["lastScoreResolution"]> | null
+ api.events.on("word_complete", (payload) => {
+ resolution = payload.scoreResolution
+ })
+
+ api.start()
+ typeCurrentWord(api)
+
+ expect(resolution).toMatchObject({
+ word: "abcdefgh",
+ characterBase: 8,
+ effectiveBase: 16,
+ total: 16,
+ itemImpacts: [{ itemId: "longshot", kind: "base", scoreDelta: 8 }],
+ })
+ expect(api.snapshot().lastScoreResolution).toEqual(resolution)
+ expect(api.snapshot().lastScoreResolution?.trace.map((step) => step.id)).toContain("item-base")
+ })
+
it("does not leak transient WASD and Sprinter bonuses between words", () => {
const wasd = createRun({
seed: "wasd-scope",
diff --git a/lib/engine/overdrive/__tests__/run.test.ts b/lib/engine/overdrive/__tests__/run.test.ts
index 3d7f125..c973f7d 100644
--- a/lib/engine/overdrive/__tests__/run.test.ts
+++ b/lib/engine/overdrive/__tests__/run.test.ts
@@ -340,7 +340,6 @@ describe("run state machine", () => {
it("skips Warm-up for one token and starts Rush cleanly", () => {
const api = createRun({ seed: "skip", words })
api.start()
- typeCurrentWord(api)
api.skipWarmup()
expect(api.snapshot()).toMatchObject({
@@ -352,6 +351,19 @@ describe("run state machine", () => {
})
})
+ it("does not allow Warm-up skip after input has started", () => {
+ const api = createRun({ seed: "skip-after-input", words })
+ api.start()
+ typeCurrentWord(api)
+ api.skipWarmup()
+
+ expect(api.snapshot()).toMatchObject({
+ screen: "stage",
+ stage: "warmup",
+ tokens: 0,
+ })
+ })
+
it("round-trips an active run through versioned persistence", () => {
const api = createRun({ seed: "save", words, startingKeycaps: ["wasd"] })
api.start()
@@ -364,4 +376,35 @@ describe("run state machine", () => {
expect(restored.snapshot()).toEqual(api.snapshot())
expect(restored.loadState('{"version":999}')).toBe(false)
})
+
+ it("continues identically after restoring seeded RNG streams", () => {
+ const options = {
+ seed: "resume-continuation",
+ words: ["abc", "def", "ghi", "jkl"],
+ startingZone: 7,
+ }
+ const uninterrupted = createRun(options)
+ uninterrupted.start()
+ typeCurrentWord(uninterrupted)
+ const saved = uninterrupted.exportState()
+
+ const restored = createRun(options)
+ expect(restored.loadState(saved)).toBe(true)
+
+ for (let index = 0; index < 24; index += 1) {
+ typeCurrentWord(uninterrupted)
+ typeCurrentWord(restored)
+ expect(restored.snapshot()).toEqual(uninterrupted.snapshot())
+ }
+ })
+
+ it("rejects saves containing unknown item ids", () => {
+ const api = createRun({ seed: "invalid-item-save", words })
+ api.start()
+ const saved = JSON.parse(api.exportState()) as { state: RunSnapshot }
+ saved.state.keycaps = ["not-a-keycap"]
+
+ const restored = createRun({ seed: "invalid-item-save", words })
+ expect(restored.loadState(JSON.stringify(saved))).toBe(false)
+ })
})
diff --git a/lib/engine/overdrive/events.ts b/lib/engine/overdrive/events.ts
index 9cce566..3abd6a4 100644
--- a/lib/engine/overdrive/events.ts
+++ b/lib/engine/overdrive/events.ts
@@ -1,4 +1,4 @@
-import type { ItemContribution, StageType } from "./types"
+import type { ItemContribution, ScoreResolution, StageType } from "./types"
export type EngineEvents = {
word_complete: {
@@ -14,6 +14,7 @@ export type EngineEvents = {
autoExecuted: boolean
appliedItemIds: string[]
combo: number
+ scoreResolution: ScoreResolution
}
typo: { expected: string; got: string; ignored: boolean }
character_accepted: {
diff --git a/lib/engine/overdrive/run-input.ts b/lib/engine/overdrive/run-input.ts
index ea58a03..ded92c0 100644
--- a/lib/engine/overdrive/run-input.ts
+++ b/lib/engine/overdrive/run-input.ts
@@ -5,6 +5,11 @@ import {
OVERDRIVE_TYPO_DRAIN,
} from "./constants"
import { GLITCHES, KEYCAPS } from "./items"
+import type {
+ ScoreItemImpact,
+ ScoreResolution,
+ ScoreTraceStep,
+} from "./types"
import type {
TypoContext,
WordPreviewContext,
@@ -55,6 +60,139 @@ export function previewItemTriggers(ctx: RunContext): string[] {
return triggered
}
+function scoreItemImpacts(
+ itemIds: readonly string[],
+ baselineScore: number,
+ scoreGain: number,
+ context: {
+ baseBonus: number
+ baseMultiplier: number
+ multAdd: number
+ multMultiplier: number
+ finalMultiplier: number
+ },
+): ScoreItemImpact[] {
+ if (itemIds.length === 0) return []
+ const scoreDelta = Math.max(0, scoreGain - baselineScore)
+ if (scoreDelta <= 0) return []
+ const kind = context.finalMultiplier !== 1
+ ? "final"
+ : context.multAdd !== 0 || context.multMultiplier !== 1
+ ? "mult"
+ : "base"
+ const share = scoreDelta / itemIds.length
+ return itemIds.map((itemId) => ({ itemId, kind, scoreDelta: share }))
+}
+
+function scoreResolution({
+ word,
+ characterBase,
+ itemBaseBonus,
+ effectiveBase,
+ effectiveMult,
+ finalMultiplier,
+ total,
+ aegisRecovery,
+ overdriveReleased,
+ appliedItemIds,
+ baselineScore,
+ context,
+}: {
+ word: string
+ characterBase: number
+ itemBaseBonus: number
+ effectiveBase: number
+ effectiveMult: number
+ finalMultiplier: number
+ total: number
+ aegisRecovery: boolean
+ overdriveReleased: boolean
+ appliedItemIds: readonly string[]
+ baselineScore: number
+ context: {
+ baseBonus: number
+ baseMultiplier: number
+ multAdd: number
+ multMultiplier: number
+ finalMultiplier: number
+ }
+}): ScoreResolution {
+ const trace: ScoreTraceStep[] = []
+ let cursor = characterBase
+ trace.push({
+ id: "word-base",
+ label: "Word base",
+ source: "word",
+ operation: "add",
+ before: 0,
+ after: cursor,
+ })
+ if (itemBaseBonus !== 0 || context.baseMultiplier !== 1) {
+ const next = effectiveBase
+ trace.push({
+ id: "item-base",
+ label: "Keycap base",
+ source: "item",
+ operation: context.baseMultiplier !== 1 ? "multiply" : "add",
+ before: cursor,
+ after: next,
+ })
+ cursor = next
+ }
+ if (aegisRecovery) {
+ trace.push({
+ id: "aegis-base-only",
+ label: "Aegis recovery",
+ source: "aegis",
+ operation: "floor",
+ before: cursor,
+ after: total,
+ })
+ } else {
+ const multiplied = effectiveBase * effectiveMult
+ trace.push({
+ id: "combo-mult",
+ label: "Combo Mult",
+ source: "combo",
+ operation: "multiply",
+ before: effectiveBase,
+ after: multiplied,
+ })
+ if (finalMultiplier !== 1 || overdriveReleased) {
+ trace.push({
+ id: "final-mult",
+ label: overdriveReleased ? "Overdrive final" : "Final Mult",
+ source: overdriveReleased ? "overdrive" : "item",
+ operation: "multiply",
+ before: multiplied,
+ after: multiplied * finalMultiplier,
+ })
+ }
+ trace.push({
+ id: "score-floor",
+ label: "Score floor",
+ source: "word",
+ operation: "floor",
+ before: effectiveBase * effectiveMult * finalMultiplier,
+ after: total,
+ })
+ }
+
+ return {
+ word,
+ characterBase,
+ itemBaseBonus,
+ effectiveBase,
+ effectiveMult,
+ finalMultiplier,
+ total,
+ aegisRecovery,
+ overdriveReleased,
+ trace,
+ itemImpacts: scoreItemImpacts(appliedItemIds, baselineScore, total, context),
+ }
+}
+
function submitWord(
ctx: RunContext,
lifecycle: InputLifecycle,
@@ -121,6 +259,21 @@ function submitWord(
recordScoreImpact(ctx, appliedItemIds, Math.max(0, scoreGain - baselineScore))
if (releasesOverdrive) ctx.state.overdriveCharge = 0
+ const resolvedScore = scoreResolution({
+ word: ctx.state.currentWord,
+ characterBase: ctx.state.currentWord.length,
+ itemBaseBonus: contextBase.baseBonus,
+ effectiveBase: modifiedBase,
+ effectiveMult: aegisRecovery ? 1 : effectiveMult,
+ finalMultiplier: aegisRecovery ? 1 : contextBase.finalMultiplier,
+ total: scoreGain,
+ aegisRecovery,
+ overdriveReleased: releasesOverdrive,
+ appliedItemIds,
+ baselineScore,
+ context: contextBase,
+ })
+ ctx.state.lastScoreResolution = resolvedScore
const resolvedBase = {
...contextBase,
@@ -146,6 +299,7 @@ function submitWord(
autoExecuted: ctx.state.zone === 1,
appliedItemIds: [...appliedItemIds],
combo: ctx.state.combo,
+ scoreResolution: resolvedScore,
})
if (releasesOverdrive) {
ctx.events.emit("overdrive_released", {
diff --git a/lib/engine/overdrive/run-lifecycle.ts b/lib/engine/overdrive/run-lifecycle.ts
index 9bed11f..2d8c590 100644
--- a/lib/engine/overdrive/run-lifecycle.ts
+++ b/lib/engine/overdrive/run-lifecycle.ts
@@ -75,6 +75,7 @@ export function startStage(ctx: RunContext) {
ctx.state.caretIndex = 0
ctx.state.stageItemImpact = {}
ctx.state.tokenBreakdown = undefined
+ ctx.state.lastScoreResolution = undefined
ctx.state.glitchState = null
ctx.state.currentWord = getBuildBiasedWord(ctx)
ctx.state.upcomingWords = Array.from({ length: 8 }, () => getBuildBiasedWord(ctx))
@@ -123,7 +124,12 @@ export function startRun(ctx: RunContext) {
}
export function skipWarmup(ctx: RunContext) {
- if (ctx.state.screen !== "stage" || ctx.state.stage !== "warmup") return
+ if (
+ ctx.state.screen !== "stage"
+ || ctx.state.stage !== "warmup"
+ || ctx.stageAttemptedChars > 0
+ || ctx.stageElapsedMs > 0
+ ) return
ctx.state.tokens += WARMUP_SKIP_REWARD
ctx.state.stage = "rush"
startStage(ctx)
diff --git a/lib/engine/overdrive/run-state.ts b/lib/engine/overdrive/run-state.ts
index 9b5939b..b5698f2 100644
--- a/lib/engine/overdrive/run-state.ts
+++ b/lib/engine/overdrive/run-state.ts
@@ -5,6 +5,7 @@ import type {
ItemImpact,
RunMode,
RunSnapshot,
+ ScoreResolution,
StageType,
ThreatBand,
WordPoolLanguage,
@@ -18,7 +19,7 @@ import {
import { getStageQuota } from "./progression"
import { createRng } from "../rng"
import type { RNG } from "../rng"
-import { KEYCAPS, MACROS } from "./items"
+import { GLITCHES, KEYCAPS, MACROS } from "./items"
import type { BaseItemContext, RuntimeData } from "./items/registry"
export const MAX_KEYCAPS = 5
@@ -74,6 +75,13 @@ export type RunContext = {
type SavedRun = {
version: number
state: RunSnapshot
+ rngState?: {
+ root: number
+ words: number
+ shop: number
+ glitch: number
+ }
+ recentWords?: string[]
runItemData: RuntimeData[]
stageItemData: RuntimeData[]
naturalMult: number
@@ -167,6 +175,7 @@ function createInitialSnapshot(
glitchState: null,
stageItemImpact: {},
runItemImpact: {},
+ lastScoreResolution: undefined,
}
}
@@ -280,6 +289,7 @@ export function resetRunSnapshot(ctx: RunContext) {
glitchState: null,
stageItemImpact: {},
runItemImpact: {},
+ lastScoreResolution: undefined,
}
}
@@ -293,6 +303,15 @@ export function cloneImpactMap(source: Record<string, ItemImpact>): Record<strin
)
}
+function cloneScoreResolution(resolution: ScoreResolution | undefined): ScoreResolution | undefined {
+ if (!resolution) return undefined
+ return {
+ ...resolution,
+ trace: resolution.trace.map((step) => ({ ...step })),
+ itemImpacts: resolution.itemImpacts.map((impact) => ({ ...impact })),
+ }
+}
+
export function snapshotRun(ctx: RunContext): RunSnapshot {
const state = ctx.state
return {
@@ -305,6 +324,7 @@ export function snapshotRun(ctx: RunContext): RunSnapshot {
stageItemImpact: cloneImpactMap(state.stageItemImpact),
runItemImpact: cloneImpactMap(state.runItemImpact),
tokenBreakdown: state.tokenBreakdown ? { ...state.tokenBreakdown } : undefined,
+ lastScoreResolution: cloneScoreResolution(state.lastScoreResolution),
}
}
@@ -452,10 +472,84 @@ function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value)
}
+function isFiniteNumber(value: unknown): value is number {
+ return typeof value === "number" && Number.isFinite(value)
+}
+
+function isRuntimeData(value: unknown): value is RuntimeData {
+ if (!isRecord(value)) return false
+ return Object.values(value).every((entry) => (
+ typeof entry === "boolean"
+ || typeof entry === "string"
+ || isFiniteNumber(entry)
+ ))
+}
+
+function isRngState(value: unknown): value is NonNullable<SavedRun["rngState"]> {
+ return isRecord(value)
+ && ["root", "words", "shop", "glitch"].every((key) => {
+ const state = value[key]
+ return isFiniteNumber(state)
+ && Number.isInteger(state)
+ && state >= 0
+ && state <= 0xFFFFFFFF
+ })
+}
+
+function hasKnownIds(
+ value: unknown,
+ registry: Record<string, unknown>,
+ allowEmpty = false,
+): value is string[] {
+ return Array.isArray(value)
+ && value.every((id) => (
+ typeof id === "string"
+ && (allowEmpty && id === "" || Boolean(registry[id]))
+ ))
+}
+
+function isValidSavedRun(value: unknown): value is SavedRun {
+ if (!isRecord(value) || value.version !== SAVE_VERSION || !isRecord(value.state)) return false
+ const state = value.state
+ const numericStateFields = [
+ "zone", "timeLeftMs", "stageDurationMs", "aegisRescues", "overdriveCharge",
+ "targetOrdinal", "score", "runScore", "standardScore", "endlessScore", "quota",
+ "combo", "maxCombo", "mult", "tokens", "totalTokensEarned", "accuracy",
+ "runAccuracy", "wpm", "averageWpm", "cleanWords", "totalCleanWords", "highestMult",
+ "stageTypos", "totalTypos", "runDurationMs", "caretIndex",
+ ]
+ if (numericStateFields.some((field) => !isFiniteNumber(state[field]))) return false
+ if (!isFiniteNumber(state.zone) || !Number.isInteger(state.zone) || state.zone < 1) return false
+ if (!isFiniteNumber(state.caretIndex) || !Number.isInteger(state.caretIndex) || state.caretIndex < 0) return false
+ if (typeof state.seed !== "string" || typeof state.currentWord !== "string") return false
+ if (!hasKnownIds(state.keycaps, KEYCAPS) || !hasKnownIds(state.macros, MACROS)) return false
+ if (!hasKnownIds(state.shopKeycaps, KEYCAPS, true)) return false
+ if (state.shopMacro !== null && (typeof state.shopMacro !== "string" || !MACROS[state.shopMacro])) return false
+ if (state.activeGlitch !== null && (typeof state.activeGlitch !== "string" || !GLITCHES[state.activeGlitch])) return false
+ if (!Array.isArray(state.upcomingWords) || state.upcomingWords.length > 8 || !state.upcomingWords.every((word: unknown) => typeof word === "string")) return false
+ if (state.glitchState !== null && !isRuntimeData(state.glitchState)) return false
+ if (!Array.isArray(value.runItemData) || !value.runItemData.every(isRuntimeData)) return false
+ if (!Array.isArray(value.stageItemData) || !value.stageItemData.every(isRuntimeData)) return false
+ if (value.runItemData.length !== state.keycaps.length || value.stageItemData.length !== state.keycaps.length) return false
+ if (["naturalMult", "stageAttemptedChars", "stageCorrectChars", "runAttemptedChars", "runCorrectChars", "stageElapsedMs", "stageIdleMs"]
+ .some((field) => !isFiniteNumber(value[field]))) return false
+ if (value.recentWords !== undefined && (!Array.isArray(value.recentWords) || value.recentWords.length > 30)) return false
+ if (value.recentWords?.some((word) => typeof word !== "string")) return false
+ if (value.rngState !== undefined && !isRngState(value.rngState)) return false
+ return true
+}
+
export function exportRunState(ctx: RunContext): string {
const save: SavedRun = {
version: SAVE_VERSION,
state: snapshotRun(ctx),
+ rngState: {
+ root: ctx.rootRng.exportState(),
+ words: ctx.wordsRng.exportState(),
+ shop: ctx.shopRng.exportState(),
+ glitch: ctx.glitchRng.exportState(),
+ },
+ recentWords: [...ctx.recentWords],
runItemData: ctx.runItemData,
stageItemData: ctx.stageItemData,
naturalMult: ctx.scorer.mult,
@@ -474,12 +568,8 @@ export function exportRunState(ctx: RunContext): string {
export function loadRunState(ctx: RunContext, json: string): boolean {
try {
const parsed: unknown = JSON.parse(json)
- if (
- !isRecord(parsed)
- || parsed.version !== SAVE_VERSION
- || !isRecord(parsed.state)
- ) return false
- const save = parsed as unknown as SavedRun
+ if (!isValidSavedRun(parsed)) return false
+ const save = parsed
const savedStage = save.state.stage ?? ctx.state.stage
const savedZone = Number(save.state.zone ?? ctx.state.zone)
const savedEndless = Boolean(save.state.endless)
@@ -505,6 +595,13 @@ export function loadRunState(ctx: RunContext, json: string): boolean {
}
ctx.runItemData = save.runItemData.map((data) => ({ ...data }))
ctx.stageItemData = save.stageItemData.map((data) => ({ ...data }))
+ if (save.rngState) {
+ ctx.rootRng.importState(save.rngState.root)
+ ctx.wordsRng.importState(save.rngState.words)
+ ctx.shopRng.importState(save.rngState.shop)
+ ctx.glitchRng.importState(save.rngState.glitch)
+ }
+ ctx.recentWords = [...(save.recentWords ?? [])]
ctx.scorer = createScorer({ combo: ctx.state.combo, mult: save.naturalMult })
ctx.stageAttemptedChars = save.stageAttemptedChars
ctx.stageCorrectChars = save.stageCorrectChars
diff --git a/lib/engine/overdrive/types.ts b/lib/engine/overdrive/types.ts
index dfc5f23..adb0e76 100644
--- a/lib/engine/overdrive/types.ts
+++ b/lib/engine/overdrive/types.ts
@@ -26,6 +26,39 @@ export type ItemImpact = {
protections: number
}
+export type ScoreTraceOperation = "add" | "multiply" | "floor"
+
+export type ScoreTraceSource = "word" | "item" | "combo" | "overdrive" | "aegis"
+
+export type ScoreTraceStep = {
+ id: string
+ label: string
+ source: ScoreTraceSource
+ operation: ScoreTraceOperation
+ before: number
+ after: number
+}
+
+export type ScoreItemImpact = {
+ itemId: string
+ kind: "base" | "mult" | "final"
+ scoreDelta: number
+}
+
+export type ScoreResolution = {
+ word: string
+ characterBase: number
+ itemBaseBonus: number
+ effectiveBase: number
+ effectiveMult: number
+ finalMultiplier: number
+ total: number
+ aegisRecovery: boolean
+ overdriveReleased: boolean
+ trace: ScoreTraceStep[]
+ itemImpacts: ScoreItemImpact[]
+}
+
export type RunSnapshot = {
screen: Screen
mode: RunMode
@@ -79,6 +112,7 @@ export type RunSnapshot = {
glitchState: Record<string, boolean | number | string> | null
stageItemImpact: Record<string, ItemImpact>
runItemImpact: Record<string, ItemImpact>
+ lastScoreResolution?: ScoreResolution
}
export type ItemContribution = {
diff --git a/lib/engine/rng.ts b/lib/engine/rng.ts
index 405c82d..6d23d1d 100644
--- a/lib/engine/rng.ts
+++ b/lib/engine/rng.ts
@@ -7,6 +7,10 @@ export interface RNG {
shuffle: <T>(array: T[]) => T[];
/** Creates a new independent RNG sequence deterministically branched from this one */
fork: (label: string) => RNG;
+ /** Exports the current 32-bit generator state for deterministic persistence */
+ exportState: () => number;
+ /** Restores a previously exported 32-bit generator state */
+ importState: (state: number) => void;
}
/** FNV-1a hash to convert a string seed into a 32-bit integer */
@@ -54,5 +58,16 @@ export function createRng(seed: string): RNG {
return createRng(`${seed}:${label}:${state}`);
}
- return { next, pick, shuffle, fork };
+ function exportState() {
+ return state >>> 0;
+ }
+
+ function importState(nextState: number) {
+ if (!Number.isInteger(nextState) || nextState < 0 || nextState > 0xFFFFFFFF) {
+ throw new Error("RNG state must be an unsigned 32-bit integer");
+ }
+ state = nextState | 0;
+ }
+
+ return { next, pick, shuffle, fork, exportState, importState };
}
diff --git a/lib/overdrive/server/__tests__/daily-seed.test.ts b/lib/overdrive/server/__tests__/daily-seed.test.ts
new file mode 100644
index 0000000..97d6ddf
--- /dev/null
+++ b/lib/overdrive/server/__tests__/daily-seed.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest"
+import { deriveDailySeed } from "../daily-seed"
+
+describe("daily seed derivation", () => {
+ it("is stable for the same server secret and board identity", async () => {
+ const first = await deriveDailySeed("server-secret", "2026-08-10", "EN", "rules-v1")
+ const second = await deriveDailySeed("server-secret", "2026-08-10", "EN", "rules-v1")
+
+ expect(first).toBe(second)
+ })
+
+ it("changes when the board identity changes", async () => {
+ const first = await deriveDailySeed("server-secret", "2026-08-10", "EN", "rules-v1")
+ const second = await deriveDailySeed("server-secret", "2026-08-11", "EN", "rules-v1")
+
+ expect(first).not.toBe(second)
+ })
+})
diff --git a/lib/overdrive/server/daily-seed.ts b/lib/overdrive/server/daily-seed.ts
new file mode 100644
index 0000000..9a3f361
--- /dev/null
+++ b/lib/overdrive/server/daily-seed.ts
@@ -0,0 +1,13 @@
+export async function deriveDailySeed(
+ secret: string,
+ runDate: string,
+ language: "EN" | "ID",
+ rulesetVersion: string,
+) {
+ const material = `${secret}:${runDate}:${language}:${rulesetVersion}`
+ const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(material))
+ const hex = [...new Uint8Array(digest)]
+ .map((byte) => byte.toString(16).padStart(2, "0"))
+ .join("")
+ return `daily-v1-${hex.slice(0, 32)}`
+}
diff --git a/lib/store.ts b/lib/store.ts
index 4c219e6..e9961d5 100644
--- a/lib/store.ts
+++ b/lib/store.ts
@@ -49,7 +49,12 @@ interface TypecadeState {
showAnimations: boolean;
isTyping: boolean;
authModalOpen: boolean;
-
+
+ // Tracks when the most recent typing test finished (unix ms).
+ // Used by the navbar to swap "Sign in" → "Save progress" right after
+ // a visitor completes a test, when saving actually matters.
+ lastTestCompletedAt: number | null;
+
// Actions
setActiveTab: (tab: ModeOption) => void;
setSubOption: (option: string) => void;
@@ -75,6 +80,7 @@ interface TypecadeState {
showUI: boolean;
setShowUI: (val: boolean) => void;
addTestResult: (result: { wpm: number; accuracy: number; duration: number; mode: string }) => void;
+ setLastTestCompletedAt: (ts: number | null) => void;
}
// Generate some dummy history
@@ -111,6 +117,7 @@ export const useStore = create<TypecadeState>()(
showAnimations: true,
isTyping: false,
authModalOpen: false,
+ lastTestCompletedAt: null,
stats: {
wpm: 94,
accuracy: 98.2,
@@ -144,6 +151,7 @@ export const useStore = create<TypecadeState>()(
setAuthModalOpen: (authModalOpen) => set({ authModalOpen }),
showUI: true,
setShowUI: (showUI) => set({ showUI }),
+ setLastTestCompletedAt: (lastTestCompletedAt) => set({ lastTestCompletedAt }),
addTestResult: (result) => set((state) => {
const newHistory = [
{
diff --git a/lib/supabase/admin.ts b/lib/supabase/admin.ts
new file mode 100644
index 0000000..695224a
--- /dev/null
+++ b/lib/supabase/admin.ts
@@ -0,0 +1,15 @@
+import "server-only"
+import { createClient } from "@supabase/supabase-js"
+import type { SupabaseClient } from "@supabase/supabase-js"
+import type { Database } from "./database.types"
+
+export function getSupabaseAdminClient(): SupabaseClient<Database> {
+ const url = process.env.NEXT_PUBLIC_SUPABASE_URL ?? ""
+ const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY ?? ""
+ if (!url || !serviceRoleKey) {
+ throw new Error("Supabase server configuration is incomplete")
+ }
+ return createClient<Database>(url, serviceRoleKey, {
+ auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },
+ })
+}
diff --git a/lib/supabase/client.ts b/lib/supabase/client.ts
index 11ba302..a820670 100644
--- a/lib/supabase/client.ts
+++ b/lib/supabase/client.ts
@@ -1,19 +1,60 @@
import { createClient, SupabaseClient } from "@supabase/supabase-js";
+import type { Database } from "./database.types";
+
+/**
+ * Singleton Supabase client for the browser.
+ *
+ * Three guard rails here:
+ * 1. Returns null if either env var is missing — call sites handle this
+ * as "no signed-in features" rather than throwing.
+ * 2. Returns null if the URL doesn't look like a Supabase project
+ * (`https://<ref>.supabase.co`). This catches:
+ * - empty/placeholder URLs from a fresh `.env.local` clone
+ * - the rare case where the project was deleted and the URL now
+ * fails DNS — without this guard the auth-js client would log
+ * an unhelpful "Failed to fetch" on every page load.
+ * 3. Validates the anon key looks like a JWT (three dot-separated
+ * base64 segments). Empty / placeholder values would silently work
+ * for `createClient` but fail every request — better to fail loud
+ * at startup.
+ */
const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL ?? "";
const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY ?? "";
-let supabaseClient: SupabaseClient | null = null;
+function looksLikeSupabaseUrl(url: string): boolean {
+ if (!url) return false;
+ try {
+ const parsed = new URL(url);
+ if (parsed.protocol !== "https:") return false;
+ // Supabase project URLs always end in .supabase.co (or
+ // .supabase.in for older projects; both accepted).
+ return /(?:^|\.)supabase\.(?:co|in)$/i.test(parsed.hostname);
+ } catch {
+ return false;
+ }
+}
+
+function looksLikeJwt(token: string): boolean {
+ if (!token) return false;
+ const parts = token.split(".");
+ return parts.length === 3 && parts.every((p) => p.length > 0);
+}
+
+export const isSupabaseConfigured: boolean =
+ looksLikeSupabaseUrl(supabaseUrl) && looksLikeJwt(supabaseAnonKey);
+
+let supabaseClient: SupabaseClient<Database> | null = null;
-export const getSupabaseClient = () => {
+export const getSupabaseClient = (): SupabaseClient | null => {
if (supabaseClient) return supabaseClient;
- if (!supabaseUrl || !supabaseAnonKey) return null;
- supabaseClient = createClient(supabaseUrl, supabaseAnonKey, {
+ if (!isSupabaseConfigured) return null;
+ supabaseClient = createClient<Database>(supabaseUrl, supabaseAnonKey, {
auth: {
persistSession: true,
autoRefreshToken: true,
- detectSessionInUrl: true
- }
+ detectSessionInUrl: true,
+ },
});
return supabaseClient;
};
diff --git a/lib/supabase/database.types.ts b/lib/supabase/database.types.ts
new file mode 100644
index 0000000..0d37607
--- /dev/null
+++ b/lib/supabase/database.types.ts
@@ -0,0 +1,110 @@
+export type Json = string | number | boolean | null | { [key: string]: Json | undefined } | Json[]
+
+export type Database = {
+ public: {
+ Tables: {
+ daily_seeds: {
+ Row: {
+ id: number
+ run_date: string
+ language: "EN" | "ID"
+ ruleset_version: string
+ rng_version: string
+ word_pool_version: string
+ seed: string
+ created_at: string
+ }
+ Insert: Omit<Database["public"]["Tables"]["daily_seeds"]["Row"], "id" | "created_at">
+ Update: Partial<Database["public"]["Tables"]["daily_seeds"]["Insert"]>
+ Relationships: []
+ }
+ runs: {
+ Row: {
+ id: number
+ public_id: string
+ client_run_id: string
+ user_id: string | null
+ mode: "daily" | "free"
+ status: "started" | "submitted" | "accepted" | "verified" | "rejected"
+ run_date: string | null
+ seed: string
+ language: "EN" | "ID"
+ ruleset_version: string
+ rng_version: string
+ word_pool_version: string
+ client_version: string
+ win: boolean | null
+ final_zone: number | null
+ final_stage: "warmup" | "rush" | "glitch" | null
+ standard_score: number | null
+ endless_score: number | null
+ final_score: number | null
+ duration_ms: number | null
+ accuracy_bps: number | null
+ average_wpm_x100: number | null
+ total_typos: number | null
+ max_combo: number | null
+ highest_mult: number | null
+ build: Json
+ replay_sha256: string | null
+ rejection_code: string | null
+ started_at: string
+ submitted_at: string | null
+ verified_at: string | null
+ created_at: string
+ updated_at: string
+ }
+ Insert: Omit<Database["public"]["Tables"]["runs"]["Row"], "id" | "public_id" | "started_at" | "created_at" | "updated_at">
+ Update: Partial<Database["public"]["Tables"]["runs"]["Insert"]>
+ Relationships: []
+ }
+ leaderboard_entries: {
+ Row: {
+ id: number
+ run_id: number
+ run_public_id: string
+ user_id: string
+ display_name: string
+ board: "daily" | "endless"
+ board_date: string | null
+ language: "EN" | "ID"
+ ruleset_version: string
+ score: number
+ final_zone: number
+ accuracy_bps: number
+ average_wpm_x100: number
+ build_fingerprint: Json
+ verification_state: "accepted" | "verified"
+ finished_at: string
+ created_at: string
+ }
+ Insert: Omit<Database["public"]["Tables"]["leaderboard_entries"]["Row"], "id" | "created_at">
+ Update: Partial<Database["public"]["Tables"]["leaderboard_entries"]["Insert"]>
+ Relationships: []
+ }
+ replays: {
+ Row: {
+ id: number
+ run_id: number
+ user_id: string | null
+ codec_version: number
+ storage_key: string
+ byte_length: number
+ input_count: number
+ sha256: string
+ verification_state: "pending" | "verified" | "rejected"
+ verification_code: string | null
+ created_at: string
+ verified_at: string | null
+ }
+ Insert: Omit<Database["public"]["Tables"]["replays"]["Row"], "id" | "created_at">
+ Update: Partial<Database["public"]["Tables"]["replays"]["Insert"]>
+ Relationships: []
+ }
+ }
+ Views: Record<string, never>
+ Functions: Record<string, never>
+ enums: Record<string, never>
+ CompositeTypes: Record<string, never>
+ }
+}
diff --git a/lib/supabase/error-handler.ts b/lib/supabase/error-handler.ts
new file mode 100644
index 0000000..c21316a
--- /dev/null
+++ b/lib/supabase/error-handler.ts
@@ -0,0 +1,58 @@
+/**
+ * Centralized Supabase error classification + tuning constants.
+ *
+ * Free-tier Supabase projects auto-pause after ~7 days of inactivity and take
+ * 1-2 minutes to wake up on the next request. During that window, queries
+ * return errors that the UI previously swallowed silently, making the app look
+ * broken (empty leaderboards, empty rooms, missing profile). This module lets
+ * call sites detect that specific condition and surface a helpful message.
+ */
+
+/** Polling interval for the lobby room list (ms). 30s is a good balance of
+ * freshness vs Supabase resource usage on the free tier. */
+export const LOBBY_POLL_INTERVAL_MS = 30_000;
+
+/** Polling interval for the leaderboard (ms). Leaderboards rarely change fast. */
+export const BOARD_POLL_INTERVAL_MS = 60_000;
+
+type SupabaseErrorLike = {
+ message?: string;
+ code?: string | number;
+};
+
+/**
+ * Returns true if the given Supabase error looks like the database is paused,
+ * waking up, or otherwise temporarily unreachable.
+ */
+export function isSupabaseUnavailable(error: SupabaseErrorLike | null | undefined): boolean {
+ if (!error) return false;
+ const message = (error.message ?? "").toLowerCase();
+ const code = String(error.code ?? "");
+
+ // Supabase pause / wake-up signals
+ if (message.includes("project is paused")) return true;
+ if (message.includes("project paused")) return true;
+ if (message.includes("waking up")) return true;
+ if (message.includes("connection terminated")) return true;
+ if (message.includes("fetch failed")) return true;
+ if (message.includes("network request failed")) return true;
+ if (message.includes("networkerror")) return true;
+ if (message.includes("econnrefused")) return true;
+ if (message.includes("econnreset")) return true;
+ if (message.includes("timeout")) return true;
+ if (code === "PGRST301" || code === "503") return true; // service unavailable
+
+ return false;
+}
+
+/**
+ * Convenience alias — most call sites care about "should we show the
+ * 'database is waking up' banner?". Same logic as isSupabaseUnavailable.
+ */
+export function classifySupabaseError(error: SupabaseErrorLike | null | undefined): boolean {
+ return isSupabaseUnavailable(error);
+}
+
+/** Human-friendly copy for the unavailable banner / toast. */
+export const SUPABASE_UNAVAILABLE_MESSAGE =
+ "The database is waking up from sleep. This usually takes 1-2 minutes — please wait or refresh shortly.";
diff --git a/lib/supabase/server-auth.ts b/lib/supabase/server-auth.ts
new file mode 100644
index 0000000..a142c8e
--- /dev/null
+++ b/lib/supabase/server-auth.ts
@@ -0,0 +1,25 @@
+import "server-only"
+import { createClient } from "@supabase/supabase-js"
+import type { User } from "@supabase/supabase-js"
+import type { Database } from "./database.types"
+
+function getConfig() {
+ const url = process.env.NEXT_PUBLIC_SUPABASE_URL ?? ""
+ const key = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
+ ?? process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
+ if (!url || !key) return null
+ return { url, key }
+}
+
+export async function getAuthenticatedUser(request: Request): Promise<User | null> {
+ const authorization = request.headers.get("authorization")
+ if (!authorization?.startsWith("Bearer ")) return null
+ const config = getConfig()
+ if (!config) return null
+
+ const client = createClient<Database>(config.url, config.key, {
+ auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },
+ })
+ const { data, error } = await client.auth.getUser(authorization.slice("Bearer ".length))
+ return error ? null : data.user
+}
diff --git a/lib/supabase/server.ts b/lib/supabase/server.ts
deleted file mode 100644
index 991c5d6..0000000
--- a/lib/supabase/server.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-import { createClient } from "@supabase/supabase-js";
-
-const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL ?? "";
-const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY ?? "";
-
-export const getSupabaseServerClient = () => {
- if (!supabaseUrl || !supabaseAnonKey) return null;
- return createClient(supabaseUrl, supabaseAnonKey, {
- auth: {
- persistSession: false,
- autoRefreshToken: false,
- detectSessionInUrl: false
- }
- });
-};
diff --git a/public/api/ping.html b/public/api/ping.html
new file mode 100644
index 0000000..410d0b1
--- /dev/null
+++ b/public/api/ping.html
@@ -0,0 +1,30 @@
+<!--
+ Typecade — External Keep-Alive Endpoint
+ ----------------------------------------
+ Halaman statis ini ada untuk di-ping oleh uptime monitor eksternal
+ (UptimeRobot / cron-job.org) yang melakukan fetch ke Supabase REST API.
+
+ CARA PAKAI:
+ 1. Setup UptimeRobot (gratis, https://uptimerobot.com):
+ - Monitor Type: HTTP(s)
+ - URL Friendly Name: Typecade Supabase Keep-Alive
+ - URL: https://YOUR-PROJECT.supabase.co/rest/v1/keepalive_log?select=id&limit=1&apikey=YOUR_ANON_KEY
+ - Monitoring Interval: 3600 minutes (1 jam) atau 1440 minutes (1 hari)
+ (ganti YOUR-PROJECT dan YOUR_ANON_KEY dengan nilai asli)
+
+ Ini mengirim 1 request HTTP ke Supabase tiap jam → terhitung sebagai
+ aktivitas REST eksternal → mencegah auto-pause 7-hari.
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <title>Typecade Keep-Alive
+
+
+
+
Typecade Keep-Alive
+
This page exists so external uptime monitors can ping Supabase and prevent the free-tier 7-day auto-pause.
+
See supabase/migrations/0001_keepalive_cron.sql for setup instructions.