Converge the WebView2 environment contract and stop the breadcrumb host stranding its buffers on failure

[drmoisan]

Converge the WebView2 environment contract and stop the breadcrumb host stranding its buffers on failure

Summary

• Converges all three production WebView2 environment creations onto a single owner, so the breadcrumb host, the QuickFiler item preview and the Efc item preview no longer request conflicting environments from one shared user-data folder.
• Adds a bounded retry to breadcrumb host initialization and a visible error state in the folder area on final failure, replacing a silent return that left the user looking at a blank list.
• Drains or explicitly discards the pending breadcrumb document and the outbound message queue when initialization fails, instead of stranding both behind a trigger that only fires on success.
• Routes InitializeBreadcrumbHostAsync failures through the form controller's boundary fault reporter so they reach the user rather than only the log.
• Carries the already-initialized folder predictor and loaded mail-item helper through the pop-out path, and constructs the viewer on the UI thread.
• Splits the 1321-line form controller into six compliant files and moves the edited members of two other over-ceiling files into new partials, under a line-conserving gate.

Why

The breadcrumb folder selector is the primary folder-selection surface on the Efc view, and it was presenting an empty list with no error.

The root cause is that three production sites construct CoreWebView2EnvironmentOptions independently while sharing one user-data folder. Two supplied --incognito and one supplied no arguments at all. A shared user-data folder requires agreeing options across every WebView running in that browser process, so the odd site out fails initialization.

The divergence is a regression with a precise origin. Before 2026-08-27 the two preview sites carried a U+2013 EN DASH in their argument literal, which Chromium silently discarded as an unrecognised token, so their effective option set was empty and matched the breadcrumb host's empty set. Correcting that literal to ASCII made the arguments real switches for the first time and created the conflict. The breadcrumb host was never touched by that correction.

On the failure path the damage compounded. The router stashes a pending document and the outbound queue buffers messages, and both are drained by a single method reachable only through the host's CoreInitialized event. That event is raised only on the success path, so a failed initialization left both buffers stranded with no retry, no error document and no user-visible signal. This is one defect with one trigger, not two independent ones.

What Changed

Core fix

• New QuickFiler/Viewers/WebView2EnvironmentContract.cs owns the user-data folder and the additional browser arguments. Each literal now appears exactly once in the tree.
• All three creation sites read from that contract. The Efc item site additionally moves onto the IWebViewCoreInitializer seam instead of calling the SDK factory directly, which also makes it testable.
• EfcFormController.InitializeBreadcrumbHostAsync gains a bounded retry and reports through TryReportBoundaryFault on final failure; the folder-area label carries the visible error state.
• BreadcrumbBridgeRouter gains an explicit failure notification that clears the pending document, navigates an error banner and discards the outbound queue.
• The pop-out path carries the initialized folder predictor and mail-item helper forward and adopts them when present.

Structure

• EfcFormController.cs is split six ways along its existing region boundaries and is now 266 lines. The split is proven by a multiset conservation gate over non-blank lines.
• Edited members of EfcItemController and QfcCollectionController move into new partials. Both parent files remain over the 500-line ceiling as pre-existing debt this change neither introduces nor resolves, recorded with before and after counts.
• Seventeen new .cs files each carry a matching Compile item in their owning non-SDK-style project file.

Tests

• Eight new test files covering the environment contract, the router failure path, the outbound queue, the form controller retry and reporting, the data-model carry and the pop-out carry.

Architecture / How It Fits Together

WebView2EnvironmentContract is the single owner of the environment inputs. The two preview controllers and the breadcrumb host each read it and hand the result to IWebViewCoreInitializer, which forwards to the SDK. Because every caller now supplies identical options for the shared user-data folder, no site can be the odd one out.

On the failure path, EfcFormController.InitializeBreadcrumbHostAsync owns the retry loop and the reporting decision; the host's SDK event handler stays a thin, coverage-exempt notifier. When the retry is exhausted the controller sets the folder-area label and notifies the router, which clears its pending document, navigates a banner and discards the queue. The success path is unchanged.

Verification

Completed

• CSharpier: Checked 1658 files, exit 0, no write-set file rewritten.
• .NET analyzers, /t:Rebuild: 0 Warning(s), 0 Error(s). Non-vacuity confirmed by 36 compiler invocations with zero skipped CoreCompile targets.
• Nullable analysis, /t:Rebuild with warnings as errors: 0 Warning(s), 0 Error(s), same non-vacuity counters.
• QuickFiler.Test: 1468 of 1468 passed, run in parallel under the repository runsettings.
• TaskMaster.Test regression sweep: 452 of 452 passed, no new failures against the recorded baseline.
• Coverage over the QuickFiler package rose from 81.73% to 82.01% line and 78.04% to 78.24% branch. The new contract file is fully covered. Figures are rolled up from class elements rather than read from the document rate attribute.
• Every regression test was recorded failing before the fix, and each failure was matched against a pre-declared assertion.
• Ten mutations were applied and each produced its pre-predicted failure, then was reverted with hash-verified restoration. This includes a criterion that was already satisfied before this work and therefore could not be observed failing, for which mutation is the only available instrument.
• A structural gate over the three creation sites was observed failing before the change and passing after.
• Manual verification on both entry points was performed by the maintainer against a live Outlook session, with the session log independently checked for initialization failures.

Recommended

• dotnet tool run csharpier check .
• msbuild TaskMaster.sln /t:Rebuild /m /p:Configuration=Debug "/p:Platform=Any CPU" /p:EnableNETAnalyzers=true /p:EnforceCodeStyleInBuild=true
• msbuild TaskMaster.sln /t:Rebuild /m /p:Configuration=Debug "/p:Platform=Any CPU" /p:TreatWarningsAsErrors=true
• vstest.console.exe QuickFiler.Test/bin/Debug/QuickFiler.Test.dll /Settings:scripts/vscode/TaskMaster.cli.runsettings /InIsolation

Backward Compatibility / Migration Notes

• No public API is removed or renamed. The environment contract is additive and internal to the QuickFiler project.
• One member changes accessibility from private to internal so the retry path can be asserted directly; it remains internal to the assembly.
• The six-way split of the form controller relocates members between files without changing behaviour. Callers are unaffected because all parts declare the same partial class.
• Seventeen files are added to two project files. A build that does not pick up the project-file changes will fail to compile the new partials.

Risks and Mitigations

• The environment convergence direction. Converging on --incognito rather than dropping it keeps the preview panes from persisting browsing data. The panes navigate untrusted message HTML and share the user-data folder, so removing the argument would newly persist tracking-pixel cookies and cache. An audit of the three files that generate the breadcrumb document found no use of any browser storage API and no external resource reference, so the breadcrumb document is unaffected by the argument.
• Retry masking a live conflict. A bounded retry can make a still-broken environment look healthy to a user. The manual verification therefore included a session-log check for initialization failures, which is the only observation that separates a genuine convergence from a masked conflict.
• Two files remain over the line ceiling. This is pre-existing debt, recorded with before and after counts rather than silently carried. A full split of either is out of scope for a bug fix.
• Mechanical diff volume. The six-way split dominates the diff. It is a pure move proven by a conservation gate, so it can be reviewed structurally rather than line by line.

Review Guide

Suggested order:

1. QuickFiler/Viewers/WebView2EnvironmentContract.cs — the new single owner, 53 lines.
2. The three creation sites, to confirm each reads the contract: the breadcrumb host, the QuickFiler viewer setup, and the new Efc item environment partial.
3. QuickFiler/Controllers/EfcFormController.Breadcrumb.cs — the retry loop, the reporting decision and the folder-area error state.
4. QuickFiler/Controllers/BreadcrumbBridgeRouter.cs and BreadcrumbOutboundQueue.cs — the failure notification and the explicit discard.
5. The carry path: EfcDataModel.Carry.cs and QfcCollectionController.PopOut.cs.
6. The new test files.

Mechanical and safe to skim: the five EfcFormController.* split parts and the project-file Compile item additions. The split conserves every non-blank line of the original.

Follow-ups

• The two parent files that remain over the line ceiling are candidates for a dedicated split.
• A pre-existing analyzer package version skew in the project files is tracked separately and is unrelated to this change.

GitHub Auto-close

• None. No verified closing issue was reported by the context bundle, so no auto-close bullet is emitted here and the tracking issue is resolved by hand.