LT-22625 Phase-1 base: Avalonia migration spine (UIMode defaults Legacy)

[johnml1135]

The Avalonia foundation for FieldWorks

LT-22625

FieldWorks can now convert a WinForms surface to Avalonia by a specified
procedure instead of by improvisation. Four detail surfaces and a family of
dialogs are here as proof that the procedure works — but the procedure, the
architecture it targets, and the rules that keep it honest are the deliverable.

Open Tools → Options → Interface, set New UI (preview) to New, and
Lexicon Edit, the Lexicon Edit popup, Notebook, and Grammar's Parts of Speech
render in Avalonia, live, without a restart. Leave it at the default and
FieldWorks does exactly what main does.

What "foundation" means here

A conversion is now a procedure with real stops. Understanding the dialog
or slice → agreeing on how it works → deciding what to prove → planning the
replacement → building it → proving it works. The middle three are gates: an
interactive question that ends the turn, not a paragraph to read past.
Analysis is read-only so it is safe to run while a developer explores the live
app; scaffolds never merge until the last stage passes.

Unfinished work is visible, not absent. Anything the Avalonia path cannot
yet render becomes a labeled Unsupported row with a stable automation id —
never a silent omission. Grep for those rows and you have the remaining
worklist. SlicePluginRegistry.Register throws on a double claim for the same
reason: one owner per legacy class, no silent overwrite.

Only reachable code ships. The Avalonia browse/bulk-edit surface was
removed rather than merged inert, and six scalar field kinds were deleted
rather than half-built. What is here is reachable and honest; what is not here
says so on screen.

The extension points are small. A new slice is an ISlicePlugin keyed by
the legacy layout's class= string, so migrating one edits no layout XML. A new surface enters the feature catalog only after its current product route, plugin, lifecycle, accessibility, localization, fallback, and workflow evidence all agree.

Scope, stack, verification

485 files, +82,962 / −465. UIMode defaults to Legacy, and both gate
predicates fail closed, so the default path is main's. PRs #965-#967 are
retired experiments, not a merge stack; their branches remain only for
archaeology. #968 is DRAFT, never merge.

Whole-solution build and full test verification were green before the final
documentation-only lesson update. Current CI is the source of truth for this
head.

---

Reading this a year from now — start here

The sections below are the decision record for the start of the FieldWorks
WinForms→Avalonia transition. They exist because the branch's working
documents — research, audits, rejected designs — were deliberately deleted
from the tree rather than merged. The durable contracts were promoted into
openspec/specs/; the reasoning that explains them is here.

The indexed Avalonia migration lesson cards
preserve the reusable observations, rejected assumptions, evidence needs, and
decision boundaries from the retired follow-ups. They constrain future research;
they do not authorize restoring old code.

The layer cake — how an XML view definition becomes an Avalonia control

Configuration/**/*.xml  (Parts + Layout)
  → ViewDefinitionCompiler        Src/Common/FwAvalonia/ViewDefinition/
       immutable snapshot, fingerprinted, cached by
       (className, layoutName, layoutType, fingerprint)
  → ViewDefinitionModel           the typed IR (a ViewNode tree)
  → DetailComposer.Compose()      Src/xWorks/Avalonia/Composer/
       LCModel-backed; walks object/sequence nodes, MaxDepth 12,
       applies per-project ViewDefinitionOverride
  → ComposedDetail { DetailModel, IDetailEditContext }
  → DataTree : UserControl        Src/Common/FwAvalonia/Detail/
       renders one row per DetailField
  → SliceFactory.Build()          switches on DetailFieldKind, or
       resolves ISlicePlugin, or builds the Unsupported row
  → DetailHostControl             hosts the Avalonia tree in-process
  → RecordEditView.Avalonia.cs    the product entry point

DetailFieldKind is deliberately small: Text, Chooser, ReferenceVector,
Header, Custom, Unsupported.

Two properties worth preserving. Composition is separate from rendering —
the new DataTree only renders a pre-built DetailModel snapshot; it does not
walk XML and does not hold live state across data changes. And the view layer
is LCModel-free: DetailField/DetailModel carry primitives, strings and
delegates, never an ICmObject, which is what lets the whole detail path be
tested headlessly without a language project.

Compilation is memoized process-wide, deliberately not with Lazy<T>, so an IO
failure is not cached as permanent. CompileAsync exists and is tested, but the
product path still composes synchronously on the UI thread — first-compile
latency is absorbed there today, mitigated only by the cache on later shows.

Decisions, and why

The UI gate is split across two assemblies on purpose.
FwUtils.UIModeGates.ShouldUseAvaloniaUI (26 call sites, 20 files) references
no Avalonia type, so a legacy-mode process evaluates it without the CLR loading
Avalonia at all. Per-tool resolution (EditSurfaceResolver,
EditSurfaceRegistry, EditSurfaceSelectionService) lives in FwAvalonia and
is only reachable from code that has already loaded it. Every legacy call site
pairs the check with a [MethodImpl(NoInlining)] helper holding the Avalonia
branch, so the JIT never resolves an Avalonia type on a Legacy path. Write the
obvious inline if (ShouldUseAvaloniaUI(...)) new AvaloniaThing() and you
defeat the whole arrangement — every non-adopting user starts paying to load
Avalonia.

net48 pins Avalonia to the 11.3.x line. 11.3.x is the last line shipping
netstandard2.0 assemblies, which is what lets Avalonia load in-process beside
WinForms on net48. A bump past it breaks hosting, and not necessarily at
compile time. Stay on 11.x until WinForms is gone.

No Avalonia modal windows during coexistence. Avalonia modals are not
supported while WinForms owns the message loop, so a converted dialog is a
WinForms-owned modal hosting Avalonia content (AvaloniaDialogHost), and
ShowModal throws off the WinForms UI thread. A greenfield-Avalonia
Window.ShowDialog() port would corrupt the message loop.

The process is deliberately DPI-unaware. A WPF dialog once triggered DPI
awareness and blurred the entire application. DPI awareness arrives only after
all WinForms is gone; expect shimming until then.

FinalizerSafeSynchronizationContext prevents a process kill, not a glitch.
Avalonia's MicroCom proxies capture the ambient SynchronizationContext and
post native Release calls from finalizer threads. If that lands after the
WinForms marshaling window is torn down — project switch, shutdown, idle GC —
the post throws on the finalizer thread and takes the process with it. It is
installed once, before SetupWithoutStarting(). Reordering the hosting
bootstrap can silently reintroduce a GC-timing-dependent crash.

Routing keys off the legacy class= attribute. ISlicePlugin.LegacyClassName
reuses the exact legacy string, so migrating a slice edits zero layout XML. The
alternative — minting new ids in the IR and updating every layout file — is a
far larger and riskier diff per slice.

DataTree and Slice are reused as names for restructured types. These are
deliberate cross-namespace twins, disambiguated with using aliases at call
sites; the rule is never to rename a type to dodge the collision. They cover
about half of what the legacy types did — state came out of the rows,
composition came out of the tree, writes came out of the keystroke path.

Seams are narrow by design. A seam is a substitution point in Feathers'
sense: product implementation and test double swap without editing a call site.
Seams/ holds six of them and nothing else — an eviction pass moved a
synchronization-context guard and a morph-type helper out to live beside their
consumers. Direct Avalonia APIs remain explicitly allowed at the UI edge. This
is not "wrap everything."

TsString stays the shared text model. Clipboard and drag/drop between
WinForms and Avalonia use the existing "TsString" clipboard format carrying
the same XML native Views copy/paste already used. The migration replaces
rendering and editing, not the data model.

FieldWorks-owned Avalonia strings are .resx, not XLIFF. This reversed an
earlier decision that routed them through LocalizationManager dynamic strings
under the Palaso app id. L10NSharp stays reserved for Palaso/FlexBridge/Chorus
UI.

Paths not taken — the section that stops a dead end being re-proposed

Plan A: extracting a model layer out of DataTree. The roadmap originally
specified pulling DataTreeModel/SliceSpec/IDataTreeView out of DataTree
so both frameworks would share model types. Execution went the other way —
straight to the typed IR, bypassing DataTree internals entirely. What tipped
it: wiring new ports into DataTree internals only serves code that gets
deleted at cutover, so it is throwaway work by construction. DataTree is
frozen legacy, slated for wholesale deletion at end of coexistence.
openspec/specs/avalonia-migration-roadmap/spec.md carries a superseded-requirement
banner pointing here for this rationale.

Every off-the-shelf dense tree/table control. TreeDataGrid — its FOSS line
was archived 2025-10-13 and editing moved behind the commercial Avalonia
Accelerate license, incompatible with FieldWorks' redistribution model; this is
a permanent exclusion, not a revisit-later. ItemsRepeater — on an upstream
deprecation path, no selection or automation-peer support.
Avalonia.Controls.DataGrid — unmaintained Silverlight port with known
virtualization and editing defects. Stock TreeView — does not virtualize;
retained only for small bounded popups.

Canonical view-definition storage. The recommendation was layered JSON:
shipped definitions plus sparse per-project patches keyed by StableId.
Rejected: YAML (new net48 dependency, whitespace hazards); new-schema XML
(indistinguishable at a glance from legacy .fwlayout, which invites
copy-pasting the very vocabulary the migration exists to retire); DB-backed
definitions (opaque to diff, breaks the off-thread immutable-snapshot compile,
removes support staff's inspect-and-delete recovery); C# builders as the sole
store (cannot express customer overrides). This was a recommendation, not a
closed decision.

A launcher/companion-strip middle tier for slice conversion. Rejected so
resolution stays strictly plugin-registry-or-Unsupported and the unmigrated
backlog stays visible instead of hiding behind a half-migrated tier.

A shared base class for the filterable dropdowns. The three controls diverge
in content shape, popup hosting and selection model, so a common base would
fight the divergent parts. A static helper instead.

Lazy DataTree construction, considered to shrink the native-Views blast
radius in RecordEditView: 67 call sites plus a subclass injecting its own
DataTree, for zero benefit — the empty constructor already realizes no native
Views.

Reversals — built, then removed

The Avalonia browse / bulk-edit surface. A complete owned browse stack —
sortable headers, inline cell edit, checkbox bulk-edit, filtering, multi-sort,
drag-reorder columns, RDE new-row entry, diacritic-aware find/replace, CSV
export, per-cell UIA peers, ~200 tests — was built, reviewed, and then pulled
rather than merged inert. Sort, filter, bulk-edit and selection were never
wired through to the real RecordClerk, so no UI mode could reach the
interactive features; it only ever rendered alongside the hidden-but-functional
legacy BrowseViewer. Browse and list tools use the legacy BrowseViewer, full stop. Retired #967
assumed the dormant implementation still existed and therefore cannot be
rebased or cherry-picked. The browse lesson card
records the reusable contracts and the evidence required before any new design.

Three disconnected tracks, converged. Before this branch opened there were
three: a clean seam layer built but wired to nothing, a typed view-definition
IR consumed by nobody, and the only working end-to-end renderer — a spike stack
on a hand-written three-field lossy DTO — ignoring both. The spike was retired
and the preview host moved onto the same detail-model boundary as product code,
so there is no duplicate UI stack to keep in sync. Surviving runtime types were
renamed by role rather than spike history. This convergence is the reason the
branch exists in the shape it does, and it is visible in no single commit.

The Chorus notes bar. Built, including a reverse-engineered LibChorus
file-format compatibility contract, then removed unregistered along with the
browse surface. The Messages slice keeps its census route.

The dialog-launcher-as-slice-editor seam. Removed in favor of the simpler
plugin-registry-or-Unsupported model.

Six scalar field kinds and the picture/media path. Boolean, Date,
EnumCombo, Integer, Image, Command, plus the picture editor and its
media seam, were deleted rather than half-built. Each now renders as an
Unsupported row — a scope narrowing, not a defect.

Free Popup dropdowns → Flyout. Free popups render in their own top-level
and misplace under fractional display scaling. A regression test now asserts no
Popup exists in the logical tree while a dropdown is open, so the pattern
cannot silently return.

The migration's own vocabulary. "Region" — a word invented during the
migration — was replaced throughout with "Detail", matching the legacy
DataTree/Slice idiom, and the invented "Lexical" prefix was dropped
wherever the concept is generic. The user-facing toggle stopped being labeled
"Lexical Edit UI", which named the internal project rather than what the user
was choosing. Migration-invented words are a tax on everyone who arrives later.

Surprising findings — where investigation contradicted the assumption

• Legacy DataTree silently drops the same part references the new importer
  drops — roughly 63 of them. The importer's "unresolved" list matches a
  pre-existing legacy gap exactly; it is not a regression.
• Shipped XML layouts import far less cleanly than expected — measured at
  ~70.5% of elements and ~51.1% of attribute occurrences. That number drove the
  explicit per-node diagnostic-drop taxonomy instead of silent loss.
• The IR models neither ghost items nor if/ifnot conditionals — 230
  occurrences across shipped files. Ghost, conditional and chooser-link metadata
  was reserved in the schema before the format froze, specifically to avoid an
  early breaking formatVersion bump when those land.
• A GenDate editing bug shipped green because every test used year-only
  dates. Composing from GenDate.ToLongString() let the parser seed the year
  from the first digit run, silently corrupting day- or month-precise dates.
• Span/link/ORC edit affordances were a production no-op: focusable trigger
  buttons stole focus from the text box before reading its selection, collapsing
  it to a caret. Invisible to tests that set selection directly instead of
  clicking — a warning about that entire class of test.
• Lexicon Browse cell editing is effectively dormant even where wired — no
  shipping browse column is both editable="true" and a simple field. The value
  is in the Edit view and in bulk-edit.
• Typing-latency evidence measured only the managed model layer (~0.01
  ms/key). That is not an end-to-end claim; real layout, shaping, render and IME
  latency remain unmeasured. Do not cite it as proof the UI is fast.

What this does NOT authorize — the limits of the XML retirement

XML retirement is per-surface, never global. A surface may disable runtime XML
only when every applicable blocker family clears for the layouts it loads:
custom fields, ghosts, conditionals, menus and hotlinks, styling, table/browse
XML, chooser metadata, parameter substitution, cross-class part resolution,
dynamic editors, native-viewing coupling.

Repo-wide XML deletion additionally waits on browse views in every area,
Interlinear, Notebook/Grammar/Lists detail, and publishing layouts — none of
which this branch authorizes. Any global "XML is gone" claim would be false for
years.

The same applies to the native boundary: a region is not migrated while it
still calls RootSite/IVwEnv/native Views for display, layout, hit-testing,
selection or editor realization. Linguistics services — XAmple, spelling, ICU,
encoding converters, parsers — may remain behind explicit service contracts,
because they do not own the UI. Without that distinction "no native code" would
have been unachievable and therefore meaningless.

Deferred, and what would unblock it

• New mode is narrower than the dialogs it replaces — 20 // PARITY markers
  across 18 files (allomorph type-mismatch warning, link-allomorph and MSA
  first-item pickers, Insert Entry duplicate search not matching gloss, MGA
  catalog import). Legacy is unaffected by all of them.
• Seven follow-up tool names remain reserved, but their retired surface code
  does not ship here. Analyses and the six rule-formula routes stay Legacy.
  PRs Phase-1 follow-up: Avalonia interlinear editor (Words Analyses) #965 and Phase-1 follow-up: Avalonia rule-formula editors (Grammar) #966 are archaeological sources only; the
  interlinear
  and rule-formula
  cards require fresh characterization and current-tree design before a route
  can be proposed for activation.
• StText multi-paragraph editing — designed, not wired. ORC-embedded runs
  stay permanently read-only by design. A content census found such content only
  in sttext fields; the trigger to revisit is real project data showing it in
  string/multistring fields.
• Feature-structure editor — control and tests ship LCModel-free; wiring to
  the MSA/MGA dialogs and the create-new-feature catalogs is deferred.
• Command/focus bridge to xCore — deferred to the shell phase, to avoid
  over-preserving legacy quirks while the surface is still moving. The hidden
  DataTree + DTMenuHandler that routes legacy right-click commands is a
  contract-gated command-routing exception, not a viewing exception, and is
  named for removal then.
• WebView2 for the ~10 Gecko/XULRunner surfaces (dictionary preview,
  configure-dictionary, MGA help, print/PDF). Blocked on making XULRunner
  startup lazy first — today a missing Firefox folder is an unconditional hard
  crash at app start — and on validating per-surface Graphite-loss warnings. The
  expensive part is the DOM/JS interop ports, not swapping the browser.
• Graphite is supported through the transition with graded per-writing-system
  warnings rather than retired first. The re-research that forced that reversal:
  HarfBuzz's Graphite2 shaping is opt-in, not default-enabled, so "Avalonia uses
  Skia/HarfBuzz" does not by itself prove shaping parity.
• Mouse-drag selection over-grow in the multi-WS field is open and
  documented, not fixed: the headless backend does no text hit-testing, so the
  defect cannot be reproduced or self-validated there. It needs a real rendered
  window.

How it stays off by default — the gate, in detail

Two predicates, both ordinal-ignore-case equality against a single "New"
literal, both failing closed on null, empty, whitespace, a corrupt settings
file, or any other value. Neither has a negation or fallback that could return
New accidentally.

Gate 2 is never more permissive than gate 1: before the preference is consulted,
an unregistered tool forces WinForms, and a per-tool opt-out
(UIModeDisabledTools) forces WinForms. A blank tool name is the one case where
gate 2 adds no narrowing — it defers to the preference, which still defaults to
Legacy.

Every legacy else-branch is equivalent to main, including the
LexReferenceMultiSlice restructure, traced case by case. The settings-migration
path is untouched.

Shared code changed outside the gates, in full.
DTMenuHandler.OnDisplayDataTreeInsert gained
|| m_dataEntryForm.IsExternalCommandAdapter; DataTree.IsExternalCommandAdapter
defaults to false and is set true only by New mode's hidden command-routing
adapter, so the clause never fires under Legacy and the check evaluates
identically to main. TsStringWrapper went internal → public with an
additive FromXml factory and Xml property for the clipboard bridge; no
existing member changed behavior.

Visible at the default anyway. The new Options chooser in both the WinForms
and Avalonia dialogs; two new settings (UIMode, UIModeDisabledTools);
per-column Name/AccessibleName on legacy browse filter-bar combos instead of
a uniform "FwComboBox" literal, an intentional screen-reader improvement
pinned by a WinForms UIA test; and FwAvalonia/FwAvaloniaDialogs now
referenced by FieldWorks, xWorks and LexTextControls, so the Avalonia
binaries deploy with every build.

Known defect, not fixed here: three <see cref> references to the deleted
LcmChooserDialogLauncher survive and will warn as CS1574.

How this is tested

Everything is net48 — there is no separate build lane for the Avalonia work,
because the legacy-vs-Avalonia choice is a runtime product switch, not a build
contract. ./build.ps1 and ./test.ps1 remain the only entry points.

Three verification surfaces, in the order a migrator uses them:

1. Headless tests — Avalonia.Headless.NUnit's [AvaloniaTest], with a
   TestAppBuilder configured .UseSkia() and UseHeadlessDrawing = false, so
   tests capture real rendered frames rather than layout alone.
   FwAvaloniaRuntime.AppBuilderOverride is the seam that lets integration
   tests driving RecordEditView run without popping real Win32 windows.
2. The preview host (Src/Common/FwAvaloniaPreviewHost/) — runs a surface
   standalone, no language project needed. It isolates whether a bug is in our
   code or in the WinForms-hosting plumbing.
3. Render snapshots — DialogSnapshot.Capture always writes a real Skia PNG
   to a gitignored folder even on a passing test, for eyeballing, paired with
   DialogLayoutAssert as the deterministic tripwire for overlap, zero-area
   text and crowding.

ViewDefinitionModel.ToSnapshot() is the semantic lane: a deterministic text
dump of the typed IR. EngineIsolationAuditTests pins isolation from native
Graphite/Views. A dedicated pin test guards FwAvaloniaPlatform.IsHeadless,
which resolves Avalonia internals by reflection — an Avalonia bump could
relocate them and make headless detection silently return false forever with no
compile error.

---

This change is

[github-actions]

NUnit Tests

    1 files  ±    0      1 suites  ±0   8m 53s ⏱️ - 2m 7s
5 776 tests +1 463  5 695 ✅ +1 455  81 💤 +8  0 ❌ ±0 
5 785 runs  +1 463  5 704 ✅ +1 455  81 💤 +8  0 ❌ ±0 

Results for commit 93feb6e. ± Comparison against base commit 8d54b33.

♻️ This comment has been updated with latest results.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 80.67623% with 903 lines in your changes missing coverage. Please review.
✅ Project coverage is 36.42%. Comparing base (84a4850) to head (93feb6e).
⚠️ Report is 18 commits behind head on main.

Files with missing lines	Patch %	Lines
Src/Common/FwAvalonia/Detail/DetailModel.cs	78.09%	77 Missing and 105 partials ⚠️
Src/Common/FwAvalonia/Detail/FwFieldControls.cs	81.65%	115 Missing and 64 partials ⚠️
.../Common/FwAvalonia/Detail/FwStructuredTextField.cs	78.34%	41 Missing and 48 partials ⚠️
Src/Common/FwAvalonia/Detail/FwOptionChooser.cs	84.04%	32 Missing and 46 partials ⚠️
Src/Common/FwAvalonia/AvaloniaDialogHost.cs	54.54%	34 Missing and 16 partials ⚠️
Src/Common/FwAvalonia/AvaloniaHostControlBase.cs	48.80%	33 Missing and 10 partials ⚠️
...Controls/DetailControls/MorphTypeAtomicLauncher.cs	56.94%	19 Missing and 12 partials ⚠️
Src/Common/FwAvalonia/Detail/DetailFocusMemory.cs	71.15%	14 Missing and 16 partials ⚠️
Src/Common/Controls/XMLViews/FilterBar.cs	40.47%	16 Missing and 9 partials ⚠️
Src/Common/FwAvalonia/Detail/LexiconFirstSlice.cs	76.34%	16 Missing and 6 partials ⚠️
... and 19 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #964      +/-   ##
==========================================
+ Coverage   32.99%   36.42%   +3.43%     
==========================================
  Files        1202     1361     +159     
  Lines      278168   296281   +18113     
  Branches    37151    40311    +3160     
==========================================
+ Hits        91781   107930   +16149     
- Misses     158537   159005     +468     
- Partials    27850    29346    +1496     

Files with missing lines	Coverage Δ
Src/Common/Controls/DetailControls/DataTree.cs	43.73% <ø> (+6.18%)	⬆️
Src/Common/FieldWorks/FieldWorks.cs	0.73% <ø> (ø)
Src/Common/Framework/MainWindowDelegate.cs	2.40% <ø> (ø)
Src/Common/FwAvalonia/CompactDialogStyles.cs	100.00% <100.00%> (ø)
...c/Common/FwAvalonia/Detail/DetailStructureRules.cs	100.00% <100.00%> (ø)
.../Common/FwAvalonia/Detail/DetailViewingServices.cs	100.00% <100.00%> (ø)
Src/Common/FwAvalonia/Detail/MorphTypeSwapLogic.cs	100.00% <100.00%> (ø)
Src/Common/FwAvalonia/FwAvaloniaDensity.cs	100.00% <100.00%> (ø)
Src/Common/FwAvalonia/FwCheckBoxStyle.cs	100.00% <ø> (ø)
Src/Common/FwAvalonia/FwPosChooser.cs	87.82% <ø> (ø)
... and 117 more

... and 158 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.