E2E WelcomePortal entry remains nondeterministic across startup states

[qnbs]

Current status — 2026-09-01

This issue remains OPEN. The supported-UI ensureWelcomePortalEntry() harness hardening reduced the original precondition problem but has not fully eliminated this nondeterministic startup/navigation failure class.

A recurrence was observed on unrelated docs-only PR #564 at exact head bf684034afe82d838dcd9bc62bfd9de0aecafbe6 in CI/CD run 33478269659 / Playwright job 99764976401:

117 passed
9 skipped
2 failed
2 flaky

The failures/flakes again converged on ensureWelcomePortalEntry() / WelcomePortal startup navigation in onboarding-entry-precondition.spec.ts and export.spec.ts, across Chromium and Mobile Chrome. PR #564 changes only the R-15 design contract / migration-ledger documentation, so there is no demonstrated S5/R-15 source relationship.

Current classification:

startup/harness determinism owner = #532
settings-only seed-authority ambiguity = RESOLVED by #546
underlying double-boot / unexpected startup-state root cause = OPEN
#527 regression = NO evidence

Preserve first-attempt failures as evidence. A same-head targeted rerun may classify intermittent behavior, but repeated retries must not substitute for root-cause analysis.

Summary

export.spec.ts's beforeEach originally assumed waitForSpaReady(page) always resolves via WelcomePortal, and clicked "Start a New Project" unconditionally. waitForSpaReady() actually races three success conditions (#sidebar, [data-tour="nav-mobile"], or the "Start a New Project" button) and succeeds on any of them — it does not distinguish a fresh boot from a returning-user boot. On the main post-merge run for PR #530 (run 33088546994, job 98579015311), all 3 Playwright retries of this test failed identically (byte-identical screenshot/error-context hashes) waiting on that locator, because the app had already booted into the main shell (Outline Generator view) instead of WelcomePortal. A same-SHA rerun (job 98582879363) passed cleanly, establishing a startup-state determinism gap rather than the already-fixed #527 portal-activation auto-seed race.

This is not a regression of #527/#530. Do not reopen #527 unless its exact mechanism is independently reproduced.

Evidence gathered from the original failure

From the failed job's attached Playwright trace (retry 1, chromium):

• waitForSpaReady()'s internal action log shows the #sidebar wait resolving successfully before the "Start a New Project" wait ever got its own resolution — i.e. the race resolved via the main-chrome branch, not WelcomePortal.
• Frame-snapshot URLs recorded across the trace: the page loaded at http://127.0.0.1:3000/WorldScript-Studio/ with no hash, then ~700ms later the hash became #/outline and stayed there for the remainder of the 20s timeout — i.e. the app's own in-app router (deepLinkService.pushHash) navigated to Outline Generator on its own, which per useApp.ts's readInitialView() priority (URL hash → ?view= → localStorage['worldscript-last-view'] → dashboard) only happens when one of the first three sources was already non-empty.
• Console log timeline shows the full boot sequence (Vite HMR connect, Using IndexedDB storage backend, SW registration, WorkerBus init) occurring twice within this single trace, with [WorldScript:DEBUG:app] Hydrating flat project state into Redux-Undo envelope. appearing only on the second occurrence. Per index.tsx's bootApp(), this log line only fires when preloadedState.project is truthy and in flat (non-envelope) format — i.e. a real, non-blank persisted project existed in IndexedDB by the second boot cycle, not merely a default/blank placeholder.
• export.spec.ts is a single-test file using Playwright's stock, fully-isolated per-test browser context (no custom fixtures, no storageState, no globalSetup in playwright.config.ts) — cross-test-file storage leakage is ruled out as the mechanism.

Open root cause

The exact trigger for the double-boot cycle and/or unexpected WelcomePortal-entry state is not yet pinned down.

Candidate mechanisms requiring evidence include:

1. register-sw.ts's unconditional controllerchange → location.reload() (the existing DA-02 finding), which can explain a mid-boot reload but does not by itself explain every persisted-state observation.
2. Early autosave / project persistence during boot, including whether a project can become durable before the WelcomePortal flow is semantically settled.
3. A separate startup/navigation race in the supported-UI reset/entry helper itself, now made more plausible by the docs(core): define R-15 secure storage contract (#445) #564 recurrence where the helper sometimes fails to reach nav-mobile or welcome-portal.

The previously noted settings-only isNewUser ambiguity is no longer an outstanding candidate: PR #546 changed seed authority to depend on an actually hydratable/normalized persisted project rather than any truthy preloaded state. That correction does not explain or close the remaining double-boot / startup-navigation behavior.

Harness hardening already landed

ensureWelcomePortalEntry() in tests/e2e/helpers.ts establishes the WelcomePortal entry through supported UI: if "Start a New Project" is not visible after waitForSpaReady(), it uses Settings → Data & Backups → Factory Reset rather than touching storage/React internals directly. tests/e2e/onboarding-entry-precondition.spec.ts regression-tests multiple startup shapes.

This remains the correct direction for deterministic preconditions, but the #564 recurrence proves the current helper is not yet a complete closure of the startup/navigation failure class. Any further remediation should be performed in a dedicated #532 scope, not opportunistically inside unrelated PRs.

Recommended investigation / acceptance criteria

A dedicated #532 remediation should establish which of these is authoritative:

• a real application startup-state/double-boot defect;
• a deterministic harness/navigation defect;
• or a combination of both.

Before closing #532, require evidence that:

• ensureWelcomePortalEntry() reliably reaches its target from each supported startup shape used by CI;
• Chromium and Mobile Chrome no longer fail because nav-mobile / welcome-portal never becomes reachable;
• retries/timeouts are not merely masking the behavior;
• any underlying application startup persistence/reload cause discovered is either fixed or separately tracked with a precise owner;
• unrelated documentation-only PRs no longer intermittently fail this required gate for the same startup-state reason.

Non-goals

• Do not reopen onboarding: WelcomePortal-vs-auto-seed effect race can skip the welcome portal under timing pressure #527 without reproducing its distinct, already-explained mechanism.
• Do not absorb this into security(core/R-15): renderer-neutral encrypted desktop storage, durable migration & identity binding #445/R-15 or unrelated feature/security PRs.
• Do not treat retries, larger timeouts, or skipped tests as root-cause fixes.
• Keep onboarding: project-bootstrap repair effect has three pre-existing edge-case gaps #531-specific bootstrap gaps separate unless concrete evidence reconnects them to this exact failure class.

[qnbs]

Related startup-authority update from PR #546 — 2026-08-31

One candidate observation documented in this issue has now been resolved independently by the S2/#531-A work in PR #546:

settings restored
project absent

is no longer treated as sufficient evidence that a real persisted project exists for initial metadata-seed authority. The boot path now derives that authority from an actually hydratable/normalized persisted project payload, so a settings-only state remains eligible to initialize the synthetic fresh project.

This removes the previously noted const isNewUser = !preloadedState / settings-only conflation as an outstanding candidate for this class of startup behavior.

It does not close #532.

The core unresolved question here remains the separate startup-state/double-boot mechanism that can result in a real project being present before an E2E test expects WelcomePortal. The existing supported-UI ensureWelcomePortalEntry() harness fix remains the correct deterministic test precondition; #546 should not be interpreted as proving or fixing the underlying Service Worker reload / autosave / other startup-state cause.

Recommended current classification:

• settings-only seed-authority ambiguity: RESOLVED by fix: preserve intentionally cleared project metadata (#531-A) #546 once merged;
• E2E WelcomePortal precondition: already hardened;
• underlying double-boot / unexpected early persisted-project root cause: still OPEN / evidence-only investigation.

[qnbs]

Recurrence on unrelated docs-only PR #564 — 2026-09-01

New evidence materially strengthens this issue's classification as an independent startup-state / WelcomePortal-entry determinism problem rather than a regression caused by the current feature work.

Exact recurrence

On PR #564 (docs(core): define R-15 secure storage contract (#445)), exact head:

bf684034afe82d838dcd9bc62bfd9de0aecafbe6

CI/CD run 33478269659 / Playwright job 99764976401 failed while the PR itself changes only the R-15 design contract / migration-ledger documentation and no application, onboarding, export, storage-runtime, or E2E source.

Playwright result:

117 passed
9 skipped
2 failed
2 flaky

The failures/flakes again converge on the existing ensureWelcomePortalEntry() / WelcomePortal startup precondition path:

• onboarding-entry-precondition.spec.ts failed in both Chromium and Mobile Chrome waiting for [data-tour="nav-mobile"] → More;
• export.spec.ts was flaky waiting for getByTestId('welcome-portal') after ensureWelcomePortalEntry();
• the second onboarding precondition case was likewise flaky waiting for welcome-portal.

This recurrence is especially useful because PR #564 is semantically unrelated documentation-only work. It therefore provides additional evidence against treating this class as an R-15/S5 regression.

Current interpretation

The existing issue ownership remains correct:

S5 / PR #564 relation = NONE demonstrated
startup/harness owner = #532
settings-only seed ambiguity = already resolved by #546
underlying double-boot / unexpected startup-state root cause = still OPEN

The prior ensureWelcomePortalEntry() supported-UI hardening remains useful, but this recurrence shows that it has not fully eliminated the nondeterministic startup/navigation failure class under CI.

Anti-cascade / next evidence rule

Do not fix this inside PR #564 and do not reopen #527. Preserve the first-attempt failure. A single same-head targeted rerun is useful only to distinguish intermittent CI/startup behavior from a consistently reproducible gate failure. Repeated retry loops should not substitute for root-cause evidence.

If the same-head rerun passes, retain this recurrence as flake evidence and continue investigating #532 separately. If it fails again with the same path, treat that as stronger reproducibility evidence for a dedicated #532 remediation rather than absorbing onboarding/export changes into unrelated PRs.

[qnbs]

Fresh recurrence on PR #564 exact head 0865895f2c3070b8923556f61134013a0d077eba, CI/CD #2571, Playwright job 99798975581: onboarding-entry-precondition.spec.ts again traversed ensureWelcomePortalEntry() and failed to reach welcome-portal after navigating to #/settings. In this run Playwright ultimately classified that test as flaky; 119 tests passed, 9 skipped. This remains separate from the run's final blocking failure, which was a reproducible Axe contrast defect now tracked in #565. No #564/S5 source ownership is inferred.