From 6df9ddf29805730ae4415901f0935b70ca9f7baa Mon Sep 17 00:00:00 2001
From: Kevin Deng <sxzz@sxzz.moe>
Date: Fri, 21 Aug 2026 15:55:12 +0900
Subject: [PATCH] Prevent flashes of mismatched restored preferences (#40)

---
 app/app.vue                              |  17 +++-
 app/composables/i18n.ts                  |  47 ++++++++--
 app/composables/prefs.ts                 |  12 ++-
 app/styles/global.css                    |  11 +++
 app/utils/preference-restore.ts          |  16 ++++
 nuxt.config.ts                           |  10 ++-
 scripts/preference-restore.ts            |  37 ++++++++
 scripts/tests/preference-restore.test.ts | 104 +++++++++++++++++++++++
 8 files changed, 238 insertions(+), 16 deletions(-)
 create mode 100644 app/utils/preference-restore.ts
 create mode 100644 scripts/preference-restore.ts
 create mode 100644 scripts/tests/preference-restore.test.ts

diff --git a/app/app.vue b/app/app.vue
index b92f826..7657766 100644
--- a/app/app.vue
+++ b/app/app.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { useStyle } from '~/composables/style.ts'
+import { revealRestoredPreferences } from '~/utils/preference-restore.ts'
 
 const { t, meta } = useT()
 const route = useRoute()
@@ -9,8 +10,20 @@ const isHome = computed(() => route.name === 'index')
 const showFooter = computed(() => route.name !== 'about')
 
 // Picks the reader's language once the client is running; the prerendered
-// HTML is always the default locale
-useLocaleChoice()
+// HTML is always the default locale. If the head script hid a mismatching
+// default frame, reveal only after the translated and projected DOM is ready.
+const { ready: localeReady } = useLocaleChoice()
+if (import.meta.client) {
+  watch(
+    localeReady,
+    async (ready) => {
+      if (!ready) return
+      await nextTick()
+      revealRestoredPreferences(meta.value.htmlLang)
+    },
+    { flush: 'post' },
+  )
+}
 
 /**
  * Serif ships its own ~140KB of @font-face rules. Latch it once a reader asks
diff --git a/app/composables/i18n.ts b/app/composables/i18n.ts
index c8ab012..71c4866 100644
--- a/app/composables/i18n.ts
+++ b/app/composables/i18n.ts
@@ -8,6 +8,7 @@ import {
   type Messages,
 } from '~/locales/index.ts'
 import { zhCN } from '~/locales/zh-cn.ts'
+import { LOCALE_KEY } from '~/utils/preference-restore.ts'
 
 /**
  * Messages that have arrived. The default is here from the start -- it is what
@@ -17,10 +18,21 @@ import { zhCN } from '~/locales/zh-cn.ts'
 const loaded = reactive<Partial<Record<Locale, Messages>>>({
   'zh-CN': zhCN,
 })
+const loading: Partial<Record<Locale, Promise<void>>> = {}
 
 async function load(locale: Locale): Promise<void> {
   if (loaded[locale]) return
-  loaded[locale] = await LOADERS[locale]()
+  const pending =
+    loading[locale] ??
+    (loading[locale] = LOADERS[locale]().then((messages) => {
+      loaded[locale] = messages
+    }))
+  try {
+    await pending
+  } finally {
+    // A failed chunk may be retried from the language menu later.
+    if (loading[locale] === pending) delete loading[locale]
+  }
 }
 
 /** Follow one dotted key through a message tree. */
@@ -78,7 +90,25 @@ export function useT() {
  */
 export function useLocaleChoice() {
   const { locale } = useT()
-  const stored = useLocalStorage<Locale | ''>('hanji:locale', '')
+  const stored = useLocalStorage<Locale | ''>(LOCALE_KEY, '')
+  const ready = ref(false)
+
+  const preferred = (): Locale | undefined =>
+    (LOCALES as readonly string[]).includes(stored.value)
+      ? (stored.value as Locale)
+      : matchLocale(navigator.languages ?? [navigator.language])
+
+  // Start fetching a non-default translation during root setup. The active
+  // locale stays untouched until mounted, so hydration still agrees with the
+  // SSG markup, but the page spends less time behind the restoration screen.
+  const initial = import.meta.client ? preferred() : undefined
+  const prepared =
+    initial && initial !== locale.value
+      ? load(initial).then(
+          () => true,
+          () => false,
+        )
+      : undefined
 
   async function apply(next: Locale): Promise<void> {
     await load(next)
@@ -91,11 +121,14 @@ export function useLocaleChoice() {
   }
 
   onMounted(async () => {
-    const wanted = (LOCALES as readonly string[]).includes(stored.value)
-      ? (stored.value as Locale)
-      : matchLocale(navigator.languages ?? [navigator.language])
-    if (wanted && wanted !== locale.value) await apply(wanted)
+    if (initial && initial !== locale.value) {
+      const available = prepared ? await prepared : false
+      if (available) locale.value = initial
+    }
+    // Even a failed locale request must not leave the static fallback hidden;
+    // the default Chinese page is still useful on a flaky or offline visit.
+    ready.value = true
   })
 
-  return { locale, choose, locales: LOCALES }
+  return { locale, choose, locales: LOCALES, ready: readonly(ready) }
 }
diff --git a/app/composables/prefs.ts b/app/composables/prefs.ts
index 457a4c6..4f778ec 100644
--- a/app/composables/prefs.ts
+++ b/app/composables/prefs.ts
@@ -5,9 +5,13 @@ import {
   type Column,
   type Region,
 } from '~~/shared/types.ts'
+import {
+  FLAGS_KEY,
+  HIDDEN_KEY,
+  OUTLINE_KEY,
+  VISIBILITY_VERSION_KEY,
+} from '~/utils/preference-restore.ts'
 
-export const HIDDEN_KEY = 'hanji:hidden'
-const VISIBILITY_VERSION_KEY = 'hanji:columns-v2'
 const isColumn = (value: string): value is Column =>
   (COLUMNS as readonly string[]).includes(value)
 
@@ -111,13 +115,13 @@ export function useColumnVisibility() {
 export function usePrefs() {
   // Keep the original storage key so existing readers retain their choice
   // after the visual labels move from platform emoji to local SVG artwork.
-  const flagLabels = useLocalStorage('hanji:emoji-flags', false)
+  const flagLabels = useLocalStorage(FLAGS_KEY, false)
   /**
    * Draw the stacked forms as outlines instead of solid ink. Filled strokes
    * that agree pile into a single mass; hollow ones stay legible through each
    * other, so where the forms part company reads at a glance.
    */
-  const outline = useLocalStorage('hanji:outline', false)
+  const outline = useLocalStorage(OUTLINE_KEY, false)
 
   // Read on the client only: the prerendered HTML has to match what hydration
   // produces, and localStorage is not available while prerendering.
diff --git a/app/styles/global.css b/app/styles/global.css
index 9447465..1b7e50e 100644
--- a/app/styles/global.css
+++ b/app/styles/global.css
@@ -14,6 +14,17 @@ html.dark {
   color-scheme: dark;
 }
 
+/*
+ * The static page is always rendered with default preferences. An inline head
+ * script adds this attribute only when local state says Vue will replace that
+ * first frame. Keeping the body hidden turns a wrong-content flash into one
+ * reveal after hydration. With JavaScript disabled the attribute is never
+ * added, so the complete SSG page remains available.
+ */
+html[data-restoring-preferences] body {
+  visibility: hidden;
+}
+
 @media (min-width: 768px) {
   html {
     --nav-h: 4.5rem;
diff --git a/app/utils/preference-restore.ts b/app/utils/preference-restore.ts
new file mode 100644
index 0000000..7cf1b48
--- /dev/null
+++ b/app/utils/preference-restore.ts
@@ -0,0 +1,16 @@
+export const LOCALE_KEY = 'hanji:locale'
+export const FLAGS_KEY = 'hanji:emoji-flags'
+export const OUTLINE_KEY = 'hanji:outline'
+export const HIDDEN_KEY = 'hanji:hidden'
+export const VISIBILITY_VERSION_KEY = 'hanji:columns-v2'
+
+export const RESTORING_ATTRIBUTE = 'data-restoring-preferences'
+
+/** Reveal the page after Vue has applied all persisted presentation state. */
+export function revealRestoredPreferences(htmlLang: string): void {
+  const root = document.documentElement
+  // Unhead updates asynchronously after Vue's DOM. Pin the final language now
+  // so the revealed translation cannot spend a frame in the SSG's CJK font.
+  root.lang = htmlLang
+  root.removeAttribute(RESTORING_ATTRIBUTE)
+}
diff --git a/nuxt.config.ts b/nuxt.config.ts
index b63fd0f..7870a4e 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { RESTORE_SCRIPT } from './app/utils/theme.ts'
+import { PREFERENCE_RESTORE_SCRIPT } from './scripts/preference-restore.ts'
 import type { CharsData } from './shared/types.ts'
 import type { NuxtConfig } from 'nuxt/schema'
 
@@ -58,9 +59,12 @@ export default {
     head: {
       htmlAttrs: { lang: 'zh-CN', 'data-style': 'sans' },
       // app.vue does not render into Nitro's client-only fallback documents.
-      // Keep preference restoration static so 200.html and 404.html also set
-      // the selected face and color scheme before their first paint.
-      script: [{ innerHTML: RESTORE_SCRIPT, tagPosition: 'head' }],
+      // Keep both bootstraps static so 200.html and 404.html also restore the
+      // theme and suppress a mismatching preference frame before first paint.
+      script: [
+        { innerHTML: RESTORE_SCRIPT, tagPosition: 'head' },
+        { innerHTML: PREFERENCE_RESTORE_SCRIPT, tagPosition: 'head' },
+      ],
       // Chunked Han subsets. Keeping the @font-face rules in their own
       // cacheable files keeps them out of the JS/CSS bundle; serif is linked
       // on demand from app.vue.
diff --git a/scripts/preference-restore.ts b/scripts/preference-restore.ts
new file mode 100644
index 0000000..f7c59f1
--- /dev/null
+++ b/scripts/preference-restore.ts
@@ -0,0 +1,37 @@
+import { DEFAULT_LOCALE, LOCALES } from '../app/locales/index.ts'
+import {
+  FLAGS_KEY,
+  HIDDEN_KEY,
+  LOCALE_KEY,
+  OUTLINE_KEY,
+  RESTORING_ATTRIBUTE,
+  VISIBILITY_VERSION_KEY,
+} from '../app/utils/preference-restore.ts'
+import { COLUMNS, DEFAULT_HIDDEN_COLUMNS, REGIONS } from '../shared/types.ts'
+
+const RESTORE_TIMEOUT_MS = 4000
+
+/**
+ * Runs in the static head before first paint. It does not try to reproduce the
+ * personalised page -- translations and column projection still belong to
+ * Vue -- but it can tell when the SSG defaults would be visibly wrong.
+ *
+ * In that case CSS keeps the default page out of sight until the client has
+ * restored every preference. Browsers with JavaScript disabled never execute
+ * this script and therefore keep the complete, default-locale SSG page. The
+ * timeout is for the rarer middle case where this inline script runs but the
+ * application bundle or a locale chunk fails to load.
+ */
+export const PREFERENCE_RESTORE_SCRIPT = `
+try{
+var d=document.documentElement,o=d.lang,g=function(k){var v=localStorage.getItem(k);return v===null?'':v.replace(/^"|"$/g,'')};
+var a=${JSON.stringify(LOCALES)},l=g(${JSON.stringify(LOCALE_KEY)}),w='';
+if(a.indexOf(l)>=0)w=l;else{var n=navigator.languages||[navigator.language||''];for(var i=0;i<n.length;i++){var x=String(n[i]).toLowerCase(),b=x.split('-'),z=b[0];if(z==='ja'){w='ja-JP';break}if(z==='ko'){w='ko-KR';break}if(z==='zh'){w=b.indexOf('hk')>=0||b.indexOf('mo')>=0?'zh-HK':b.indexOf('tw')>=0||b.indexOf('hant')>=0?'zh-TW':'zh-CN';break}}}
+var p=!!w&&w!==${JSON.stringify(DEFAULT_LOCALE)};
+if(g(${JSON.stringify(FLAGS_KEY)})==='true'||g(${JSON.stringify(OUTLINE_KEY)})==='true')p=true;
+var h,r=localStorage.getItem(${JSON.stringify(HIDDEN_KEY)});try{h=r===null?${JSON.stringify(DEFAULT_HIDDEN_COLUMNS)}:JSON.parse(r)}catch(e){h=${JSON.stringify(DEFAULT_HIDDEN_COLUMNS)}}if(!Array.isArray(h))h=${JSON.stringify(DEFAULT_HIDDEN_COLUMNS)};
+var v=g(${JSON.stringify(VISIBILITY_VERSION_KEY)})==='true',c=${JSON.stringify(COLUMNS)};h=c.filter(function(k){return !v&&k==='kr'||h.indexOf(k)>=0});
+if(${JSON.stringify(REGIONS)}.every(function(k){return h.indexOf(k)>=0}))h=${JSON.stringify(DEFAULT_HIDDEN_COLUMNS)};
+if(h.length!==${DEFAULT_HIDDEN_COLUMNS.length}||h.some(function(k,i){return k!==${JSON.stringify(DEFAULT_HIDDEN_COLUMNS)}[i]}))p=true;
+if(p){if(w)d.lang=w;d.setAttribute(${JSON.stringify(RESTORING_ATTRIBUTE)},'');setTimeout(function(){if(d.hasAttribute(${JSON.stringify(RESTORING_ATTRIBUTE)})){d.lang=o;d.removeAttribute(${JSON.stringify(RESTORING_ATTRIBUTE)})}},${RESTORE_TIMEOUT_MS})}
+}catch(e){}`
diff --git a/scripts/tests/preference-restore.test.ts b/scripts/tests/preference-restore.test.ts
new file mode 100644
index 0000000..ff59d4b
--- /dev/null
+++ b/scripts/tests/preference-restore.test.ts
@@ -0,0 +1,104 @@
+import { runInNewContext } from 'node:vm'
+import { describe, expect, it } from 'vitest'
+import {
+  FLAGS_KEY,
+  HIDDEN_KEY,
+  LOCALE_KEY,
+  OUTLINE_KEY,
+  RESTORING_ATTRIBUTE,
+  VISIBILITY_VERSION_KEY,
+} from '../../app/utils/preference-restore.ts'
+import config from '../../nuxt.config.ts'
+import { PREFERENCE_RESTORE_SCRIPT } from '../preference-restore.ts'
+
+interface RunOptions {
+  storage?: Record<string, string>
+  languages?: string[]
+}
+
+function runRestore({ storage = {}, languages = ['zh-CN'] }: RunOptions = {}) {
+  const attributes = new Set<string>()
+  const timers: (() => void)[] = []
+  const documentElement = {
+    lang: 'zh-CN',
+    hasAttribute: (name: string) => attributes.has(name),
+    setAttribute: (name: string) => attributes.add(name),
+    removeAttribute: (name: string) => attributes.delete(name),
+  }
+
+  runInNewContext(PREFERENCE_RESTORE_SCRIPT, {
+    document: { documentElement },
+    localStorage: {
+      getItem: (key: string) => storage[key] ?? null,
+    },
+    navigator: { languages, language: languages[0] ?? '' },
+    setTimeout: (callback: () => void) => timers.push(callback),
+  })
+
+  return {
+    htmlLang: () => documentElement.lang,
+    isRestoring: () => attributes.has(RESTORING_ATTRIBUTE),
+    runFallback: () => timers.forEach((callback) => callback()),
+  }
+}
+
+describe('preference restoration screen', () => {
+  it('leaves the static page visible when every preference is default', () => {
+    expect(runRestore().isRestoring()).toBe(false)
+    expect(
+      runRestore({
+        languages: ['ja-JP'],
+        storage: { [LOCALE_KEY]: 'zh-CN' },
+      }).isRestoring(),
+    ).toBe(false)
+  })
+
+  it('understands legacy column state before deciding it differs', () => {
+    expect(runRestore({ storage: { [HIDDEN_KEY]: '[]' } }).isRestoring()).toBe(
+      false,
+    )
+    expect(
+      runRestore({
+        storage: {
+          [HIDDEN_KEY]: JSON.stringify(['cn', 'hk', 'tw', 'jp', 'kr']),
+          [VISIBILITY_VERSION_KEY]: 'true',
+        },
+      }).isRestoring(),
+    ).toBe(false)
+  })
+
+  it.each([
+    ['stored locale', { [LOCALE_KEY]: '"ja-JP"' }],
+    ['flag labels', { [FLAGS_KEY]: 'true' }],
+    ['outlines', { [OUTLINE_KEY]: '"true"' }],
+    [
+      'comparison scope',
+      { [HIDDEN_KEY]: '[]', [VISIBILITY_VERSION_KEY]: 'true' },
+    ],
+  ])('hides a mismatching SSG frame for %s', (_, storage) => {
+    expect(runRestore({ storage }).isRestoring()).toBe(true)
+  })
+
+  it('covers a browser-selected locale when no choice is stored', () => {
+    const page = runRestore({ languages: ['en-US', 'zh-TW'] })
+    expect(page.isRestoring()).toBe(true)
+    expect(page.htmlLang()).toBe('zh-TW')
+  })
+
+  it('reveals the default page if the application never finishes', () => {
+    const page = runRestore({ storage: { [LOCALE_KEY]: 'ja-JP' } })
+    expect(page.isRestoring()).toBe(true)
+    expect(page.htmlLang()).toBe('ja-JP')
+    page.runFallback()
+    expect(page.isRestoring()).toBe(false)
+    expect(page.htmlLang()).toBe('zh-CN')
+  })
+
+  it('keeps no-JavaScript SSG visible by default', () => {
+    expect(config.app.head.htmlAttrs).not.toHaveProperty(RESTORING_ATTRIBUTE)
+    expect(config.app.head.script).toContainEqual({
+      innerHTML: PREFERENCE_RESTORE_SCRIPT,
+      tagPosition: 'head',
+    })
+  })
+})
-- 
2.51.2