TOEIC　vocabulary　Lab (toeic_website_ver2.0)

TOEIC語彙ラボ is a comprehensive web application for learning essential TOEIC vocabulary, featuring AI-generated explanations, pronunciation support, and efficient caching strategies.

🚀 Features

• Content Error Reports and Social Metadata: Every available word explanation includes an email report link with the word and canonical URL prefilled, plus a contact-page fallback. Home Open Graph and Twitter titles/descriptions match its page metadata and retain share images. robots.txt keeps crawl rules and the sitemap URL without the unused Host directive. (Updated: 2026-10-02)

• Study Audio Controls: Study/review word and example-sentence audio buttons use 44×44px targets, 20px icons, blue styling, and visible keyboard focus. The example button sits beside the sentence instead of inline, so wrapped sentences keep even line spacing.

• Consistent Difficulty Labels: Level UI uses 最重要 / 中級 / 上級 and shared blue / violet / rose styles across home, search, daily picks, and word details. Labels, score guidance, and styling come from the shared level definitions.

• Accessible Favorites Confirmation: Clear-all uses a native modal dialog with initial focus on Cancel, Escape dismissal, and browser-managed background interaction blocking. Cancel restores focus to the trigger; successful deletion focuses the empty-state message.

• Inline Audio Recovery: Word details and study/review cards show audio fetch/playback errors near the affected control with an explicit retry button. New playback clears the error; stale requests are ignored after switching audio, cards, or pages. Study word requests use the canonical slug (including uppercase terms such as CEO), and scope changes clear loading/error/retry state so revisiting a card remains playable.

• Consistent Term Search: Home, all-words, and favorites share NFKC/case/whitespace normalization and exact-match-first prefix ordering. Home and all-words also share * wildcard matching, including full-width ＊; favorites retain prefix-only search.

• Home Search Recovery: Empty word-search results show spelling/prefix guidance, a clear button that restores input focus and the first page, and a link to the meaning-search tab. (Updated: 2026-09-26)

• Initial-load resources: The UI uses system fonts without Geist downloads/preloads. A8 banners and their tracking pixels use native lazy loading, retaining their dimensions to reserve layout space.

• Curated Word Lists: Access 1,300+ important TOEIC vocabulary words classified into three levels (Important / Medium / High), sourced from Vercel Blob in production. Blob fetch failures throw (instead of returning an empty list) so a transient outage never gets cached as an empty word list — the last good cache keeps serving.

• SEO-Optimized Learning Hub: /words combines a score/letter/prefix search explorer with a server-rendered complete index. The complete index keeps every word available through a crawlable <a href> while nesting level → initial-letter groups in native <details> disclosure panels, so the mobile page is scannable without sacrificing the internal-link graph.

• Google Search Site Name: Google-facing site-name signals use TOEIC語彙ラボ (WebSite.name, og:site_name, and application-name), while page titles keep the established TOEIC重要単語 product name. The homepage uses the factual 2026年版 label rather than claiming unverified “latest test trends.”

• Snappy List → Detail Navigation: Word links use prefetch={false} (Vercel Edge Request reduction) and the detail route is fully SSG, which together cause the static RSC payload to render with the Suspense boundary already resolved (so loading.tsx never visibly fires). Interactive explorer cards wrap WordLinkPending (useLinkStatus) for instant click feedback; the 1,300+ links in the complete SEO index remain plain Server Component links to avoid creating a client boundary for every word.

• AI-Powered Explanations: Detailed definitions, synonyms, and examples generated by Google Gemini (gemini-2.5-flash-lite).

• Adaptive Word-Detail Disclosures: A word's primary Japanese translation always stays visible, while dense supporting content can be collapsed. Every native <details> panel is expanded on initial page display and starts with an explicit 「閉じる」action; after the user closes one, its one-line preview, item count, and 「見る」action keep the hidden content discoverable. Short sections remain permanently visible without adding an unnecessary interaction. The pure length/count rules live in src/lib/word-detail-disclosure.ts and keep the behavior consistent across AI-generated payloads.

• Smart Caching:

  • L1: Next.js Data Cache ("use cache" + cacheLife("max"), revalidated on demand via /api/revalidate/*) for instant access.
  • L2: Upstash Redis for persistent, shared caching across users.
  • L3: On-demand AI generation for missing words.

• Semantic Search（意味で探す）: The /words explorer has a second search tab that finds words by meaning — Japanese queries like「延期する」or「感謝を伝えるメールで使う単語」work. Each word's AI-generated WordDetails (definitions, synonyms, examples) is embedded as one document with gemini-embedding-001 (768 dims, L2-normalized) and stored in Upstash Vector; queries are embedded the same way and matched via cosine top-K (POST /api/search/semantic). Candidates below the configurable similarity threshold (default 0.82) are omitted. Results are cached in Redis for 7 days using both the normalized-query hash and a Vector-index generation; bulk or per-word vector updates advance the generation so stale results stop being addressable immediately. Requests are rate-limited per IP and results link straight to /words/[slug]. The TOP page has a lightweight launcher card (SemanticSearchLauncher, titled「意味で探す」and placed below the daily picks, above the spelling-based word list) that transfers the query through same-tab sessionStorage and navigates with only an opaque launch ID (/words?mode=meaning&launch=...#word-explorer). The query text therefore stays out of Vercel request URLs and GA4 page_location; GA4 custom events also receive only query length, never the text. useSearchParams keeps the explorer synchronized with browser history, while an in-flight request map prevents React Strict Mode from issuing duplicate semantic-search requests.

• Study Modes:

  • List View: Browse words by level (Important / Medium / High), initial letter, prefix, and wildcard (*) search. /words initially renders 36 compact result cards with “load more”, while the complete A–Z index stays available below.
  • Study Mode: Flashcard-style learning. The front shows the word (with pronunciation audio and an optional example-sentence hint); “答えを見る” reveals the Japanese meaning, parts of speech, and an example with its translation, and only then can the learner grade it Remembered / Not Remembered / Later (the same button order as before). Grading unlocks only once the answer has loaded; if it fails to load, only Later and a retry stay available. Every grade advances to the next card on the same screen; the answer links to the full word detail. An in-session "review later" sidebar keeps deferred words.
  • Review Mode (Sign-In Required): Focus on words marked as favorites. Guests reaching /review — including by bookmark — get the shared FavoritePracticeLoginGate instead of a session; there is no guest fallback to the full favorites list.

• Today’s 6 Picks:

  • A compact “今日おすすめの6単語” section is shown on the TOP page.
  • All 6 words are displayed directly in the TOP section without a separate “view all” button.
  • Picks are determined by UTC date key + word slug hash, so the same day yields the same 6 words.
  • Selection logic lives server-side in getTodayRecommendedSelection() as a Cache Component ('use cache' + cacheLife('max')), which returns the picks together with their date key and an 8-character word-corpus version. The cache entry is tagged with both today-recommended-words and word-list, so a word-list revalidation also marks the derived daily selection stale. TOP / /today-words / /today-words/listen receive the same cached 6 words, refreshed once per day at JST 7:05 (UTC 22:05) via Vercel Cron (/api/revalidate/today-words). The pick count is the shared constant TODAY_WORDS_COUNT. getTodayRecommendedWords() is a thin uncached wrapper for callers that only need the words — the cache boundary stays on the selection function so there is only ever one cache entry.
  • On the TOP page, the daily picks, word-list/stat block, and FAQ block are each rendered behind their own <Suspense> boundary. The page shell no longer awaits the full word list before streaming, and each async block has a stable skeleton fallback to reduce layout shift.
  • Because cacheLife('max') never self-expires, the daily rotation depends solely on the Vercel Cron firing; the cron should be monitored, since a stalled cron freezes the same 6 words indefinitely. A time-based fallback ('days') is intentionally not combined with it to avoid double revalidation.
  • Word-detail navigation never calls the daily cache. Daily-picks links carry the displayed slug order as a JSON picks query. resolveTodayNavigation() validates the bounded, unique list against known words and preserves it through every previous/next link, even when the cached corpus version differs. Invalid or unavailable selections hide both navigation links and offer a return to /today-words; they never widen to the full word list. Valid legacy date/version links are upgraded to snapshots. No daily cache dependency is added to pre-rendered word pages.

• Listen-and-Repeat Mode (Beta) (/today-words/listen — open to everyone, /favorites/listen — sign-in required):

  • Hands-free auto-play of today's 6 words or favorite words: each word is read out as word → English example → Japanese example, then advances to the next word.
  • FavoritesListenClient is a thin state gate (guest → login gate, loading → skeleton, error → retry) and mounts FavoritesListenPlayer only once Supabase favorites are ready, so no TTS request is issued for a signed-out visitor.
  • Play / Pause / Skip-Prev / Skip-Next controls. A completion message is shown after the final selected word; pressing play again restarts from the top.
  • Internally, audio sequencing uses a ref-based state machine to guard against onended race conditions, and prefetches the current and next word's WordDetails for instant example previews.

• Favorites: Save difficult words for later review. Persisted in local storage via FavoritesContext for guests; synced to Supabase for signed-in users. Adding and browsing favorites never requires an account; only the favorites-powered review and listen modes do. On /favorites, signed-out visitors with at least one favorite see FavoritePracticeLoginCard (a single card linking to /login?next=/mypage) in place of the review/listen buttons.

  • /favorites has a prefix search box that filters the list by English term. Matching lives in the pure, unit-tested src/lib/word-search.ts (filterWordsByTermPrefix): input is NFKC-normalized, whitespace-collapsed, trimmed, and lowercased so full-width IME input still matches; exact matches come first and the newest-first order is otherwise kept. Substring and wildcard (*) matching are intentionally not supported here. The query never enters the URL or analytics. The bulk-delete button is labeled 「すべて削除」 so it is not mistaken for clearing the search, and it still removes every favorite behind the existing confirmation modal.
  • Local storage is subscribed to as an external store (src/lib/favorites-store.ts + useSyncExternalStore) rather than being loaded through a mount effect, so no setState happens inside an effect and SSR/hydration stays consistent via getServerSnapshot(). If browser storage is unavailable, an in-memory fallback keeps favorites usable for the current tab.
  • Remote favorites are tagged with both the user ID and an authentication epoch. This prevents stale Supabase state from an earlier login from hiding or overwriting favorites added while signed out, even when the same account signs back in and the refresh request fails.

• Optional Sign-In & Favorites Sync (Supabase): Google sign-in (/login) stays optional for the core experience — browsing, search, favorites (add/list), Study Mode, and the daily picks all work without an account. The favorites-powered review and listen modes and My Page require sign-in. The login page provides a TOP-page return button in both signed-in and signed-out states. While LOGIN_MAINTENANCE in src/lib/auth-maintenance.ts is true, signed-out visitors see a maintenance notice instead of the Google button and existing sessions keep working (see §10 of docs/operations/phase1-login-favorites-sync-setup.md). The TOP header uses one authentication control: it shows ログイン while signed out and automatically becomes マイページ after authentication, with sign-out beside it instead of rendering a separate “logged in” badge and duplicate My Page button. The login link keeps prefetch={false} and uses useLinkStatus for immediate inline feedback; /login/loading.tsx and the page-level <Suspense> boundary reuse a stable login-card skeleton through route loading, hydration, and the initial auth check. Signing in stores favorites in Supabase Postgres (RLS-protected favorites table) so they sync across devices. On first login, locally stored favorites are merged into the account (upsert with ignoreDuplicates), and local storage is cleared only after a successful merge. On sign-out, the account's favorites are copied back to local storage so they stay visible, tagged with the owner's user id so that a different account signing in on the same browser never inherits them. Auth state is resolved client-side (onAuthStateChange) to keep pages statically cacheable; the session cookie exchange happens in /auth/callback.

• My Page & Review Flow (Sign-In Required) (/mypage): A personal hub whose only job is to answer “what should I review today, and why now?”. Account information is deliberately minimal (avatar, display name, sign-out); the screen is dominated by the review flow for favorite words. Signed-in users get a Leitner-style schedule (1 / 3 / 7 / 14 / 30-day intervals) stored in Supabase (word_review_progress, learning_streaks, both RLS-protected), so the same due queue and streak follow them across devices. The page shows today's due count with a progress ring, a 🔥 streak / best-streak / weekly-reviewed row, a four-segment retention breakdown (untouched / learning / familiar / mastered), the most-forgotten words, and links into the existing favorites, listen, study, and daily-picks screens. A filtered review snapshots at most 10 slugs when the session starts, removes each graded slug without refilling from the backlog, and ends on a completion screen. Authenticated sessions use queue- and user-scoped sessionStorage keys, and the answer’s “詳しい解説を見る” link carries the original queue so returning from the word detail keeps the same session context. Grading is optimistic, writes a user-scoped retry outbox to local storage before sending, serializes sends per user so rapid grades cannot finish out of order, and removes pending data only after Supabase accepts it; failed writes are merged and retried on the next review mount or grade. Next-due dates are snapped to the start of a later JST day so a nightly learner does not drift by a day. Favorites are read strictly from Supabase for authenticated review flows: /mypage and signed-in review sessions wait for favoritesStatus === "ready"; a signed-in favorites read failure shows a retry state instead of exposing a possibly stale local snapshot. Guests hitting /mypage, /review, or /favorites/listen get a login gate whose sign-in flow always returns to /mypage, with links to everything that stays free; only a signed-in progress-fetch error still degrades /review?queue=due|weak to the full favorites list with a notice. /review session storage keys are therefore always user- and epoch-scoped. All scheduling rules are pure functions in src/lib/review-schedule.ts (unit-tested), with Supabase access isolated in src/lib/review-progress-repo.ts and src/hooks/useReviewProgress.ts. Auth stays client-side (the proxy matcher is unchanged) so the page shell remains statically prerendered.

• Single-Grade Review Detail Flow: Review Mode uses the same reveal-then-grade card as Study Mode, so each word is graded exactly once on the card and grading never leaves the session. Opening “詳しい解説を見る” before grading keeps the card ungraded; the detail-page return action “復習に戻る” brings the learner back to that same revealed card. Detail pages opened from Review Mode (from=review, with any queue or none) hide the previous/next word links, so learners cannot preview cards still waiting to be graded in the same session.

• Analytics Events: GA4 tracks settled word-explorer queries with the recommended search event (700 ms debounce, 2+ characters, duplicate suppression), semantic searches (semantic_search with query length and result count; the query text is not sent), level/letter/search-mode filters (words_filter), and detail opens (word_detail_open, with source: semantic_search for meaning-search results) in addition to existing favorite/share events. My Page adds mypage_view (due count, favorite count, streak), mypage_login_gate_view (login-gate exposure for guests), and mypage_cta_click (which review/learning entry point was taken). The favorites review/listen gate adds favorite_practice_gate_view and favorite_practice_gate_cta, both carrying feature (review / listen / card).

• Social Share: Share word details via Twitter, Facebook, and LINE (react-share), with GA4 event tracking.

• PWA Ready: Installable on mobile and desktop via manifest.ts.

• Dynamic OGP: Per-word Open Graph images generated on-the-fly via src/app/words/[word]/opengraph-image.tsx.

• CDN-Cached OG Images (Active CPU control): Under cacheComponents: true, metadata image routes are never prerendered — even a route with no data access stays dynamic (ƒ), export const revalidate is inert, and generateStaticParams does not help; the build's prerender-manifest.json lists zero OG routes. The word OG route therefore carries no generateStaticParams / dynamicParams = false: keeping them only doubled the build's static-generation set (1,422 → 2,798 pages) with per-word prerender attempts that emit nothing, measurably degrading local builds (static generation 9.1s → 28.2s, whole build 17s → 35s, macOS compressed memory 4.7 GB → 11.4 GB, swapins 14k → 201k). Unknown slugs are rejected inside the Function by the getWordBySlug check, which returns a bare 404 with OG_IMAGE_NOT_FOUND_CACHE_CONTROL instead of rasterizing a "Not Found" image. Since each image costs a Satori layout pass plus a resvg 1200×630 PNG rasterization, leaving this unaddressed burns Vercel Fluid Active CPU in proportion to request volume. Both OG routes therefore send OG_IMAGE_CACHE_CONTROL (src/lib/og-utils.ts), letting the CDN hold the PNG so the Function runs roughly once per edge instead of once per request. s-maxage is 30 days to match the word-detail cache (WORD_CACHE_TTL_DAYS, cacheLife("max")), with stale-while-revalidate covering expiry. loadGoogleFont is wrapped in 'use cache' and fetches one stable full-TTF URL shared by every OGP. It deliberately omits Google Fonts' text= parameter: that parameter produced a different cache key per word while returning the same roughly 7 MB font, duplicating identical data across 1,300+ entries and exhausting build memory.

• Outbound Timeouts & Selective Retries: External-call policy is centralized in src/lib/http-retry.ts, and every server/CLI outbound path has a timeout. fetchWithRetry keeps response decoding (json / text / arrayBuffer) inside the retry boundary and retries only statuses a resend can fix (408/425/500/502/503/504); 429 is deliberately excluded because Gemini and Google Cloud TTS are metered. Gemini SDK retries are disabled because SDK 1.50.x includes 429 and erases the final HTTP status; calls instead use retryWithTimeout, preserving ApiError.status and a fresh signal per attempt. Redis keeps one SDK network retry plus a short command timeout but does not replay ambiguous HTTP failures such as INCR. Upstash Vector uses a custom public requester so idempotent query/upsert/delete calls can retry selected HTTP 5xx while retaining their status. Vercel Blob list() is bounded separately with an AbortController. Route Handlers structurally classify SDK status / statusCode errors (429 → 429, 5xx → 502, timeout/abort → 504).

• Lean Proxy Matching: src/proxy.ts refreshes the Supabase Auth session, with the matcher minimized to /login and /auth/* to keep Vercel Middleware/Proxy execution usage low (auth state elsewhere is handled client-side).

• Static Pages: Includes About, Privacy, Terms, and Contact pages for better user trust and SEO. The Privacy Policy explicitly discloses Google AdSense / third-party ad vendors' Cookie usage and Google Analytics tracking, with opt-out links, in line with AdSense program policy requirements.

• Learning Guide Articles (/guide): 16 article records, of which 15 are currently published. The May 2026 public-test retrospective is retained for source review but excluded from the guide index, static params, sitemap, related links, and search indexing. Published guides use visible Rain bylines, optional linked references, and Article + BreadcrumbList JSON-LD; unsupported score guarantees, fixed forgetting percentages, and unverifiable frequency claims have been removed or qualified. The index lists articles newest-first.

• Cookie Consent: First-visit consent banner aligned with GA4 tracking. Consent is stored in a cookie and read server-side via CookieConsentGate; GoogleAnalyticsGate loads GA4 only after explicit acceptance. Both gates are wrapped in <Suspense> so the rest of the root layout remains cacheable.

• AdSense Preparation: Ownership meta tag and ads.txt are retained; Google ad scripts are disabled. Affiliate banners are independently opt-in via NEXT_PUBLIC_AFFILIATE_ADS_ENABLED=true. Search indexing does not depend on advertising. Draft guides return not-found. Fifteen guides include revised explanations and nine original exercises. Editorial word corrections take precedence over Redis and generation; review hashes distinguish AI checks from human approval. See reapplication plan and review procedure.

• Responsive Design: Optimized for desktop and mobile devices. Below 640px, word-detail audio/favorite buttons and home/favorites pagination have at least 44×44px tap targets; icon sizes and desktop sizing stay compact. (Updated: 2026-09-23)

• Stronger Page Backgrounds: The TOP, word index, sign-in, favorites, daily picks, listening, study, and review screens share a more visible blue radial background, while word-detail pages retain their distinct teal hue with increased saturation.

🛠️ Tech Stack

• Framework: Next.js 16.4.2 (App Router, reactCompiler: true, cacheComponents: true)
• Language: TypeScript
• UI: React 19, Tailwind CSS v4 (Utility-first CSS), Lucide React
• Compiler: React Compiler (babel-plugin-react-compiler) for automatic memoization
• Social: react-share
• AI: Google Gemini (@google/genai / GoogleGenAI) - models: gemini-2.5-flash-lite (word details), gemini-embedding-001 (semantic search embeddings)
• Database / Cache: Upstash Redis (@upstash/redis)
• Vector Search: Upstash Vector (@upstash/vector) - 768-dim cosine index for semantic word search
• Auth / User Data: Supabase (@supabase/supabase-js + @supabase/ssr) — Google sign-in and RLS-protected favorites sync
• Storage: Vercel Blob (@vercel/blob) - for word lists
• Analytics: Google Analytics 4 (via @next/third-parties), Vercel Analytics & Speed Insights
• Deployment: Vercel

🏁 Getting Started

Prerequisites

• Node.js 24+ (package.json requires >=24; CI uses Node.js 24)
• npm

Installation

1. Clone the repository

   git clone https://github.com/Rainnnnnnnn-maker/toeic_website_ver2.0.git
   cd toeic_website_ver2.0
   

2. Install dependencies

   npm ci
   

3. Environment Variables Copy .env.example to .env.local and configure the following variables:

   cp .env.example .env.local
   

   Variable	Description
   GEMINI_API_KEY	Google Gemini API Key for generating word details.
   TTS_API_KEY	Google Cloud Text-to-Speech API Key for audio.
   UPSTASH_REDIS_REST_URL	Upstash Redis REST URL.
   UPSTASH_REDIS_REST_TOKEN	Upstash Redis REST Token.
   UPSTASH_VECTOR_REST_URL	Upstash Vector REST URL (semantic search). The index must be created with 768 dimensions / cosine metric.
   UPSTASH_VECTOR_REST_TOKEN	Upstash Vector REST Token (semantic search).
   SEMANTIC_SEARCH_MIN_SCORE	(Optional) Minimum cosine-similarity score returned by semantic search (default: 0.82, range: 0–1).
   BLOB_READ_WRITE_TOKEN	Vercel Blob Token (for fetching word lists in production).
   BLOB_URL_IMPORTANT	(Optional) Direct URL for word.txt in Blob. Skips the Blob list call when set.
   BLOB_URL_MEDIUM	(Optional) Direct URL for word_mid.txt in Blob.
   BLOB_URL_HIGH	(Optional) Direct URL for word_high.txt in Blob.

Optional MCP Development Tools

The project-level .mcp.json configures Claude Code integrations for Next.js DevTools, Playwright, GitHub, and Upstash. GitHub and Upstash require the following environment variables in the shell that launches Claude Code; values in .env.local are not exported to the parent shell automatically.

Variable	Description
GITHUB_MCP_PAT	GitHub personal access token. Grant only the repository permissions required for the intended MCP operations.
UPSTASH_EMAIL	Email address associated with the Upstash account.
UPSTASH_API_KEY	Upstash account API key. Prefer a read-only key unless resource changes are explicitly required.

For example, export the values before starting Claude Code:

export GITHUB_MCP_PAT=<your-github-pat>
export UPSTASH_EMAIL=<your-upstash-email>
export UPSTASH_API_KEY=<your-upstash-api-key>
claude

Claude Code asks for approval before starting project-scoped MCP servers for the first time. Never commit credential values to .mcp.json or another tracked file.

📜 Scripts

• npm run dev: Starts the development server.
• npm run build: Builds the application for production.
• npm run start: Starts the production server.
• npm run lint: Runs ESLint.
• npm run test: Runs Vitest unit tests. These cover pure logic only (word selection/parsing, Gemini response normalization, TTS cache keys & example allowlist, listen-mode example fallback, favorites sync/auth-session selection, audit-report validation, study-mode word selection & persisted-state parsing, semantic-search query normalization / index-versioned cache keys / score filtering / embedding-document building / result parsing, stale-vector reconciliation guards, and outbound retry policy / timeout detection / upstream-failure status mapping) and run in CI alongside npm run lint. Cypress E2E tests cover guest favorites persistence and today-word navigation; other integration and UI changes still require manual smoke testing.
• npm run test:e2e:ci: Builds an isolated production app with local Blob/Redis HTTP fixtures, starts it, runs Cypress, and cleans up. No app secrets or local word files are needed. GitHub Actions runs this on Chrome.
• npm run test:e2e: Runs the Cypress browser tests against a running local server. npm run test:e2e:open opens the interactive runner; npm run typecheck:e2e checks the isolated Cypress TypeScript project. See E2E setup for prerequisites and scope.
• npm run embed:words: Embeds all WordDetails into Upstash Vector for semantic search (tsx --env-file=.env.local scripts/embed-words.ts). The word list is loaded through the same shared loader as the site (src/lib/word-source.ts), so the indexed corpus matches what is actually served — it defaults to Vercel Blob and only reads __words__/*.txt when NODE_ENV=development. Reads WordDetails from Redis first and generates missing ones with Gemini. Supports -- --dry-run, -- --limit=N, -- --only-cached, and -- --source=local|blob (explicit corpus override). After a complete successful Blob backfill, it ranges the Vector index and deletes word vectors whose IDs are no longer in the served corpus; pruning is skipped for limited, cached-only, local, or failed runs. It then advances the semantic-index generation, invalidating all prior result-cache keys without a Redis key scan. This is a standalone Node/tsx CLI, so it must not import Next.js's marker. Run once for the initial backfill and re-run after bulk word-list changes.

🚀 CI / Deployment

• Pushes and pull-request updates whose changed files are all *.sql skip the CI workflow. SQL-only pushes to non-main branches also skip the Vercel Preview workflow. A push containing any non-SQL source change still runs the workflows normally.
• Vercel Git Integration is enabled (git.deploymentEnabled: true). Pushes to the Vercel Production Branch automatically deploy to Production. The existing Preview push workflow and manual Production workflow also remain available, so Git integration and Actions can both deploy.
• The nodejs-e2e CI job runs the two Cypress flows on an isolated production build without service secrets. Failures upload build/server logs, screenshots, and videos for 7 days. Other CI jobs skip the Cypress binary download.
• CI and Vercel Git deployments run independently. Adding E2E does not automatically block Production promotion. Configure required PR checks / Vercel Deployment Checks separately if needed. Workflow paths-ignore rules do not disable Vercel Git deployments.

🔄 API Endpoints

Revalidate Word List Data

Triggers on-demand revalidation for cached word lists (tag: word-list). Useful when updating word lists in Vercel Blob.

• Endpoint: GET /api/revalidate/words

• Authentication: Requires token query parameter matching REVALIDATION_TOKEN.

• Usage:

  curl "https://<your-site>/api/revalidate/words?token=<REVALIDATION_TOKEN>"
  

Revalidate Specific Word Details

Clears L1 (Next.js Data Cache) for a specific word. To also clear L2 (Upstash Redis) cache, add the upstash=true parameter. This forces a fresh AI generation on the next request if both caches are cleared.

• Endpoint: GET /api/revalidate/word

• Authentication: Requires token query parameter matching REVALIDATION_TOKEN.

• Parameters:

  • slug (The word to revalidate)
  • upstash (Optional, set to true to also clear Upstash Redis cache)
  • vector (Optional, set to true to re-embed the word and upsert it into Upstash Vector after the caches are cleared, keeping semantic search in sync with the regenerated content. A successful upsert also advances the semantic-index generation so cached search results are invalidated immediately. Combine with upstash=true to force a full Gemini regeneration first.)

• Usage:

  curl "https://<your-site>/api/revalidate/word?token=<REVALIDATION_TOKEN>&slug=additional&upstash=true&vector=true"
  

Delete Upstash Word Cache Key (L2 Only)

Deletes a specific Upstash Redis key for word details (word:<slug>). This endpoint does not touch the Next.js Data Cache (L1).

• Endpoint: GET /api/revalidate/upstash-word

• Authentication: Requires token query parameter matching REVALIDATION_TOKEN.

• Parameters:

  • key (Must start with word:. Example: word:ability)

• Usage:

  curl "https://<your-site>/api/revalidate/upstash-word?token=<REVALIDATION_TOKEN>&key=word:ability"
  

Text-to-Speech

Generates audio for words or sentences.

• Endpoint: POST /api/tts
• Headers:
  • Content-Type: application/json
  • X-App-Source: toeic-client
• Body: { "text": "word or sentence", "language": "en" | "ja", "wordSlug": "<slug>" }
  • wordSlug is required for multi-word text or any Japanese text.
• Voices: en-US-Wavenet-C (English), ja-JP-Neural2-B (Japanese).
• API key handling: The server sends TTS_API_KEY to Google using the x-goog-api-key request header; it is never included in the request URL or returned to the browser.
• Allowlist:
  • Single English words must exist in the curated vocabulary list.
  • Example sentences must exactly match (after whitespace normalization) one of the cached WordDetails.toeicExamples or meanings[].detailedMeanings[].example entries for the given wordSlug. This blocks Referer-spoofing attacks from synthesizing arbitrary text against the Google Cloud TTS quota.
• Rate limit: 30 req/min per IP via Upstash Ratelimit (sliding window). Cached results bypass the counter.

Semantic Search

Finds vocabulary words by meaning (Japanese or English queries) via embedding similarity.

• Endpoint: POST /api/search/semantic
• Headers:
  • Content-Type: application/json
  • X-App-Source: toeic-client
• Body: { "query": "延期する" } (max 100 chars after normalization)
• Response: { "results": [{ "slug", "term", "level", "japaneseTranslation", "score" }], "cached": boolean } — up to 10 results in cosine-similarity order after applying the minimum-score filter.
• Relevance threshold: Results below SEMANTIC_SEARCH_MIN_SCORE are omitted (default 0.82). The UI deliberately does not label raw vector scores as percentages.
• Caching: Valid top-K candidates are cached in Redis (semsearch:v3:<indexVersion>:<sha256_16> of the NFKC-normalized query, 7-day TTL), and the current minimum-score filter is reapplied on every read so threshold changes take effect without a cache purge. npm run embed:words and successful /api/revalidate/word?...&vector=true updates increment semsearch:index-version, making earlier cache keys unreachable immediately. Cached queries bypass the rate limiter; an empty candidate set is not cached. If the index version cannot be read, the API bypasses the result cache.
• Privacy: The query is sent to Gemini to create its embedding. The Redis result-cache key contains only a SHA-256-derived prefix, and the semantic_search GA4 event sends only query length and result count—not the query text.
• Rate limit: 20 req/min per IP via Upstash Ratelimit (sliding window, prefix rl:semsearch).
• 503: Returned when UPSTASH_VECTOR_REST_URL / UPSTASH_VECTOR_REST_TOKEN are not configured.

Sitemap

Returns sitemap.xml containing all static pages and all word detail URLs.

• Endpoint: GET /api/sitemap
• Rewrite: /sitemap.xml → /api/sitemap (configured in next.config.ts).
• Indexable URLs only: noindex pages (/favorites, /review, /login, */listen) are excluded from the sitemap — listing a URL in the sitemap while its page says noindex sends Google contradictory signals.
• lastmod policy: Static pages and guide articles emit lastmod. URLs whose real modification date is not tracked (all /words/* detail pages, and the daily-rotating /today-words) omit lastmod — emitting one fixed, identical date trains Google to distrust the lastmod signal, so it is left out rather than faked. (changefreq/priority are kept but are ignored by Google.)
• Note on robots.txt: robots.txt is generated by src/app/robots.ts (App Router metadata route), which points at /sitemap.xml. The former static public/robots.txt was removed to avoid a stale, conflicting second source.

📂 Project Structure

• src/app: Next.js App Router pages (e.g., /, /study, /favorites, /favorites/listen, /review, /mypage, /today-words, /today-words/listen, /words, /words/[word], /login, /auth/callback, and static /about, /privacy, /terms, /contact, /donate) and API routes.
• src/proxy.ts: Supabase Auth session refresh, with the matcher minimized to /login and /auth/* to keep Vercel Middleware usage low.
• src/actions: Server Actions (e.g., fetchWordDetail wrapping the cached getWordDetail).
• src/components: React components organized by feature (features/words, features/today-words, auth, favorites, mypage, review, study, sns) and common UI (common/ — Footer, TabNavigation, CookieConsent / CookieConsentGate).
• src/lib: Utility functions and API clients (Upstash Redis, Upstash Vector, Gemini embeddings, Redis-backed word cache, Supabase browser/server clients, favorites-sync / semantic-search / review-schedule pure logic, Supabase review-progress access, JSON-LD, OG utils).
• src/types: TypeScript type definitions (e.g., WordDetails).
• src/data: Data fetching logic — words.ts (Local vs Blob switching, getAllWords / getTodayRecommendedWords / getRelatedWords) and word-detail.ts (multi-layer cached getWordDetail, Gemini generation).
• src/hooks: Custom React hooks (e.g., useTTS, useReviewProgress).
• src/context: React Contexts (AuthContext, FavoritesContext, ShareTargetContext).
• docs: Project documentation, with the current architecture in docs/architecture.md, operational runbooks in docs/operations/, specifications in docs/specs/, and completed plans in .

マイページの達成表示・定着度別一覧（2026-09-06）

• 今日の目安は REVIEW_SESSION_LIMIT（現在10語、対象が少なければ対象数）とし、到達後は達成メッセージと「もう N 語復習する」を表示する。期限到来の残件数は別に表示する。
• due / weak の固定セッションでは、完了語数・初期語数・残り語数を復習画面に表示する。全件モードと学習モードには表示しない。
• 苦手単語一覧は WEAK_WORDS_LIMIT（現在7語）まで表示する。× は「覚えていない」の累計回数と明記し、開始時の上限を適用した対象語数をボタンに表示する（途中再開時は保存済みセッションが優先）。
• 定着度は成果を中心に表示する。区分ボタンを押すとマイページ内で該当単語一覧を展開し、0件時は空状態を表示する。分類は getRetentionLevel を集計と共用し、詳細へのリンクは from=mypage を付ける。
• 確認項目：10語達成表示、due/weak の進捗と詳細からの復帰、4区分の件数と一覧、空区分、スマートフォン幅とキーボード操作。

TOPページの表示順

ヒーローには学習モードとお気に入りの2つのボタンだけを置き、すぐ下に今日のおすすめ単語を表示します。収録語数はヒーローの小さなバッジで示します。

表示順は、ヒーロー → 今日のおすすめ単語 → 意味で探す（AI） → レベル別単語一覧（つづり検索）→ 全単語一覧 → はじめての方へ → 学習ガイド最新記事 → このサイトについて（できること・おすすめルーティン・運営者メッセージ）→ FAQ → 解説記事 → SNSシェアです。2つの検索は見出しと入力欄の文言で「意味で探す」「つづりで探す」と役割を分けています。初回学習の案内のボタンは、モバイルで高さ44px以上のタップ領域を確保しています。