[Tracking] macOS xwidget-internal: remaining gaps after #297

[tag-und-nacht]

Long-term tracking issue for the macOS half of #22. It stays open until the
boxes below are checked; update the list rather than closing it when one lands.

Follow-up to #297, which lands the native WKWebView overlay and flips
xwidget-internal to provided on macOS. That PR is deliberately partial, and
the items below are the gaps the review agreed to track rather than block on.
They are listed roughly in the order a user notices them.

Linux is unaffected by all of this. Its inline browser is the WPE/dma-buf
path, xwidget-internal still answers NotBuilt there, and ledger 190's
missing subrs are still open. Nothing here changes that.

What works today on macOS

xwidget-webkit-browse-url on the primary frame: creation, navigation,
placement, clipping, hiding, resize, mouse input through the responder chain,
and xwidget-webkit-execute-script without a callback. Verified against a real
configuration rendering MathJax and Mermaid.

Remaining gaps

• Secondary top-level frames. sync_inline_web_views runs only for the
  primary frame (render_thread/render_pass.rs, guarded by
  if is_primary_frame), and WkWebViewHost binds to one content view
  (backend/wkwebview/mod.rs, host: Option<Retained<NSView>>). An xwidget
  displayed in a second frame gets no view at all. GNU keys the view off
  s->f and has one xwidget_view per (model, frame) pair
  (src/xwidget.c), which is the shape to port.

• Real WKNavigationDelegate / KVO events, and measured load progress.
  Nothing produces InputEvent::WebKitLoadFinished — the variant exists and
  has neither producer nor consumer — so
  xwidget-webkit-estimated-load-progress is 0.0 before a navigation and
  1.0 the moment one is dispatched, rather than measured. GNU reads
  WebKitGTK's continuous estimated-load-progress property. WKWebView
  exposes the same thing through KVO on estimatedProgress, plus
  didFinishNavigation: / didFailNavigation: on a WKNavigationDelegate.
  Title and URL changes (WebKitTitleChanged, WebKitUrlChanged) are in
  the same position: #[cfg(feature = "wpe-webkit")] only.

  The user-visible consequence: a script run immediately after enabling a
  preview is a no-op, because the page has not loaded and nothing says so.
  

• JavaScript result callbacks. xwidget-webkit-execute-script's
  optional FUN currently signals rather than being silently dropped —
  a caller that passed it would otherwise wait forever for a call that never
  comes. Delivering a result needs a channel from the render thread back to
  the Lisp thread. Both backends pass a nil completion handler today, so
  this is not macOS-specific. Two in-tree callers are affected:
  xwidget-webkit-get-selection (lisp/xwidget.el, behind
  copy-selection-as-kill) and xwidget-webkit-insert-string.

• Keyboard focus handoff. Not implemented in either direction. Mouse
  input works because the view is a real subview in the responder chain;
  keys are not routed to or reclaimed from the web view.

• Frame-aware lifecycle ownership. WkWebViewHost currently owns every
  view for one window and is reached from two places
  (render_thread/asset_commands.rs and render_pass.rs). Consolidating
  creation, attachment, replay and teardown into one frame-aware runtime
  module is a prerequisite for the secondary-frame item above, not just a
  tidy-up.

• The per-frame glyph scan and its temporary allocation.
  sync_inline_web_views filters FrameGlyph::Xwidget out of the whole
  presented glyph buffer and builds a Vec of placements on every presented
  frame, including frames with no xwidget in them at all. It is guarded by
  host.is_empty(), so a session with no web views pays nothing, but a
  session with one pays on every frame.

• A nested AssetCommand::WebKit(WebKitViewCommand). The native
  backend's conversion in backend/wkwebview/command.rs matches the five
  WebKit* variants and hands everything else back, so a future
  AssetCommand::WebKit* variant compiles without reaching the native
  backend and the enumerated conversion test still passes. Nesting the
  shared command inside AssetCommand would make the conversion itself
  compiler-checked. Touches the producers in neomacs-bin/src/main.rs
  and the WPE arms in render_thread/asset_commands.rs, which is why it
  is a follow-up rather than part of feat(macos): inline xwidget web views via native WKWebView #297. (From the round-three review.)

Documentation

docs/building.md states these limits in the macOS section, so a user meets
them before filing. Please keep the two in step.

[tag-und-nacht]

Status against main after 3a8368eea (the neomacs-webview service) and #327, which builds on it:

• Secondary top-level frames — done by 3a8368eea: synchronize_webview_presentations (render_thread/frame_ingest.rs) iterates every top-level window, MacPlatform keeps a HostWindowId → NSView map, and MacWebView::present re-parents the clip view when the host changes. One view per host is enforced by AttachedToAnotherHost, matching GNU's one-window-per-view rule.
• Real WKNavigationDelegate / KVO events, measured progress — the delegate came with 3a8368eea; macOS xwidgets: build and ship the WKWebView backend, KVO progress and GNU load-changed events, keyboard focus, placement caching (#300) #327 adds KVO on estimatedProgress/title/URL (with a wake, so idle sessions see intermediate values), reports redirect and commit, and delivers GNU's (xwidget-event load-changed XWIDGET "load-started"|"load-redirected"|"load-committed"|"load-finished") to Lisp, which xwidget-webkit-callback needs and never received. xwidget-webkit-goto-uri resets progress to 0.0 instead of writing 1.0.
• JavaScript result callbacks — done by 3a8368eea (evaluateJavaScript:…completionHandler: → ScriptFinished → XwidgetFrontendEffect::InvokeScriptCallback); xwidget-webkit-execute-script no longer signals on FUN. Verified on the GUI: FUN received "Example Domain / 129".
• Keyboard focus handoff — macOS xwidgets: build and ship the WKWebView backend, KVO progress and GNU load-changed events, keyboard focus, placement caching (#300) #327 ports src/nsxwidget.m: keyDown: on a WKWebView subclass evaluates GNU's xwHasFocus() and forwards to the Emacs view unless an INPUT/TEXTAREA is active; GNU's xwScript and keyDown message handler return focus on C-g; focus intents use -[NSWindow makeFirstResponder:]. Not ported: the isearch-mode special case (needs Lisp state the AppKit thread cannot read).
• Frame-aware lifecycle ownership — done by 3a8368eea (WebViewSystem in crates/neomacs-webview/src/system.rs, one display-runtime edge).
• Per-frame glyph scan — 3a8368eea moved it out of the render pass and deduplicated downstream; macOS xwidgets: build and ship the WKWebView backend, KVO progress and GNU load-changed events, keyboard focus, placement caching (#300) #327 gates the walk on WebViewPlacementInputs so it runs once per presentation, not per event-loop pass.
• Nested AssetCommand::WebKit(WebKitViewCommand) — done by 3a8368eea as the flat AssetCommand::WebView(neomacs_webview::WebViewCommand) / InputEvent::WebView(WebViewEvent); every conversion is an exhaustive match.
• Documentation — macOS xwidgets: build and ship the WKWebView backend, KVO progress and GNU load-changed events, keyboard focus, placement caching (#300) #327 rewrites the macOS section of docs/building.md and the citations in the xwidget-internal C-feature row and the coupled-variable table.

Found on the way and fixed in #327's first commit: after 3a8368eea a macOS --features webview build did not compile (remove_webview was Linux-only), the darwin production capability row requested no features, and neovm-core/build.rs still advertised xwidget-internal from the target alone — so a production macOS binary provided the feature and failed at make-xwidget with NotBuilt.

Remaining, stated in docs/building.md: the isearch-mode key rule, and OS-level persistent-profile isolation only on macOS 14+.

[tag-und-nacht]

Status after the PR #327 review round (commits 90ea92f and 4b84b1f on that PR):

Done in #327: native-boundary validation of the page's answers (NSNumber/NSString downcasts, closed FocusProbe/KeyDownMessage types), a host epoch that drops key probes completing after the view changed or lost its host, attachment keyed on the native view's identity, and one PageLoadState owning milestones, observed progress, deduplication and terminal ordering; a lost title/URL is now reported as empty.

Still open, explicitly:

• isearch-mode key routing. GNU sends every key to Emacs while buffer-local isearch-mode is non-nil (nsxwidget.m:247-253, emacs-31.0.90). That is a buffer-local Lisp read from the AppKit thread; the render thread cannot ask Lisp synchronously, so a page input keeps the keys while searching. Needs a pushed "isearch active" flag from the evaluator to the web view (or an equivalent typed input policy) before it can be ported.
• urlScriptBlocked key routing. GNU sends every key to Emacs without probing when the response's Content-Security-Policy: sandbox lacks allow-scripts (nsxwidget.m:255-260, populated at :168-191). Not ported; in such a document the probe fails and the key goes to Emacs anyway, which converges on GNU's answer by accident.
• Allocation in synchronize_webview_presentations. Placement caching removed the per-event-loop glyph walk; the synchronization path still allocates the child inputs, the scene/live-host/stale-host collections and clones the cached placements each pass. Performance follow-up.
• Windows and PageLoadState. WebView2 keeps NavigationMilestone::normalized_events (it has no second progress source, so no duplicate 1.0 today); adopting the shared state there is a follow-up.