Can show:false + ready-to-show + backgroundColor be honoured on system webviews (hidden-paint oracle)? #394

Activity

1. 0monish

   added the

   Task

   issue type on Oct 6, 2026
2. 0monish

   added

   wayfinder:prototypeWayfinder prototype decisionWayfinder prototype decision

   electron-compatElectron compatibility program areaElectron compatibility program area

   on Oct 6, 2026
3. 0monish

   added a parent issue on Oct 6, 2026

   • Wayfinder map: KELD Electron Compatibility Program (Electron 44.x baseline) #391
4. 0monish commented on Oct 6, 2026

   

   0monish

   on Oct 6, 2026

   MemberAuthor

   More actions

   Generated by an AI agent (Claude Code, Fable 5.1) on behalf of @0monish, 2026-10-06, under the map's execution doctrine. Statements are labelled FACT / INFERENCE / UNKNOWN by their author; nothing here authorizes implementation.

   Decision packet

   Decision: Whether ready-to-show on a show:false window can be a true first-frame signal on WKWebView (a host-owned isolated-world double-rAF reporter) or must be a documented divergence that fires at load-finished.

   Classification: needs-experiment · Milestone (YAGNI test against the first proof): next · Reversible: Yes. The outcome only selects which event source feeds the facade's ready-to-show; the facade API is unchanged either way. · Owner: Crate keld-wv (crates/keld-wv/AGENTS.md). No live Linear issue owns ready-to-show: KEL-142, which owns the macOS injection seam, and KEL-139 are Done; KEL-25 (In Progress, GYLDLAB) is the nearest active windowing issue (Linear fetched 2026-10-06). Tracking sits on GitHub #394 under epic #447 until the owner names a Linear home.

   Facts

   • FACT: Electron emits ready-to-show 'when the renderer process has rendered the page for the first time if the window has not been shown yet', states that the renderer 'will be considered "visible" and paint even though show is false', and notes the event is usually after did-finish-load but 'may be emitted before' it for pages with many remote resources. Source: https://raw.githubusercontent.com/electron/electron/v44.4.5/docs/api/browser-window.md lines 35-55, retrieved 2026-10-06.
   • FACT: draw.io's main window does not use show:false or ready-to-show. It is created visible with backgroundColor. ready-to-show appears only in the update-download progress bar; the other show:false windows (CLI export, vsdx import, export3) are never shown. Source: corpus/drawio-desktop@2edf9fb src/main/electron.js lines 714-717, 1085, 1402, 3093; src/main/progress-bar.js lines 44-59.
   • FACT: Zettlr has 14 ready-to-show sites and 15 files with show: false. Source: grep of corpus/zettlr/source, 2026-10-06.
   • FACT: All three keld-wv backends build the window with no hidden-creation option, and the macOS backend emits NavigationReady from navigation finish only. Source: /crates/keld-wv/src/wkwebview/mod.rs lines 460 and 716-723; grep for with_visible returns nothing.
   • FACT: The KEL-64 double-rAF beacon is an external benchmark instrument, not a host-injected script. The only host injection seam is the macOS isolated-world user script from KEL-142. Source: crates/keld-wv/AGENTS.md first-paint rule; crates/keld-wv/src/wkwebview/macos_bridge.rs lines 510-536.
   • FACT: The WebView2 backend avoids document-created script injection because it measured 96-109 ms during renderer boot. Source: crates/keld-wv/src/webview2/mod.rs module header.
   • FACT: WebView2: 'If IsVisible is set to FALSE, the WebView2 is transparent and is not rendered.' Source: https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2controller (ms.date 2026-08-24), retrieved 2026-10-06.
   • FACT: KEL-142 (macOS renderer bridge) and KEL-139 (macOS spine spec) are Done; KEL-25 (hello window on every OS) is In Progress, assignee GYLDLAB; KEL-28 (Linux WebKitGTK window) is Backlog. Source: Linear, fetched 2026-10-06.

   Inferences

   • INFERENCE: The first proof does not need this decision: no step of install, activation, open, edit, save or close waits on ready-to-show, and the updater path is a recorded no-op.
   • INFERENCE: Zettlr on macOS does need it: every Zettlr window is created hidden and shown from the ready-to-show listener, so a missing event means no window ever appears.
   • INFERENCE: On Windows the host would have to keep the WebView2 controller visible inside a hidden parent window; whether that paints is not stated by the Microsoft page.
   • INFERENCE: draw.io's backgroundColor on a visible window is a plain native-background mapping (F02-T5 (feat(window): macOS chrome and capability options for Zettlr (titleBarStyle hidden/hiddenInset, trafficLightPosition, frame:false, backgroundColor, alwaysOnTop, skipTaskbar, fullscreenable, closable/resizable/minimizable/maximizable) #456) scope) and is independent of the hidden-paint question.

   Unknowns

   • UNKNOWN: Whether WKWebView runs requestAnimationFrame and composites while its NSWindow has never been ordered front.
   • UNKNOWN: What document.visibilityState reports in that state.
   • UNKNOWN: The same two questions for WebView2 (hidden parent window, controller visible) and WebKitGTK (realized but unmapped window).
   • UNKNOWN: The injection cost of a reporter script on Windows against the 300 ms first-paint budget.

   Alternatives

   Option	Cost	New invariant created	Existing invariant at risk
   First-frame oracle: host-owned isolated-world double-rAF reporter per engine	macOS extends the KEL-142 seam; Windows needs a measured injection decision; Linux needs a new user-content seam. Each backend needs a hidden-creation path.	ready-to-show fires only after a composited frame exists while the window is still hidden.	The Windows first-paint budget (a regression above 5% needs a waiver); first-paint scoreboard classes must not pool hidden-window samples with visible ones.
   Documented divergence: emit ready-to-show at load-finished	Possible white flash on show; the event order differs from Electron for pages with many remote resources (Electron may fire before did-finish-load).	ready-to-show is a navigation signal, recorded as a scoreboard divergence.	The conformance entry citing Electron's 'rendered the page for the first time' sentence cannot be marked passing.
   Show briefly or off-screen to force a paint	Visible artefacts and focus or Mission Control side effects; breaks windows that must stay hidden.	None worth keeping.	show:false semantics for hidden export and modal windows.

   Recommendation

   Run one macOS-only experiment before choosing; do not spend on Windows or Linux cells until those lanes open. Harness: a throwaway AppKit program outside the repo using only public API, with a WKWebView loading a local page that posts three messages to a script message handler: a timer beacon (liveness), a double-rAF beacon, and document.visibilityState. Arms: A, window ordered front (positive control: the rAF beacon must arrive); A-neg, the same with the rAF script removed (negative control: no rAF beacon); B, window created and never ordered front; B-then-show, arm B ordered front after the bounded wait, recording whether the rAF beacon arrives then. Twenty runs per arm, each ended by the beacon event or by a fixed deadline measured from navigation finish (no sleeps as synchronisation). Exit: B gets the rAF beacon within 2 s in 20 of 20 runs, so choose the first-frame oracle on macOS. B gets the timer beacon but no rAF beacon in 20 of 20 while A passes, so rAF is suspended when hidden: record the load-finished divergence for macOS and stop designing the reporter. Mixed results: report the counts and keep the ticket open.

   Falsifier: The recommendation (that one cheap macOS experiment settles it) is wrong if arm B's result differs between macOS versions in the support range, or if the in-harness result does not reproduce inside the real keld-wv window because of its guardian or window configuration.

   Missing evidence: The macOS arm B observation (rAF beacon, timer beacon, visibilityState) on a real Mac with the OS version recorded. Later, on real devices: the Windows hidden-parent arm and the WebKitGTK unmapped arm.

   Next action: Owner: the agent or session that takes the Zettlr-on-macOS window lane under epic #447, on a real macOS arm64 machine. Build the four-arm harness in a scratch directory and attach a results table (arm, runs, rAF beacons, timer beacons, visibilityState, macOS version) to #394. First check: arm A shows 20 of 20 rAF beacons and A-neg shows 0, which proves the harness before arm B is read. Not on the first-proof path, so no Prompt Tracker node is issued now.
5. 0monish

   added

   milestone:nextNeeded after the first proof (Zettlr or strict profile)Needed after the first proof (Zettlr or strict profile)

   on Oct 6, 2026
6. 0monish

   marked this as blocking on Oct 6, 2026

   • feat(window): show:false, ready-to-show and paintWhenInitiallyHidden on macOS per the F02-A3 outcome #535