Port to Avalonia 12 on a locally built CefGlue.Avalonia (OutSystems/CefGlue#249)

[danielmeza]

Summary

The app now runs on Avalonia 12.1.2. The embedded browser uses the Avalonia 12 port of
CefGlue.Avalonia from the open upstream pull request
OutSystems/CefGlue#249, which this repo builds
locally until upstream publishes it. WebViewControl-Avalonia is removed. MainWindow uses
CefGlue's own browser control.

This is a draft for one reason: CI and every fresh clone depend on code from an unmerged
third-party pull request, built at a pinned commit (see CI and the open questions).

Part of #67. The issue's "Done when" also requires that "a part downloaded in the embedded browser
still imports end to end". I could not show that: it needs an UltraLibrarian account. What I did show
is the download being intercepted into the configured folder, and refused when it would escape it
(see Verification).

What changed since the last push (2026-09-21 17:49)

1. Master is merged in, up to 8e4ed2e (#88 to #118), KiCadSharp 0.4.0 and SExpressions 0.2.0
included. One textual conflict, Views/MainWindow.axaml.cs, plus four places where master's code
needed the Avalonia 12 port applied to it.

• The download handler is master's, whole. Refusing never calls Continue, and a refused id is
  cancelled on its next update (Refused browser downloads are not refused: Continue("") downloads to CEF's temp directory #97, Refuse browser downloads for real, and import only accepted ones (#97) #106); only a download the handler accepted becomes an import,
  and only at the path it accepted; the folder comes from IConfigService, and nothing reads Avalonia
  state on CEF's thread (Browser downloads ignore the download folder set in Settings #108, Use the configured download folder for browser downloads (#108) #111). This branch had its own answer to that last bug — handing the
  handler the view model — and master's replaces it.
• On top of it go this branch's browser changes: CefGlue's AvaloniaCefBrowser used directly, the
  download and life-span handlers set in the constructor instead of through WebViewControl's
  GlobalWebViewInitialized, WebviewUrl followed through NavigateTo, and SameBrowserPopupHandler.
  NavigateTo is also how Find on Ultra Librarian (Give every Part Explorer result an import route or a reason (#47) #100) reaches the browser.
• CefGlue.Common is still 120.6099.211, where OnBeforeDownload returns void, so the override is
  unchanged.
• Settings (Registration scope: Automatic / Project / Global, default Automatic (#71) #96, EasyEDA / LCSC search: JLCPCB's official Components API with the user's credentials, JLCPCB's website endpoint otherwise (#51, #52) #103, Settings: refuse relative download and Target paths, and keep the browser page on save (#112) #115): the text boxes master added use Watermark, which Avalonia 12 makes
  obsolete; they now use PlaceholderText, like the others. The #if DEBUG using Avalonia; that Compile Debug builds again, and build Debug in CI #90
  added in AboutWindow and SettingsWindow goes with the AttachDevTools calls this branch had
  already removed — Avalonia 12's developer tools attach once, in App.
• Program.cs (Log MCP mode to nlog.config's files and stderr, never stdout (#80) #95, Set NLog's log folder from code, and make nlog.config's rules take effect (#98) #104) is merged as master has it: HarfBuzzPreload, SetLogDirectory and the
  MCP logging allowlist are untouched. Only the UseReactiveUI comment changes, because the CefGlue
  build no longer brings in the old Avalonia.ReactiveUI.

2. ReactiveUI.Avalonia 11.4.13 → 12.0.3. This is what made CI red on the last push: the master
merge done through GitHub kept 11.4.13, while the CefGlue.Avalonia built from #249 depends on
ReactiveUI.Avalonia >= 12.0.3, and restore failed with NU1605 (package downgrade). 12.0.3 is
still ReactiveUI 23.2.28 — the ReactiveUI master has — so the #116 search pipeline compiles unchanged.

3. ReactiveUI 24 is not here, and that is a change of plan. See the next section.

ReactiveUI 24: tried, and left out for now

The plan in this PR (and in #67, scope item 4) was ReactiveUI.Avalonia 12.1.x, i.e. ReactiveUI 24.
I ported it and then took it out, because the CefGlue.Avalonia built from #249 cannot run on it:

• ReactiveUI 24 dropped System.Reactive; it is built on ReactiveUI.Primitives.
• That CefGlue build was compiled against ReactiveUI.Avalonia 12.0.3 (ReactiveUI 23) and uses
  System.Reactive in three places: Subscribe in ExtendedAvaloniaNativeControlHost and in
  AvaloniaOffScreenControlHost (every platform), and Observable.Interval(...).ObserveOn(AvaloniaScheduler.Instance)
  in AvaloniaBrowserProcessHandler (the external message pump, created on macOS only).
• With ReactiveUI 24 and no System.Reactive, 4 of Xilium.CefGlue.Avalonia's 206 type references fail
  to bind. Run headless on Linux, the app aborted the moment the browser was created — exit 134,
  System.IO.FileNotFoundException: Could not load file or assembly 'System.Reactive, Version=6.1.0.0'
  from ExtendedAvaloniaNativeControlHost..ctor. This is the whole browser tab, not a corner case.
• Referencing System.Reactive 6.1.0 runtime-only (IncludeAssets="runtime"; at compile time its
  extension methods clash with ReactiveUI.Primitives') gets Linux and Windows working again — I ran
  that variant and the browser loaded — but ReactiveUI.Avalonia.AvaloniaScheduler is still gone, so
  CefGlue's macOS message pump would still fail. Nothing here was run on macOS.

So the branch stays on ReactiveUI 23.2.28 through ReactiveUI.Avalonia 12.0.3, which is the pairing
#249 itself was built against, and where every reference of that build binds.

The port itself is done and checked, and sits on the local branch avalonia12-rui24 in the
worktree this was prepared in (one commit on top of the merge). It moves the Part Explorer pipeline
from System.Reactive to ReactiveUI.Primitives (RxVoid for Unit, ISequencer for IScheduler,
Signal.Return/Signal.Empty, the same Where/Select/Switch/SelectMany/Append/Catch/
ObserveOn/StartWith in the same order), and rewrites AsyncEnumerableObservableExtensions.ToObservable
as a plain IObservable<T> that keeps #86's cancellation rules. A throwaway harness runs 106 checks —
14 for those cancellation rules and 92 view-model checks adapted from #49's harness, under two
stand-ins for Avalonia's dispatcher — and they pass against both that build and a build of master.
It is one git cherry-pick away whenever the question below is answered.

The upstream pull request

• PR: Feature support AvaloniaUI 12 OutSystems/CefGlue#249, "Feature support AvaloniaUI 12", by selway.
  Open, last updated 2026-07-31, still no review.
• Pinned commit: e204172cdf6ad8d048fe0a3a3c0436db8a7c767c, still the PR head. It is fetched from
  OutSystems/CefGlue by SHA, so a later push to the PR branch cannot change what is built here.
• New since the last push: upstream merged #252 and #253 and published CefGlue 120.6099.214
  (2026-09-22). #249 is now CONFLICTING with upstream master, and one of those commits touches
  CefGlue.Avalonia/AvaloniaBrowserProcessHandler.cs (a macOS idle-CPU fix). The pin here is
  deliberately unchanged: 120.6099.211 for CefGlue.Common, and #249 at e204172 for
  CefGlue.Avalonia. Moving to 214 means waiting for #249 to be rebased, or rebasing it ourselves.
• What #249 changes: CefGlue.Avalonia moves to Avalonia 12.1.0; focus event args,
  TopLevel.GetTopLevel instead of GetVisualRoot, DataTransfer instead of DataObject,
  WindowDecorations, ContextMenu.Placement. It drops Avalonia.ReactiveUI 11.0.9 and the
  System.Reactive.Linq preview for ReactiveUI.Avalonia 12.0.3 and AvaloniaUI.DiagnosticsSupport
  2.2.3. CefGlue.Common is untouched by it.

How the local build is consumed

Unchanged from the last push: scripts/pack-cefglue-avalonia12.sh shallow-fetches the pinned commit,
builds CefGlue.Avalonia and copies only that .nupkg into the git-ignored local-packages/ feed, at
version 120.6099.211-pr249.e204172 ($(CefGlueAvaloniaVersion) in Directory.Build.props). The
version names the pull request and the commit, so no published package can satisfy it and restore
cannot silently fall back. CefGlue.Common keeps coming from nuget.org at 120.6099.211. Nothing binary
is committed.

Switching back when upstream publishes: point CefGlueAvaloniaVersion at the published version,
bump CefGlue.Common to match, and delete the script, its CI step and the README paragraph.

CI

Two jobs are red, for two different reasons, and only one of them is about the local package.

• build (CI workflow). This job does build CefGlue#249 from source: ci.yml has had a "Pack
  CefGlue.Avalonia" step before Restore since the first commit here, and it works — it was green on
  run 35625857982 (pack about
  33 s, whole job 1 min 16 s). What failed on the last push was NU1605, the ReactiveUI downgrade
  the master merge introduced. With that pinned correctly, this push is
  green again: pack, restore,
  Release (0 warnings, 0 errors), Debug (0/0) and Format all pass. The pack step logs 71 warnings of
  its own; they come from compiling CefGlue, which does not treat warnings as errors.
• submit-nuget (GitHub's "Automatic Dependency Submission", a dynamic workflow, not a file in this
  repo). This one is the "CI cannot restore a locally built package" case: it runs its own
  dotnet restore without running any repo script, so local-packages/ is empty and restore reports
  NU1603 — "CefGlue.Avalonia 120.6099.211-pr249.e204172 was not found; 120.6099.211 was resolved
  instead" — which TreatWarningsAsErrors turns into an error
  (this push's run). It has
  failed on every push since the local package was introduced, and it cannot be put right from
  ci.yml.
• (The third red check on the last push, "Code scanning AI findings", is GitHub Advanced Security's
  Copilot job; it failed in its own setup, unrelated to this branch.)

Suggestions, not implemented here — pick one and I'll do it:

1. Leave submit-nuget red while this is a draft. The dependency graph cannot be submitted for a
   package that does not exist publicly anyway.
2. Turn Automatic Dependency Submission off for this repository (Settings → Advanced Security →
   Dependency graph) and add a workflow step that runs the pack script first and then submits the
   graph, so the check stays meaningful.
3. Publish the packed CefGlue.Avalonia once to this repository's GitHub Packages feed and add
   that feed to NuGet.config. Every job then restores it normally, and the pack step disappears. It
   still ships an unreviewed third-party build, and it needs a token for restore.
4. Commit the ~42 KB .nupkg to the repo. Simplest for every consumer; a binary in git, and I have
   not done it because the instructions here are to ask first.
5. Wait for upstream. #249 has had no review since July and is now conflicting, so this may be long.

Design

WebViewControl-Avalonia is dropped, not upgraded. Its latest release, 3.120.11, pins Avalonia 11,
its Avalonia 12 issue (OutSystems/WebView#403) is open with no fix, and it is not binary compatible:
with Avalonia 12.1.2 loaded, WebView.ExtraInitialize fails to JIT (AvaloniaObject.get_Item(IndexerDescriptor),
removed in 12) and it runs in the WebView constructor. The app used it only as a host for CefGlue, so
MainWindow now declares views:EmbeddedBrowser, a one-line subclass of CefGlue's AvaloniaCefBrowser
(whose only constructor takes an optional argument, which the XAML compiler rejects as not
parameterless, AVLN3000).

What WebViewControl did, and what happens now:

• Address binding. AvaloniaCefBrowser.Address is a CLR property, so MainWindow sets it from
  WebviewUrl: once when the DataContext arrives, then on every change.
• CEF settings. App already called CefRuntimeLoader.Initialize(...), but WebViewControl's
  WebView constructor called it again with its own settings, so App's never took effect. They do
  now: PersistSessionCookies, PersistUserPreferences, CookieableSchemesList. This is a
  behaviour change; see the open questions.
• New-window links (target=_blank, window.open). WebViewControl sent them to the system
  browser, where a download never reaches InternalDownloadHandler. They now open in the embedded
  browser (SameBrowserPopupHandler), and their downloads are intercepted (measured, see
  Verification). Non-http(s) targets keep CEF's default. Also a behaviour change; see the open
  questions.
• Dead code removed. The six request/resource handler classes at the end of MainWindow.axaml.cs
  were referenced nowhere and depended on WebViewControl types.
• Dropped with WebViewControl, now CEF defaults, not verified: its context-menu, JS-dialog,
  file-dialog, drag and keyboard handlers, and AllowDeveloperTools.

Avalonia 12 API changes: Avalonia.Diagnostics has no 12.x, so AvaloniaUI.DiagnosticsSupport
replaces it, Debug-only, attached once in App.Initialize; binding plugins are gone and the
DataAnnotations validator is off by default, so DisableAvaloniaDataAnnotationValidation goes;
IClipboard.SetTextAsync is an extension method now; TextBox.Watermark → PlaceholderText;
Avalonia.Xaml.Interactions has no 12.x and nothing used it.

Lemon.Hosting.AvaloniauiDesktop 1.1.1 stays. Every one of its type and member references binds
against this build (72 types, 119 members, 0 failures), and the app starts on it.

Verification

All of it on e7a4764, the merge commit this push adds.

• Build: dotnet build UltraLibrarianImporter.sln -c Release and -c Debug, both with
  --no-incremental: 0 warnings, 0 errors.

• Format: dotnet format UltraLibrarianImporter.sln --severity warn --verify-no-changes: clean,
  exit 0.

• Vulnerable packages: dotnet list ... --vulnerable --include-transitive: none, in either project.

• Parser: dotnet run --project src/importer/SampleConsole -c Release -- --test-parser: exit 0,
  reaches === Tests Complete ===.

• Binding check. A throwaway probe binds every type and member reference of the built assemblies
  against the app's own output folder, the way the runtime does. Xilium.CefGlue.Avalonia from #249:
  0 of 206 type references and 0 of 363 member references fail. Lemon.Hosting.AvaloniauiDesktop and
  ReactiveUI.Avalonia: 0 failures. (On ReactiveUI 24 that same probe is what showed the 4 failures
  described above.)

• Runtime, headless. Xvfb, a temp HOME with the XDG directories deliberately not created
  (Resolve special folders to absolute paths even when they do not exist yet (#70) #93), DBUS_SESSION_BUS_ADDRESS pointing at nothing (so the real keyring is never touched), a short
  TMPDIR, no LD_PRELOAD, and env -i otherwise.

  • Startup: the main window opens, the log shows Pre-bound .../libHarfBuzzSharp.so with RTLD_NOW
    (Linux: segfault in HarfBuzz right after the main window opens (CEF's GTK vs HarfBuzzSharp) #78, no LD_PRELOAD needed) and Main window created and configured, and the app runs until
    timeout kills it (exit 124) with no crash markers and no core dump.
  • Search: typed NE555, clicked Search All Providers, and the grid filled with 25 live rows
    from JLCPCB's endpoint (Aggregated search completed for query: ne555, found: 25).
  • Find on Ultra Librarian: clicked on the first row; the app switched to the Web Browser tab, CEF
    started, and app.ultralibrarian.com rendered (its login page, since the search needs an account).
    The status line read "Searching Ultra Librarian for NE555DR…". No crash.

• Downloads, end to end, through the real handler. An instrumented scratch copy of this commit
  (an environment variable picks the first URL and the browser tab; stderr traces every handler
  callback) against a local server that sends Content-Disposition: attachment, with config.json
  seeding DownloadDirectory to <temp home>/custom-downloads:

  Case	Result
  filename="part.zip"	OnBeforeDownload on CEF's thread (uiThread=False), Continue(<custom-downloads>/part.zip), completed at that path, 260,118 bytes, and Detected download for UltraLibrarian: part.zip. One copy of the file, in the configured folder.
  filename=".."	Refused: no Continue, Cancel on each following update until CEF reported it canceled, and "Browser download refused: its file name would place it outside the download folder". No file of the served size anywhere — not in the temp home, not in the browser cache, not in TMPDIR.
  window.open('/good') (a new-window link)	OnBeforePopup target=[…/good] disposition=NewForegroundTab gesture=False, the same browser took it, and the download landed in the configured folder as above.

  No run logged "Call from invalid thread", and none crashed (each ended at timeout, exit 124).

• MCP: ./UltraLibrarianImporter.UI --mcp with initialize, notifications/initialized,
  tools/list and two tools/calls piped in. stdout had 4 lines, all valid JSON-RPC 2.0; the tools
  are search_components, list_providers, get_component_details; list_providers and
  search_components both answered (isError=false, 20 components for NE555); every log line went to
  stderr. Exit 0.

Not verified: the end-to-end import of a downloaded UltraLibrarian archive (needs an account);
Windows and macOS; Flatpak KiCad; JS dialogs, context menus, drag and drop, and CEF's off-screen
rendering mode.

Open questions

1. ReactiveUI 24 (the section above). Options: (a) stay on ReactiveUI 23 through
   ReactiveUI.Avalonia 12.0.3, as this push does, until upstream CefGlue builds against ReactiveUI 24;
   (b) take the ported commit plus a runtime-only System.Reactive reference, which works on Linux and
   Windows and leaves CefGlue's macOS message pump broken; (c) patch AvaloniaBrowserProcessHandler
   in the local CefGlue build (three lines) and offer that upstream on #249 — more unreviewed code
   here, but nothing platform-specific left behind.
2. CI and submit-nuget: which of the five options above? (4) needs your go-ahead to commit a
   binary.
3. New-window links now open in the embedded browser, where before they went to the system browser.
   That is what lets their downloads be intercepted — measured above with window.open. Is that the
   behaviour you want, or should some of them still go out to the system browser?
4. Session cookies now persist (PersistSessionCookies, PersistUserPreferences), because App's
   CEF settings finally take effect: an UltraLibrarian login would survive a restart. Keep it?
5. Lemon.Hosting.AvaloniauiDesktop is unmaintained and built against Avalonia 11. It works today
   (binding check above, and the app starts on it). Replace it now or later?
6. AvaloniaUI.DiagnosticsSupport, which #249 makes a runtime dependency of CefGlue.Avalonia,
   declares no license in its nuspec. It stays out of Release builds here (the direct reference sets
   IncludeAssets=None outside Debug, and it is indeed absent from bin/Release), so it would not be
   distributed, but you may want to keep an eye on it.

What CLAUDE.md should say after this lands

I did not edit CLAUDE.md (it is kept up to date in its own PRs). Suggested changes:

• Commands. Add before the build commands:

  scripts/pack-cefglue-avalonia12.sh must run once per clone before restore: it builds
  CefGlue.Avalonia for Avalonia 12 from Feature support AvaloniaUI 12 OutSystems/CefGlue#249 at a pinned commit into
  local-packages/. CI runs it as its first step.

• Build constraints. Replace the "Avalonia is held on the 11.3 line on purpose" paragraph with:

  Avalonia 12, with a locally built browser. The app is on Avalonia 12.x. CefGlue.Avalonia for
  Avalonia 12 is not published: $(CefGlueAvaloniaVersion) in Directory.Build.props
  (120.6099.211-pr249.e204172) selects the package scripts/pack-cefglue-avalonia12.sh builds from
  the open upstream PR Feature support AvaloniaUI 12 OutSystems/CefGlue#249 at commit e204172. CefGlue.Common is not part of
  that PR and stays on nuget.org at 120.6099.211. When upstream publishes, point the property at the
  release, bump CefGlue.Common to match, and delete the script, its CI step and the README
  paragraph. WebViewControl-Avalonia is gone: it has no Avalonia 12 build and its WebView
  constructor calls an API 12 removed; MainWindow uses CefGlue's AvaloniaCefBrowser (through
  EmbeddedBrowser) directly. Lemon.Hosting.AvaloniauiDesktop 1.1.1 is still built against
  Avalonia 11 but works on 12.

• ReactiveUI paragraph. Replace with:

  ReactiveUI: ReactiveUI.Avalonia 12.0.3 (ReactiveUI 23.2.28), enabled with .UseReactiveUI(_ => { }).
  12.1.x is ReactiveUI 24, which dropped System.Reactive; the CefGlue.Avalonia built from
  Feature support AvaloniaUI 12 OutSystems/CefGlue#249 calls System.Reactive in both of its control hosts and fails to create a
  browser without it, so the app stays on 23 until upstream builds against 24 (Port to Avalonia 12 (requires replacing the CEF browser stack) #67). CefGlue no
  longer brings in Avalonia.ReactiveUI.

• Architecture, item 2. "Avalonia 11 desktop app" → "Avalonia 12 desktop app".
• Code style. The #if DEBUG example now points at files that no longer have it: Avalonia 12's
  developer tools are attached once in App.Initialize, so AboutWindow/SettingsWindow no longer
  carry a Debug-only using. The rule stands; the example needs another file.
• Import flow, Web Browser. Add:

  New-window links open in the same browser (SameBrowserPopupHandler) so their downloads are
  intercepted too.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DHQsqcKVEiAKvCS98Hn4Yh

[danielmeza]

Decisions from the maintainer, so the branch has them on record:

1. ReactiveUI: stay on 23, as pushed (ReactiveUI.Avalonia 12.0.3, the Avalonia 12 line). The measured abort on RUI 24 (exit 134 the moment the browser is created, System.Reactive 6.1.0 missing) settles it. Keep the finished RUI 24 work on its local branch for after CefGlue #249 moves.

2. submit-nuget: leave it red while this is a draft. The real CI build is green and already builds CefGlue #249 from source at a pinned commit. Nothing is committed as a binary, and no repository setting changes.

3. Both behaviour changes stay:

   • links that open a new window open in the embedded browser, which is what lets their downloads be intercepted;
   • session cookies and preferences persist, so a provider login survives a restart.

   Both belong in the PR description as intended behaviour, and in CLAUDE.md when this merges.

Unresolved upstream: CefGlue published 120.6099.214 today and #249 now conflicts with their master, so moving off 120.6099.211 needs #249 rebased. This stays a draft until #249 merges.