fix(e2e): establish a deterministic WelcomePortal entry precondition (#533)

* fix(e2e): establish a deterministic WelcomePortal entry precondition

export.spec.ts's beforeEach assumed waitForSpaReady() always resolves via
WelcomePortal and clicked "Start a New Project" unconditionally, but that
helper's Promise.race also succeeds when the app boots straight into an
already-mounted main shell. This caused all 3 retries to fail identically
on a post-merge main run, distinct from the (already-fixed) #527 portal-
activation auto-seed race.

Adds ensureWelcomePortalEntry() (tests/e2e/helpers.ts), which recovers via
the real Settings -> Data & Backups -> Factory Reset flow when the portal
isn't already showing -- no storage/React internals touched, only supported
app behavior. Regression-tested from both startup shapes in a new spec.

See issue #532 for the full evidence trail and the still-open root-cause
question of how a persisted project reached IndexedDB before the test's
own actions ran.

* fix(e2e): address review findings on the WelcomePortal precondition fix

- Add the required QNBS-v3 marker to ensureWelcomePortalEntry
  (CodeRabbit).
- Harden the persisted-main-shell regression case: wait for the real
  debounced autosave to land (observable "All changes saved" signal in
  Header.tsx) before reloading, and explicitly assert the reload landed
  back in the main shell with "Start a New Project" absent -- otherwise
  the scenario could pass via a fresh WelcomePortal without ever
  exercising ensureWelcomePortalEntry()'s Factory Reset fallback
  (chatgpt-codex-connector).

* fix(e2e): normalize to English before the locale-dependent recovery flow

ensureWelcomePortalEntry()'s Factory Reset fallback matches Settings/
Data & Backups/Factory Reset button text in English or German only. If
a non-EN/DE language were persisted when the fallback is entered, it
would hang instead of establishing the promised precondition. Force
worldscript-language to 'en' via the same localStorage key the app's
own language switcher writes, then reload, before navigating.

* fix(e2e): fix strict-mode violation in the persisted-main-shell regression test

The new post-reload main-shell assertion used locator('#sidebar').or(
locator('[data-tour="nav-mobile"]')).toBeVisible(), which fails with a
Playwright strict-mode violation: both elements exist in the DOM at
once (only one is CSS-visible per viewport via Tailwind's responsive
classes), so .or() resolves to 2 elements instead of 1. This caused
the CI E2E job on the prior push to fail on all projects (chromium,
Mobile Chrome).

Export the existing waitForMainChrome() helper (already correct via
Promise.race of two independent visibility waits, the same pattern
ensureBlankProject()/waitForSpaReady() already use) and reuse it
instead of duplicating the buggy pattern.

* fix(e2e): make WelcomePortal readiness detection locale-independent

waitForSpaReady() detected the welcome portal via the English-only
"Start a New Project" button label. If the app booted into a
non-English WelcomePortal, none of the race's three conditions would
ever match, so the whole helper (and anything built on it, including
ensureWelcomePortalEntry()'s own language-normalization step, which
only runs after waitForSpaReady() resolves) would time out before ever
getting a chance to fix the locale.

Adds a stable data-testid="welcome-portal" to WelcomePortal's root and
uses it in the readiness race instead of the translated button text.

* fix(e2e): make ensureWelcomePortalEntry's own portal check locale-independent

The stable-selector fix in 878c1e7 only updated waitForSpaReady()'s
race. ensureWelcomePortalEntry()'s own early-return check still used
the English-only button text, so a non-English WelcomePortal would
incorrectly fall through into the main-chrome-only Settings recovery
flow (which itself would then fail, since clickNavItem needs main-
chrome nav that doesn't exist on WelcomePortal). Switch this check to
the same welcome-portal testid.

Adds a regression case seeding a non-English (Spanish) language before
boot, per CodeRabbit's suggestion, proving the whole helper survives a
non-English WelcomePortal end to end.

* fix(e2e): collapse a two-line comment into the required single-line QNBS-v3 form

* fix(e2e): handle the fallback's own internal reload racing autosave

ensureWelcomePortalEntry()'s Settings/Factory Reset fallback forces
English then reloads before waiting for main chrome rigidly. If that
reload happens before a still-pending debounced autosave (~1s) lands,
the reload discards the unpersisted project and lands back in
WelcomePortal instead of main chrome -- exactly what was observed on
CI (E2E Tests failed on 7513e37, 13m timeout in waitForMainChrome).

Re-check both states after the internal reload instead of assuming
main chrome: if the portal is already visible, the target state was
reached via the race and no Settings navigation is needed.

Also fixes the helper's contract to be explicit: it guarantees the
portal is reached, locale-independently, not that it is English.
Aligns both existing regression tests (which incorrectly asserted the
English button after a locale-independent portal check) and adds a new
regression proving the helper is deterministic when its own internal
reload can land in either shape.

* fix(e2e): replace export.spec.ts's fragile EN-button click with a locale seed

ensureWelcomePortalEntry()'s contract is locale-independent (portal
reached, not necessarily English), which makes it newly possible for
export.spec.ts to actually return from a non-English WelcomePortal --
previously that state just timed out entirely, so this dead code path
was never exercised.

The existing "click the EN button" logic is unreliable there: the
custom LanguageSelector's closed-state trigger is a listbox opener,
not a direct language switch, and its accessible name comes from an
aria-label that can itself contain "en" as a substring in another
locale (Spanish's translation of the group label contains "bienvenida"
-- "bienvenida" matches /en/i). Clicking it would just open the
dropdown instead of selecting English.

Seed worldscript-language to 'en' via page.addInitScript() before the
first navigation instead, matching the existing setFeatureFlags()
idiom -- deterministic, and removes the need for any in-page language
switching in this test entirely.

Author: qnbs

CHANGELOG.md

@@ -28,6 +28,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   new user. Fixed both: synchronous `isPortalActive` initialization, and the missing
   `isInitialLoad` guard (extracted into `hooks/useProjectBootstrapEffect.ts` for direct test
   coverage). See issue #527.
+- **`export.spec.ts` E2E precondition assumed WelcomePortal unconditionally:** `waitForSpaReady()`
+  succeeds on either WelcomePortal or an already-mounted main shell, but the test's `beforeEach`
+  clicked "Start a New Project" unconditionally, causing spurious CI failures whenever a cold boot
+  landed in the main shell instead (a startup-state precondition gap, not a #527/#530 regression —
+  see issue #532). Added `ensureWelcomePortalEntry()` (`tests/e2e/helpers.ts`), which recovers via
+  the real Settings → Data & Backups → Factory Reset flow when needed, with regression coverage for
+  both startup shapes.
 
 ## [1.28.2] — 2026-08-27
 

components/WelcomePortal.tsx

@@ -366,11 +366,15 @@ export const WelcomePortal: React.FC<WelcomePortalProps> = ({ onExit }) => {
   };
 
   return (
-    <div className="fixed inset-0 z-50 overflow-y-auto overscroll-contain bg-[var(--sc-surface-base)] animate-fade-in">
+    <div
+      data-testid="welcome-portal"
+      className="fixed inset-0 z-50 overflow-y-auto overscroll-contain bg-[var(--sc-surface-base)] animate-fade-in"
+    >
       {/* QNBS-v3: shell is now scrollable (overflow-y-auto) with min-h-full centering — content
           taller than the viewport (e.g. the feature grid on mobile) scrolls instead of being
           clipped by the old fixed `flex items-center` shell. Fixes Mobile-Chrome E2E click
           timeouts where the bottom action buttons were unreachable. */}
+      {/* QNBS-v3: stable, locale-independent selector for E2E readiness checks — the primary action button's label is translated, but this attribute is not. */}
       {/* LanguageSelector now imported from ui/LanguageSelector.tsx with search functionality */}
       <LanguageSelector value={language} onChange={setLanguage} />
       <div className="flex min-h-full items-center justify-center p-4 pt-16 sm:pt-4">

tests/e2e/export.spec.ts

@@ -2,10 +2,10 @@ import { expect, type Route, test } from '@playwright/test';
 
 import {
   clickNavItem,
+  ensureWelcomePortalEntry,
   flushWriterDebounce,
   seedGeminiApiKey,
   selectFirstEnabledWriterSection,
-  waitForSpaReady,
 } from './helpers';
 
 const isCI = process.env['CI'] === 'true';
@@ -52,16 +52,14 @@ test.describe('End-to-end project flow (CI-only)', () => {
   test.beforeEach(async ({ page }) => {
     test.skip(!isCI, 'CI-only E2E suite');
     await page.route('**/generativelanguage.googleapis.com/**', mockGemini);
+    // QNBS-v3: seeds English before boot — ensureWelcomePortalEntry's contract is locale-independent, and the LanguageSelector trigger's accessible name isn't a reliable /EN/i click target (its aria-label can itself contain "en" as a substring in other locales, e.g. Spanish "bienvenida").
+    await page.addInitScript(() => localStorage.setItem('worldscript-language', 'en'));
     await page.goto('/');
-    await waitForSpaReady(page);
+    // QNBS-v3: a cold CI boot can already be in the main shell instead of WelcomePortal — this guarantees the precondition below assumes.
+    await ensureWelcomePortalEntry(page);
   });
 
   test('full project flow navigates from AI outline to export and settings', async ({ page }) => {
-    const englishButton = page.getByRole('button', { name: /EN/i }).first();
-    if (await englishButton.isVisible()) {
-      await englishButton.click();
-    }
-
     await page.getByRole('button', { name: /Start a New Project/i }).click();
     await page.getByRole('button', { name: /Generate with AI/i }).click();
 

tests/e2e/helpers.ts

@@ -109,19 +109,18 @@ export async function seedGeminiApiKey(page: Page): Promise<void> {
 
 /**
  * Vite dev server keeps the HMR/WebSocket busy → `networkidle` often never settles.
- * Wait for either the welcome portal primary action or the desktop sidebar shell.
+ * Wait for either the welcome portal or the desktop/mobile sidebar shell.
  * QNBS-v3: Also waits for the body theme class to be applied by the App useEffect so
  *          that CSS custom properties (--sc-text-primary, etc.) are fully resolved before
  *          axe or visual checks run — without this, variables resolve to intermediate values.
  */
 export async function waitForSpaReady(page: Page): Promise<void> {
   await page.waitForLoadState('domcontentloaded');
+  // QNBS-v3: welcome-portal is a stable data-testid, not the translated button label — a non-English boot no longer times out this race.
   await Promise.race([
     page.locator('#sidebar').waitFor({ state: 'visible', timeout: 25000 }),
     page.locator('[data-tour="nav-mobile"]').waitFor({ state: 'visible', timeout: 25000 }),
-    page
-      .getByRole('button', { name: /Start a New Project/i })
-      .waitFor({ state: 'visible', timeout: 25000 }),
+    page.getByTestId('welcome-portal').waitFor({ state: 'visible', timeout: 25000 }),
   ]);
   // QNBS-v3: theme class is applied in App useEffect after first render — wait for it so
   //          CSS variable values are stable (avoids axe false-positives on mid-transition colors).
@@ -137,9 +136,11 @@ export async function waitForSpaReady(page: Page): Promise<void> {
 }
 
 /**
- * Main shell is ready (desktop sidebar or mobile bottom tab bar).
+ * Main shell is ready (desktop sidebar or mobile bottom tab bar). Exported so callers proving
+ * "main shell is visible" don't reach for `locA.or(locB)` — both elements exist in the DOM at
+ * once (only one is CSS-visible per viewport), which trips Playwright's strict-mode violation.
  */
-async function waitForMainChrome(page: Page): Promise<void> {
+export async function waitForMainChrome(page: Page): Promise<void> {
   await Promise.race([
     page.locator('#sidebar').waitFor({ state: 'visible', timeout: 25000 }),
     page.locator('[data-tour="nav-mobile"]').waitFor({ state: 'visible', timeout: 25000 }),
@@ -172,6 +173,46 @@ export async function ensureBlankProject(page: Page): Promise<void> {
   await waitForMainChrome(page);
 }
 
+// QNBS-v3: guarantees a deterministic WelcomePortal entry precondition when CI cold-boots into the main shell instead.
+/**
+ * Deterministically reach the WelcomePortal entry point regardless of which of
+ * waitForSpaReady()'s two success shapes the app actually booted into. A cold CI boot has landed
+ * in an already-mounted main shell with a persisted project instead of the portal — a startup-
+ * state precondition gap distinct from the (fixed) portal-activation auto-seed race.
+ * Contract: guarantees the portal is reached, locale-independently — it does NOT guarantee
+ * English. A caller needing English selects it itself (export.spec.ts already does this for the
+ * fresh-boot case). Recovers via the real Settings → Data & Backups → Factory Reset flow when
+ * main chrome is active so no React/Redux/storage internals are touched — only supported app
+ * behavior.
+ */
+export async function ensureWelcomePortalEntry(page: Page): Promise<void> {
+  await waitForSpaReady(page);
+  const portal = page.getByTestId('welcome-portal');
+  if (await portal.isVisible({ timeout: 3000 }).catch(() => false)) {
+    return;
+  }
+  // QNBS-v3: force English before the locale-dependent recovery flow below, or a persisted non-EN/DE language would hang it.
+  await page.evaluate(() => localStorage.setItem('worldscript-language', 'en'));
+  await page.reload();
+  await waitForSpaReady(page);
+  // QNBS-v3: this reload can itself race a pending debounced autosave and land back in WelcomePortal instead of main chrome — accept either state again rather than assuming main chrome.
+  if (await portal.isVisible({ timeout: 3000 }).catch(() => false)) {
+    return;
+  }
+  await waitForMainChrome(page);
+  await clickNavItem(page, /Settings/i);
+  await page
+    .getByRole('button', { name: /Data & Backups|Daten & Backups/i })
+    .first()
+    .click();
+  await page.getByRole('button', { name: /Factory Reset|Werkseinstellungen/i }).click();
+  await page
+    .getByRole('button', { name: /Delete everything & restart|Alles löschen & neu starten/i })
+    .click();
+  await waitForSpaReady(page);
+  await expect(portal).toBeVisible({ timeout: 15000 });
+}
+
 /** Desktop sidebar (`md:`); avoids duplicate nav controls vs mobile tab bar. */
 export function sidebar(page: Page) {
   return page.locator('#sidebar');

tests/e2e/onboarding-entry-precondition.spec.ts

@@ -0,0 +1,55 @@
+import { expect, test } from '@playwright/test';
+import { ensureBlankProject, ensureWelcomePortalEntry, waitForMainChrome } from './helpers';
+
+const isCI = process.env['CI'] === 'true';
+
+// QNBS-v3: proves ensureWelcomePortalEntry's contract (portal reached, locale-independent) holds from every startup shape waitForSpaReady() accepts, including its own internal-reload race.
+test.describe('WelcomePortal entry precondition (CI-only)', () => {
+  test.beforeEach(() => {
+    test.skip(!isCI, 'CI-only E2E suite');
+  });
+
+  test('reaches the entry point on a fresh WelcomePortal boot', async ({ page }) => {
+    await page.goto('/');
+    await ensureWelcomePortalEntry(page);
+    await expect(page.getByTestId('welcome-portal')).toBeVisible();
+  });
+
+  test('reaches the entry point when a non-English language is already persisted', async ({
+    page,
+  }) => {
+    // QNBS-v3: the helper's contract is locale-independent portal-reached, not English — assert the stable testid, not the translated button label.
+    await page.addInitScript(() => localStorage.setItem('worldscript-language', 'es'));
+    await page.goto('/');
+    await expect(page.getByTestId('welcome-portal')).toBeVisible();
+    await ensureWelcomePortalEntry(page);
+    await expect(page.getByTestId('welcome-portal')).toBeVisible();
+  });
+
+  test('reaches the entry point from an already-mounted main shell with a persisted project', async ({
+    page,
+  }) => {
+    await page.goto('/');
+    await ensureBlankProject(page);
+    // QNBS-v3: waits for the debounced autosave to land so this scenario specifically exercises the full Settings/Factory Reset fallback, which does normalize to English as an implementation detail.
+    await expect(page.getByText(/All changes saved|Alle Änderungen gespeichert/i)).toBeVisible({
+      timeout: 10000,
+    });
+    await page.reload();
+    // QNBS-v3: proves the reload landed in the main shell, not a fresh WelcomePortal, or the assertion below would be vacuous.
+    await waitForMainChrome(page);
+    await expect(page.getByRole('button', { name: /Start a New Project/i })).not.toBeVisible();
+    await ensureWelcomePortalEntry(page);
+    await expect(page.getByRole('button', { name: /Start a New Project/i })).toBeVisible();
+  });
+
+  test('reaches the entry point when its own internal reload can race a pending autosave', async ({
+    page,
+  }) => {
+    // QNBS-v3: deliberately does not wait for "All changes saved" — the helper's own English-normalization reload can race the pending debounced save either way, and it must end in the portal regardless.
+    await page.goto('/');
+    await ensureBlankProject(page);
+    await ensureWelcomePortalEntry(page);
+    await expect(page.getByTestId('welcome-portal')).toBeVisible();
+  });
+});