Skip to content

Developer experience: semantic tree, headless workflow and dotnet cui doctor - #22

Merged
albertwoo merged 5 commits into
mainfrom
feature/developer-experience
Nov 16, 2026
Merged

albertwoo merged 5 commits into
mainfrom
feature/developer-experience

Conversation

@albertwoo

Copy link
Copy Markdown
Contributor

Brings the developer-experience work landed across five commits onto main. The theme is a driver that can see and trust what an app renders: the semantic tree now carries roles, values, state and automation ids, the headless workflow can name a viewport, isolate app state and refuse ambiguous matches, and dotnet cui doctor reports the setup problems that would otherwise surface as a confusing failure.

Highlights

Semantic tree

  • Every recorded node exposes Role, Name, Value, SemanticState and AutomationId.
  • ui.Id and ui.Automation name a control independently of its label; SemanticNode.ToAccessibility() is the projection an accessibility adapter will consume.
  • tree --details prints the metadata, and find/click accept --role, --value and --id.
  • id: ranks a real automation id above a text fallback and an actionable control above its own container or a static label in the same scope; a genuine tie is refused instead of guessed.
  • A path step (a > b) matches containers only, and the leaf keeps its role and value, so role:button card > Delete resolves.
  • ui.Input/TextArea/Search record ReadOnly; TagInput, OtpInput and FilterBar record their value.

Headless workflow

  • png --size names one viewport and --sizes builds a matrix, with the project built once per matrix.
  • --env adds environment, --state points at an isolated app-state root, and CUISHARP_VIEWPORT makes a headless frame the requested size (range-checked, applied inside HeadlessLoop).
  • A blank find/click query is a usage error, an env key must start with a letter or _, and --state wins over --env.
  • ui.MarkReady() with --wait ready replaces frame counting for async data.

dotnet cui doctor

  • Checks the tool's version and API catalog against the CuiSharp version the app resolved, reports a floating #:package CuiSharp@*, a missing ApplicationIcon, and whether NativeAOT is configured.
  • --json is machine-readable, --strict fails on warnings, and --strict --json honestly reports "ok": false.
  • --aot performs the Release publish of an app with PublishAot and reports its IL2xxx/IL3xxx warnings.

Hardening

  • FindCuiWindow passes its result through lparam instead of a shared static that clobbered a parallel window's handle.
  • The message-window class is registered once under the static gate, and the resize hook's table is concurrent.
  • Live find/click use the same strict disambiguation as the headless loop.
  • Window tests that touch process-wide state share the ProcessWindowState collection.
  • Closing an AutomationScope is reported as a scope leak; ui.Automation is no longer treated as a row id by the analyzer.

Renames and behaviour changes

  • HttpMethod is now HttpVerb, since the old name collided with System.Net.Http.HttpMethod.
  • Color.WithAlpha on a theme token returns the token unchanged; use ui.TokenColor(...).WithAlpha(...) for a translucent tint. Color.IsToken now checks the whole token marker.
  • The samples and headless workflow are platform-neutral; music.cs stays Windows-only because of WinRT MediaPlayer.
  • Size gained IsFit, IsFill, IsFixed, IsPercent, TryGetPoints, TryGetPercent and a readable ToString.

Docs

CHANGELOG.md, README.md, samples/README.md, docs/ARCHITECTURE.md, docs/API-SURFACE.txt, skills/cui-dotnet/SKILL.md, llms.txt and the generated API docs all moved with the code, and the template's README.md/AGENTS.md describe the same workflow.

Verification

  • dotnet build CuiSharp.slnx -c Release -warnaserror
  • dotnet test CuiSharp.slnx -c Release — 1039 + 37 tests
  • dotnet format CuiSharp.slnx --verify-no-changes
  • pwsh tools/regen.ps1 -NoNative -NoDiff — generated output is fresh
  • pwsh tools/verify-template.ps1 — dotnet new → build → test → AOT → dotnet cui, end to end

- add --size and a png-only --sizes matrix to dotnet cui
- add --env and --state, with CUISHARP_VIEWPORT and CUISHARP_STATE_HOME in the app
- make find and click refuse equally ranked controls; record icon-button tooltips
- document MarkReady/--wait, viewport, state and strict matching
- move the samples' state under CUISHARP_STATE_HOME
- regenerate the bindings, API catalog and public-surface baseline
- remove Windows-only gates from the new headless tests
- reveal downloads with explorer, open -R or xdg-open
- replace stock's WinHttpHandler with SocketsHttpHandler
- document platform-neutral app and publish paths
- keep music Windows-only for WinRT MediaPlayer
- add session --script for shells without input redirection
- add doctor: tool/app versions, package pinning, icon and AOT checks
- rename the generated HttpMethod enum to HttpVerb
- document token alpha, Size introspection, Card vs Box and FilePicker
- keep every new path cross-platform and regenerate the bindings/docs
- record role, name, value, state and automation id on every node
- add ui.Automation and make ui.Id/Keyed supply stable automation ids
- capture text, numeric and toggle values in generated wrappers without frame allocations
- add tree --details and find/click --role, --value and --id
- project the tree with SemanticNode.ToAccessibility for future platform adapters
Fix the defects found while reviewing the developer-experience branch, and
bring the docs back in step with the code.

Semantics and recording:
- A path query keeps its role and value at the leaf, and a path step only
  matches a container, so `role:button card > Delete` resolves.
- `id:` ranks an explicit automation id above a text fallback and an
  actionable control above its container or a static label in the same
  scope, and `FindUnique` refuses two controls that rank equally there.
- `ui.Input`/`TextArea`/`Search` record ReadOnly; `TagInput`, `OtpInput`
  and `FilterBar` record their value; `Describe` escapes newlines so
  `tree --details` stays one line per node.
- Closing an `AutomationScope` is a scope leak the analyzer reports, and
  `ui.Automation` is not treated as a row id.
- Role and static-widget tables cover the remaining wrappers.

Live attach and the window thread:
- The message-window class is registered once under the static gate, and
  the resize hook's table is concurrent, so two windows cannot race.
- `FindCuiWindow` hands its result through lparam instead of a shared
  static, which clobbered a parallel window's handle.
- Live `find`/`click` use the same strict disambiguation as the headless
  loop.
- Window tests that touch process-wide state share one collection.

Headless workflow and tool:
- `CUISHARP_VIEWPORT` is range-checked and applied inside the loop, and
  `--size` and `--sizes` stay distinct so one viewport still names the
  file after it; a matrix builds the project once.
- A blank find/click query is a usage error, an env key starts with a
  letter or `_`, and `--state` wins over `--env`.
- `doctor --strict --json` reports ok:false when a warning fails the run.
- An allocation test takes the median of five batches.

Docs:
- llms.txt, SKILL.md's contents, the docs index and live-debugging topic,
  the template README/AGENTS.md, and the README version example match the
  current API and grammar.
@albertwoo
albertwoo merged commit 5fbab51 into main Nov 16, 2026
24 checks passed
@albertwoo
albertwoo deleted the feature/developer-experience branch November 16, 2026 00:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant