feat: DB migration — pgvector, Postgres caches, leaderboard, security

.gitignore

@@ -4,6 +4,9 @@
 # Working session docs (internal notes)
 docs/
 
+# Design exploration HTML mockups (local only)
+public/design-explorations/
+
 # Node.js / Frontend
 node_modules/
 .pnpm-store/
@@ -55,3 +58,4 @@ scripts/.fonts/
 
 # OG mode images: regenerate with `uv run python scripts/generate_mode_og_images.py --all`
 # Committed to git (~5MB) since Render build env lacks Python/uv.
+.claude

TODO.md

@@ -448,3 +448,68 @@ const stats = computed(() => {
 });
 ```
 Then `calculateStats(key, max)` becomes `setStatsKey(key, max)` — just sets the refs, Vue handles the rest. Eliminates the entire class of "forgot to recalculate" bugs. Touches: `stores/stats.ts`, `composables/useGamePage.ts`, `pages/profile.vue`.
+
+### 16. Semantic Explorer: viewport-locked layout (like other game modes)
+The semantic page uses a scrollable layout (`overflow-y: auto` on `.semantic-body`) while every other game mode uses `h-[100dvh]` viewport-locked layout via `PageShell`. This causes:
+- Double scrollbar on short desktops (page scroll + browser scroll)
+- Map SVG overflows its `max-height` container because it renders at intrinsic 520px
+- `min-height: 280px` fights `max-height: calc(100dvh - 310px)` on short viewports
+- Input gets pushed below the fold
+
+**Proper fix:** Refactor `semantic.vue` to use viewport-locked layout like `PageShell`:
+- Left column (map + input): flex column, map grows to fill, input pinned to bottom
+- Right column (compass + hint + leaderboard): flex column with overflow scroll
+- No page-level scroll — everything fits in viewport
+- Expand button goes truly fullscreen (overlay), not just "fill the column"
+
+Current band-aid: `min-height: min(200px, calc(100dvh - 310px))` prevents `min-height` from exceeding viewport, but the SVG still overflows on short desktops. `:deep()` CSS hacks were tried and reverted because they broke the expanded map aspect ratio.
+
+---
+
+## DB Migration — Remove Disk Fallback Paths
+
+**Added**: 2026-04-12
+**Status**: Monitoring — disk fallback paths emit console.warn when hit
+
+Data has been migrated from Render's persistent disk to Postgres:
+- 253K definitions (77K kaikki native + 98K kaikki-en + 77K LLM, source/model provenance tracked)
+- 2.8K word stats
+- 50K embeddings with UMAP/PCA2D coordinates, 70 axes, 4.4M neighbor ranks
+- `model` column added to definitions table (gpt-5.2, wiktionary-kaikki-2024, legacy-unknown)
+
+### Phase 1: Remove disk fallback code (after 2 weeks stable, ~2026-04-26)
+
+- [ ] `server/utils/definitions.ts` — remove Tier 1 disk read, disk write, kaikki in-memory cache (`_kaikkiCache`, `loadKaikkiFile`, `lookupKaikki`, `resolveDefinitionsDir`, `DEFINITIONS_DIR`). Kaikki data is now in the `definitions` table with source='kaikki'/'kaikki-en'.
+- [ ] `server/utils/word-stats.ts` — remove disk read/write fallback + `proper-lockfile` dependency
+- [ ] `server/utils/wiktionary.ts` — remove `readCache`/`writeCache` disk functions
+- [ ] `server/api/[lang]/semantic/hint.post.ts` — remove disk read/write for hints
+- [ ] `server/utils/data-loader.ts` — remove `WORD_DEFS_DIR`, `WORD_STATS_DIR` exports
+- [ ] Remove `proper-lockfile` from package.json
+- [ ] Remove fs imports (`existsSync`, `readFileSync`, `writeFileSync`, `mkdirSync`) from all above files
+
+### Phase 2: Migrate remaining disk-dependent features
+
+- [ ] **Word history** → new DB table `(lang, day_idx, word)`. ~136K rows (80 langs × 1700 days). Eliminates 546MB of `.txt` files on Render disk and disk reads in `word-selection.ts`. Algorithm is deterministic but cache is a safety net against word list changes.
+- [ ] **Word images** → decide: keep on Render persistent disk ($0.40/month for 1.5GB), or move to Cloudflare R2 (free egress, ~$0.003/month for 204MB). Only feature still requiring the persistent disk. No urgency — current setup works.
+- [ ] **`semantic.ts` legacy in-memory loader** — `start.post.ts` and `word/[slug].get.ts` still import `loadSemanticData` which loads the 98MB embedding matrix. Migrate these two endpoints to use `_semantic-db.ts` (DB-backed), then delete `loadSemanticData`/`loadSemanticDataSafe`/`loadEmbeddings` and the entire in-memory path.
+
+### Phase 3: Remove committed heavy files from git
+
+- [ ] `data/semantic/embeddings.f32` + `embeddings.meta.json` (~99MB) — in pgvector
+- [ ] `data/semantic/embeddings.json` (~230MB if present) — in pgvector
+- [ ] `data/semantic/axes.json` — in `semantic_axes` table
+- [ ] `data/semantic/umap.json`, `pca2d.json` — in `word_embeddings` columns
+- [ ] `data/semantic/targets.json`, `vocabulary.json` — queryable from `word_embeddings`
+- [ ] Keep `data/semantic/valid_words.json` (loaded into memory for spellcheck, no DB table)
+- [ ] Keep `data/definitions/` as archive (kaikki data now in DB, but files are small and useful for re-seeding)
+
+### 17. Semantic Explorer OG image
+Design and add `public/images/og-semantic.png` (1200x630) showing the meaning map with dots, compass needle, and the editorial aesthetic. Currently falls back to generic `og-image.png`.
+
+### 18. Semantic best starting words
+Add semantic-specific content to the `/en/best-starting-words` page — tips for first guesses in semantic mode (broad category words, high-information starters). Could be a separate section or tab.
+
+### 19. useGameSeo refactor
+- Silent 60-char truncation: configured titles are dropped without warning when too long. Should either warn at build time or use the configured title regardless.
+- Hardcoded `| Wordle English` suffix: not all modes benefit from Wordle brand. Add configurable suffix per mode.
+- No length validation at config time — easy to write titles/descriptions that get silently truncated.

assets/css/design-system.css

@@ -230,6 +230,25 @@
     border-color: var(--color-ink);
 }
 
+/* Thin editorial scrollbar — used on modals, leaderboards, and any scrollable panel */
+.editorial-scroll {
+    scrollbar-width: thin;
+    scrollbar-color: var(--color-rule) transparent;
+}
+.editorial-scroll::-webkit-scrollbar {
+    width: 4px;
+}
+.editorial-scroll::-webkit-scrollbar-track {
+    background: transparent;
+}
+.editorial-scroll::-webkit-scrollbar-thumb {
+    background: var(--color-rule);
+    border-radius: 2px;
+}
+.editorial-scroll::-webkit-scrollbar-thumb:hover {
+    background: var(--color-muted);
+}
+
 /* Flag icon — consistent circular flag display */
 .flag-icon {
     width: 24px;

components/LbAvatar.vue

@@ -0,0 +1,41 @@
+<template>
+    <img
+        v-if="avatarUrl"
+        :src="avatarUrl"
+        :alt="username"
+        :class="[sizeClass, 'rounded-full object-cover flex-shrink-0']"
+        referrerpolicy="no-referrer"
+    />
+    <div
+        v-else
+        :class="[
+            sizeClass,
+            fontSize,
+            'rounded-full bg-rule text-muted flex items-center justify-center font-display font-bold flex-shrink-0',
+        ]"
+    >
+        {{ initial }}
+    </div>
+</template>
+
+<script setup lang="ts">
+const props = withDefaults(
+    defineProps<{
+        username: string;
+        avatarUrl?: string | null;
+        size?: 'sm' | 'md' | 'lg';
+    }>(),
+    {
+        avatarUrl: null,
+        size: 'md',
+    }
+);
+
+const sizeClass = computed(() => {
+    if (props.size === 'sm') return 'w-7 h-7';
+    if (props.size === 'lg') return 'w-12 h-12';
+    return 'w-8 h-8';
+});
+const fontSize = computed(() => (props.size === 'lg' ? 'text-base' : 'text-xs'));
+const initial = computed(() => props.username.charAt(0).toUpperCase());
+</script>

components/LbList.vue

@@ -0,0 +1,98 @@
+<template>
+    <ol class="lb-list">
+        <li
+            v-for="entry in entries"
+            :key="entry.rank"
+            class="lb-row"
+            :class="{ 'lb-row-you': showYou && you && entry.username === you.username }"
+        >
+            <div class="lb-rank" :class="rankClass(entry.rank)">{{ entry.rank }}</div>
+            <LbAvatar :username="entry.username" :avatar-url="entry.avatarUrl" />
+            <div class="flex-1 min-w-0">
+                <div class="text-sm font-semibold text-ink truncate">
+                    {{ entry.username }}
+                    <span
+                        v-if="showYou && you && entry.username === you.username"
+                        class="font-mono text-[8px] tracking-[0.1em] uppercase bg-ink text-paper px-1 py-px ms-1.5 align-middle"
+                        >YOU</span
+                    >
+                </div>
+                <div v-if="isAgg && entry.daysPlayed" class="font-mono text-[9px] text-muted">
+                    {{ entry.daysPlayed }} days
+                </div>
+            </div>
+            <div class="text-end flex-shrink-0">
+                <div class="font-mono text-sm font-bold flex items-center gap-1">
+                    <Flame v-if="isStreaks" :size="14" class="text-flame" />
+                    {{ formatScore(entry) }}
+                </div>
+                <div v-if="formatScoreSub(entry)" class="font-mono text-[9px] text-muted">
+                    {{ formatScoreSub(entry) }}
+                </div>
+            </div>
+        </li>
+    </ol>
+</template>
+
+<script setup lang="ts">
+import { Flame } from 'lucide-vue-next';
+
+defineProps<{
+    entries: any[];
+    you?: any;
+    showYou?: boolean;
+    isStreaks: boolean;
+    isAgg: boolean;
+    formatScore: (entry: any) => string;
+    formatScoreSub: (entry: any) => string | null;
+}>();
+
+function rankClass(rank: number): Record<string, boolean> {
+    return {
+        'lb-rank-gold': rank === 1,
+        'lb-rank-silver': rank === 2,
+        'lb-rank-bronze': rank === 3,
+    };
+}
+</script>
+
+<style scoped>
+.lb-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+.lb-row {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 10px 4px;
+    border-bottom: 1px solid var(--color-rule);
+    transition: background 0.15s;
+}
+.lb-row:hover {
+    background: var(--color-paper-warm);
+}
+.lb-row-you {
+    background: var(--color-paper-warm);
+    border-inline-start: 3px solid var(--color-ink);
+    padding-inline-start: 1px;
+}
+.lb-rank {
+    font-family: var(--font-mono);
+    font-size: 14px;
+    font-weight: 700;
+    width: 28px;
+    text-align: center;
+    flex-shrink: 0;
+}
+.lb-rank-gold {
+    color: #c9a930;
+}
+.lb-rank-silver {
+    color: #8a8a8a;
+}
+.lb-rank-bronze {
+    color: #a0622e;
+}
+</style>

components/LbPodium.vue

@@ -0,0 +1,132 @@
+<template>
+    <div class="podium">
+        <div
+            v-for="(place, idx) in orderedPlaces"
+            :key="idx"
+            class="podium-place"
+            :class="['second', 'first', 'third'][idx]"
+        >
+            <div class="podium-rank">{{ ['#2', '#1', '#3'][idx] }}</div>
+            <LbAvatar
+                :username="place.username"
+                :avatar-url="place.avatarUrl"
+                :size="idx === 1 ? 'lg' : 'md'"
+            />
+            <div class="podium-name">
+                {{ place.username }}
+                <span v-if="showYou && you && place.username === you.username" class="podium-you"
+                    >YOU</span
+                >
+            </div>
+            <div class="podium-score">
+                <Flame
+                    v-if="isStreaks"
+                    :size="14"
+                    class="text-flame inline-block align-text-bottom"
+                />
+                {{ formatScore(place) }}
+            </div>
+        </div>
+    </div>
+</template>
+
+<script setup lang="ts">
+import { Flame } from 'lucide-vue-next';
+
+const props = defineProps<{
+    podium: { first: any; second: any; third: any };
+    you?: any;
+    showYou?: boolean;
+    isStreaks: boolean;
+    formatScore: (entry: any) => string;
+}>();
+
+const orderedPlaces = computed(() => [props.podium.second, props.podium.first, props.podium.third]);
+</script>
+
+<style scoped>
+.podium {
+    display: flex;
+    align-items: flex-end;
+    justify-content: center;
+    gap: 12px;
+    padding: 16px 8px 16px;
+    margin-bottom: 4px;
+}
+.podium-place {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 4px;
+}
+.podium-place.first {
+    order: 2;
+}
+.podium-place.second {
+    order: 1;
+}
+.podium-place.third {
+    order: 3;
+}
+.podium-rank {
+    font-family: var(--font-mono);
+    font-size: 10px;
+    font-weight: 700;
+    color: var(--color-muted);
+    letter-spacing: 0.04em;
+    margin-bottom: 2px;
+}
+.podium-place.first .podium-rank {
+    color: #c9a930;
+}
+.podium-place.second .podium-rank {
+    color: #8a8a8a;
+}
+.podium-place.third .podium-rank {
+    color: #a0622e;
+}
+.podium-name {
+    font-family: var(--font-body);
+    font-size: 12px;
+    font-weight: 600;
+    max-width: 80px;
+    text-align: center;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    color: var(--color-ink);
+}
+.podium-you {
+    display: block;
+    font-family: var(--font-mono);
+    font-size: 7px;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    background: var(--color-ink);
+    color: var(--color-paper);
+    padding: 0 4px;
+    margin: 2px auto 0;
+    width: fit-content;
+}
+.podium-score {
+    font-family: var(--font-mono);
+    font-size: 13px;
+    font-weight: 700;
+    color: var(--color-ink);
+    margin-top: 2px;
+}
+
+/* Avatar ring color for podium */
+.podium-place.first :deep(img),
+.podium-place.first :deep(.rounded-full) {
+    border: 2px solid #c9a930;
+}
+.podium-place.second :deep(img),
+.podium-place.second :deep(.rounded-full) {
+    border: 2px solid #8a8a8a;
+}
+.podium-place.third :deep(img),
+.podium-place.third :deep(.rounded-full) {
+    border: 2px solid #a0622e;
+}
+</style>