Windows first-run onboarding: current five-page physical-input qualification remains

Current reconciliation - 2026-11-09

The original connection-order/UIA defects were fixed by the accepted native stack, and the historical beta27 clean-Sandbox four-page packaged first-run/Connected Welcome/persistence execution below remains earned evidence. The page-count gap has since been implemented in PR #905: current main has five pages, with One window per line of work before backend selection.

Still open / Partial: current ordinary packaged five-page first run/reopen and native physical-keyboard qualification; no Narrator/screen-reader conformance is inferred. #779 retains the page-level paired visual obligations. #965's bounded normal onboarding during Create & Open is not a fresh installed-package physical-keyboard first-run flight. The old false-Disconnected/no-tree title is no longer a current source defect claim.

The original report, acceptance criteria and historical evidence below are preserved; the dated scope/progress above supersedes obsolete missing-feature claims.

Describe the bug
On first launch, Onboarding.showFirstRun (graphcode-windows/src/App.zig, around lines 941–953) runs a modal "Welcome to GraphCode" dialog (window class GraphCodeWindowsOnboarding) before self.client.connect() (around line 997). While the dialog is open:

The main window is disabled but displays "Disconnected" and the red "GraphCode daemon unavailable…" banner, even though a daemon is running and reachable. The CLI connected fine at the same time.
The daemon receives no connection from the shell until the dialog is dismissed.
The onboarding dialog exposes no UI Automation descendants (AutomationElement.FromHandle(...).FindAll(Descendants, TrueCondition) returned nothing). Its Skip and Continue controls are custom-drawn and not reachable by assistive technology.

This made a working build look broken, and I spent a long time diagnosing a "connection failure" that was really the hidden modal.

To reproduce

Start graphcoded.exe with GRAPHCODE_SUPPORT_DIR set to a sandbox directory.
Launch graphcode-windows.exe with the same GRAPHCODE_SUPPORT_DIR, and no %LOCALAPPDATA%\GraphCode\onboarding-seen file.
The main window shows "Disconnected"; the daemon logs no shell connection.
Click Skip on the onboarding dialog. The daemon logs client connected, the banner clears and "Open Folder…" appears.

Expected behavior

Connect to the daemon independently of onboarding, or show a neutral "Finishing setup…" state instead of an error banner.
Make sure the onboarding dialog is foreground and owned by the main window.
Expose a proper UIA tree (buttons with names) for the dialog's controls. Record any parity-ledger impact in investigation/ui-parity-matrix.md.

Environment

GraphCode version: 0.1.77 label, built locally from commit 59ebed1
OS: Windows 11 Enterprise 26200 x64

Additional context
App.zig is a shared surface; coordinate edits per AGENTS.md.

Status audit — 2026-10-01

Classification: still reproducible/source-supported startup-order defect plus accessibility gap. Recommendation: keep open. Confidence: high.

The first-run modal still runs before client.connect() (App.zig onboarding, connect). WindowsOnboarding.zig remains a custom-drawn modal without a UIA/WM_GETOBJECT provider; existing tests cover state/click logic, not assistive-technology reachability. #563 corrected the ledger only, and #568 did not launch first run.

Remaining acceptance criteria: begin daemon connection independently of the modal or show a truthful neutral setup state; expose named keyboard-operable UIA page/actions with deterministic focus; preserve foreground/modal teardown; and exercise package install → first launch → onboarding → connected Welcome using native keyboard and UIA. Runtime evidence must remain distinct from unit/hidden-window coverage.

Preview priority: P0; every first-time tester encounters this path.

Start daemon connection before first-run onboarding

Normalize onboarding provider line endings

Implementation update — 2026-10-01

Classification: source-fixed; remaining acceptance is native/package evidence. Recommendation: keep open until the final first-run flight is witnessed.

Native stack #579 → #580 merged through stack #581 at accepted main acdb2a625c93046b9443d2437361ef5464b0f347.

Implemented progress:

the daemon callback and DaemonClient.connect() are now scheduled before genuine first-run onboarding enters its modal message loop, while ordinary startup and automation hooks retain the previous late connection point;
onboarding now exposes a named UI Automation fragment tree for the current page, Skip, Back, Continue/Get Started, and backend actions;
UIA Invoke/SetFocus, mouse input, and Tab/Shift+Tab/Enter/Space share one deterministic action/focus model with visible focus outlines;
the shared shell provider changed only by the narrow include used to compile the isolated onboarding provider.

Evidence:

layer 1 focused ordering GREEN 1/1 and full App 731/731;
layer 2 focused/provider-linked onboarding roots 13/13, full App 734/734, and ReleaseSafe build passed;
an isolated shown-window probe discovered all four pages and named actions, invoked navigation/backend controls, observed selected backend status, set UIA focus to Get Started, and posted native WM_KEYDOWN Tab traversal;
all exact-head required checks passed after rerunning one timed-out/post-action Windows validation shard; the unchanged-source rerun completed terminal/contracts validation and post steps successfully.

Remaining acceptance criteria:

run the ordinary packaged install → first launch → onboarding → connected Welcome path with production graphcoded;
witness desktop-level native keyboard operation rather than only posted WM_KEYDOWN;
record screen-reader/assistive-technology behavior if claiming conformance.

Preview priority: P0 evidence gate. The diagnosed source defects are fixed; the issue stays open so a unit/hidden-window result is not mistaken for the packaged first-run qualification.

Post-queue reconciliation PR #596 merged at main 41b4d9278f90b02c54262bf91d0410f710fef66a. The source fixes remain accepted, but this issue is still correctly open and queued: closing evidence requires explicit authorization for an owned Windows client, exact package install/upgrade/uninstall, ordinary production graphcoded first launch through onboarding to connected Welcome, desktop-native keyboard/UIA, one named authenticated backend/version with bounded credits, and any claimed assistive-technology observation. While the user is away these are recorded as NotExecuted, not failure or success; no unattended package/native mutation will be attempted.

Expose Windows onboarding to UI Automation

Track every Partial parity row in an issue; drop 150% and fixed backe…

Still open: NotExecuted. Run: GraphCode-DevBox-Return-testing-gaps (attempt 2, installed beta26, 100%, injected input). Run B (operator physical keyboard) was not performed in this run.

Local Windows Sandbox run, 2026-10-13 (published 0.1.78-windows.beta27, ZIP 9b485543…): the packaged first-run path passed. Physical input: NotExecuted.

Run in a clean Windows Sandbox (per-instance vGPU disabled), with keys injected by SendInput inside the guest. Evidence is local in C:\gc-logs\556-sandbox\; all 562 hashes were re-verified.

Passed

Install. Setup Verify and Install both exited 0, and the scheduled-task graphcoded ran.
Connection behind onboarding. The main window showed "Connected · protocol v2" behind the onboarding modal, with no daemon-unavailable banner. The shell's own named-pipe client was connected to the installed daemon (PIDs checked).
Ownership. Onboarding is owned by the main shell window and is in the foreground; the main window is disabled while it is open.
UIA. The tree exposes named nodes: the page, Skip and Continue.
Keyboard. 29 asserted keystrokes went through all four pages: Tab, Shift+Tab, Enter, Space, Back and Get Started. Each backend was selected and showed UIA ItemStatus Selected.
Connected Welcome after Get Started, and the marker %USERPROFILE%\.graphcode\onboarding-seen was written.
Relaunch. After File > Exit, a relaunch with a new PID opened straight to Welcome. Onboarding did not reappear; I reviewed relaunch-welcome.png myself.

Still open

Physical keyboard: NotExecuted. The operator wasn't available. The Phase B harness (foreground and focus sampler, plus a WH_KEYBOARD_LL hook) is ready.
Screen reader: not tested, so no claim.

Notes

The main window paints "Connected", but its UIA status node reads "Ready". UIA can't be used to check the connection state.
macOS onboarding now has 5 pages ("One window per line of work"); Windows has 4. That's a parity gap outside this issue's scope.

Keeping this open until a physical-keyboard pass is recorded. That pass can now be done in a local Sandbox; a Dev Box isn't needed.

Narrowed to macOS scope (2026-10-13). macOS is the ground truth, so requirements macOS does not have are no longer parity requirements. This was checked against macOS source by the parity extras audit; citations are in the audit and the ledger.

Dropped: the "Finishing setup�" neutral state (macOS has none).

Remaining requirement:

Connect to the daemon independently of onboarding, with no false "Disconnected" or error state while it is open.
The dialog is owned by the main window and in the foreground.
Its controls are named and accessible, and keyboard-operable (Return advances or finishes).
The seen state persists, and onboarding can be reopened from Help.
Its pages match macOS. macOS has five; the missing fifth page is tracked in Windows parity: Five-page onboarding needs paired visual and input qualification #779.

Navigation Menu

Repository navigation

Windows first-run onboarding: current five-page physical-input qualification remains #556

Current reconciliation - 2026-11-09

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Windows first-run onboarding: current five-page physical-input qualification remains #556

Description

Current reconciliation - 2026-11-09

Activity

coneilen commented on Oct 1, 2026

coneilen commented on Oct 2, 2026

coneilen commented on Oct 2, 2026

coneilen commented on Oct 13, 2026

coneilen commented on Oct 14, 2026

coneilen commented on Oct 14, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions