Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,45 @@ Every user-visible change, newest first. Pre-1.0 the minor number carries new su
carries fixes. The section for a tag is what the GitHub release publishes, so the two cannot say
different things.

## [Unreleased]

### Added

- **`dotnet cui session --script <file>`** names the command file instead of relying on `<` input
redirection, which Windows PowerShell does not have. Stdin still works in a POSIX shell.
- **`dotnet cui doctor`** checks this 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
`--aot` performs the Release publish of an app that enables `PublishAot` and reports its
IL2xxx/IL3xxx warnings.
- **`png --size` / `--sizes`, `--env` / `--state` and strict `find` / `click`** from the earlier
headless workflow pass: one viewport or a png matrix, an isolated app state root, extra
environment, and a refusal to guess between equally good matches. `CUISHARP_VIEWPORT` makes a
headless frame the requested size; `ui.MarkReady()` and `--wait ready` replace frame counting for
async data.
- **Semantic roles, values, state and automation ids.** Every recorded node now exposes `Role`,
`Name`, `Value`, `SemanticState` and `AutomationId`; `ui.Id` and `ui.Automation` name a control
independently of its label, and `SemanticNode.ToAccessibility()` is the projection a platform
accessibility adapter will consume. `dotnet cui tree --details` prints the metadata, and
`find`/`click` accept `--role`, `--value` and `--id` as well as the existing query text.

### Changed

- **`HttpMethod` is now `HttpVerb`.** The old name collided with `System.Net.Http.HttpMethod` in
every app that also made an HTTP request. `RequestBar` and `CuiHttp.MethodName` take `HttpVerb`;
the generated C binding is unchanged.
- **`Color.WithAlpha` on a theme token returns the token unchanged.** A token has no channels to fade
until a frame resolves it, so the old call silently did nothing useful; the guide now shows
`ui.TokenColor(Token.Accent).WithAlpha(0.14f)` for a translucent tint. `Color.IsToken` now checks
the whole token marker, including alpha, so a raw color that happens to share G/B is not a token.
- **The samples and headless workflow are platform-neutral.** `stock.cs` uses `SocketsHttpHandler`,
`download.cs` reveals with `explorer`, `open -R` or `xdg-open`, and the generated binaries are
named for the host. `music.cs` remains Windows-only because its player is WinRT `MediaPlayer`.
- **`Size` can be inspected**: `IsFit`, `IsFill`, `IsFixed`, `IsPercent`, `TryGetPoints` and
`TryGetPercent`, with a readable `ToString`. The guide also spells out when to use `Card` instead
of `Box`, and warns that the OS file dialog (`CuiWindow.PickFile`) is modal and must not run from a
component's `Draw`; `ui.FilePicker` is the in-frame picker.

## [0.4.2] — 2026-11-13

### Added
Expand Down
20 changes: 14 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ dotnet publish demo1.cs -c Release -o . # one native binary beside it, no .NE
folder; replace the .ico with your own to change the exe and window icon. Add `-o <folder>`
only when you want a separate output directory. The generated file carries the properties that make
that publish one file of about 1.2 MB, and says so at the top. It starts with
`#:package CuiSharp@*`, resolving the latest stable package; use `--CuiSharpVersion 0.3.3` when
`#:package CuiSharp@*`, resolving the latest stable package; use `--CuiSharpVersion <version>` when
generating to pin a version. Its counter and theme switch use the same frame API as a full app;
`CUISHARP_HEADLESS=1` runs it without a window for automation.

Expand Down Expand Up @@ -181,9 +181,9 @@ Then this is the whole of what a project's `AGENTS.md` has to say about CuiSharp
> project, not in a shell history.

`dotnet cui docs` answers from the guide, the reference and the behaviour pages **inside the tool**:
no repository, no NuGet cache, no network, nothing built and nothing started. Fourteen topics cover
no repository, no NuGet cache, no network, nothing built and nothing started. Fifteen topics cover
the tasks an assistant arrives with — `getting-started`, `writing-ui`, `custom-controls`, `hosting`,
`testing`, `debugging`, `layout`, `live-debugging`, `performance`, `theming`, `translation`,
`testing`, `debugging`, `layout`, `live-debugging`, `headless`, `performance`, `theming`, `translation`,
`publishing`, `signatures`, `widgets` — and each one is a named set of sections of the shipped pages,
so the tool cannot say anything the documentation does not.

Expand Down Expand Up @@ -220,13 +220,20 @@ Assert.True(app.PaintedAnything());

```sh
dotnet cui tree # the controls of the last frame, nested
dotnet cui tree --details # …with role, automation id, value and state
dotnet cui find --role button Save # find by semantic role and label
dotnet cui find --value Milk # find by the value a field holds
dotnet cui click Save # click a control, print the frame it produced
dotnet cui click "Button Save" # …when a heading says the same word
dotnet cui click "editor > Save" # …or the path to the control
dotnet cui type Milk # type into the focused field
dotnet cui png shot.png # the frame as a PNG, for a person or a model
dotnet cui png shot.png --size 420x720 # a viewport without editing the app
dotnet cui png shot.png --sizes 420x720,1180x820 # one png per viewport
dotnet cui tree --state artifacts/cui-run # isolated app state
dotnet cui tree -a 15036 # the same, on a live window a person is watching
dotnet cui session < script.txt # many commands, one build, one app
dotnet cui session --script script.txt # many commands, one build, one app
dotnet cui doctor # check the tool against the app before a bug report
```

The query is **one quoted argument** — `click "Button Save"`, not `click Button Save` — because the
Expand Down Expand Up @@ -272,7 +279,7 @@ dotnet tool install -g CuiSharp.Tools # exposes `dotnet cui`
```

```sh
dotnet publish -c Release -r win-x64 # one executable, from ~1.2 MB up, nothing beside it
dotnet publish -c Release -r win-x64 # or linux-x64 / osx-arm64; one executable, nothing beside it
```

`cui.lib` is linked statically through the package's targets, so there is no `cui.dll` in the output.
Expand Down Expand Up @@ -300,7 +307,8 @@ The browser-hosted gallery and GitHub Pages build are documented in
[`samples/CuiSharp.Gallery.Browser/README.md`](samples/CuiSharp.Gallery.Browser/README.md).

The four file-based apps in [`samples/`](samples/README.md) — Disk Usage, Global Market Cap, Music
and Downloads — are one `.cs` file each, with the same run / publish / headless header.
and Downloads — are one `.cs` file each, with the same run / publish / headless header. Music is
Windows-only because it uses the WinRT `MediaPlayer`; the other three publish for the current platform.

```
src/CuiSharp/ the library: Interop (generated), Ui, Runtime, Semantics, Hosting, Charting
Expand Down
2 changes: 1 addition & 1 deletion bindings/api.json
Original file line number Diff line number Diff line change
Expand Up @@ -27261,7 +27261,7 @@
},
{
"CName": "cui_http_method",
"CsName": "HttpMethod",
"CsName": "HttpVerb",
"Values": [
{
"CName": "CUI_HTTP_GET",
Expand Down
7 changes: 4 additions & 3 deletions bindings/overrides.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
"cui_renderer_kind": "Renderer",
"cui_sw_format": "SwFormat",
"cui_token": "Token",
"cui_task_status": "CuiTaskStatus"
"cui_task_status": "CuiTaskStatus",
"cui_http_method": "HttpVerb"
},
"memberRenames": {
"CUI_RENDERER_OPENGL": "OpenGL"
Expand Down Expand Up @@ -233,8 +234,8 @@
},
"cui_request_bar_ex.method": {
"storage": "enum",
"type": "HttpMethod",
"why": "CUI takes an int* the method menu writes: the wrapper keeps the caller's HttpMethod and hands over the int behind it."
"type": "HttpVerb",
"why": "CUI takes an int* the method menu writes: the wrapper keeps the caller's HttpVerb and hands over the int behind it. HttpVerb, not HttpMethod, so it cannot be confused with System.Net.Http.HttpMethod."
}
},
"capacityParams": {
Expand Down
117 changes: 106 additions & 11 deletions docs/API-SURFACE.txt
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,8 @@ class CuiSharp.AppChromeMenuBarToolbarStatusBarDocumentTabsUiExtensions+<G>$2E78
Void ToolbarSeparator()
Void ToolbarSpacer()
class CuiSharp.AppChromeMenuBarToolbarStatusBarDocumentTabsUiExtensions+<G>$2E78AC6C4589E2D26F56ACB2C0F932B4+<M>$D152016828D0F2CB0A8B78500F4F70D3
struct CuiSharp.AutomationScope
Void Dispose()
struct CuiSharp.AvatarOpts
field Boolean Square
field Single Size
Expand Down Expand Up @@ -651,7 +653,7 @@ class CuiSharp.CuiFiles
static Void SortTraceSpans(Span<TraceSpan>)
class CuiSharp.CuiHttp
static KeyValue[] ParseQuery(String, Int32)
static String MethodName(HttpMethod)
static String MethodName(HttpVerb)
static String Reason(Int32)
static String SetQuery(String, ReadOnlySpan<KeyValue>, Int32)
class CuiSharp.CuiMath
Expand Down Expand Up @@ -1534,7 +1536,7 @@ class CuiSharp.Hosting.HeadlessApp
HeadlessApp ScrollAt(Single, Single, Single, Single)
HeadlessApp Type(String)
Int32 Settle(Int32, Nullable<TimeSpan>)
String Print(Boolean)
String Print(Boolean, Boolean)
String PrintLayout()
String SavePng(String, Boolean)
String ToString()
Expand All @@ -1547,6 +1549,7 @@ class CuiSharp.Hosting.HeadlessApp
WidgetTarget FindById(String)
WidgetTarget FindInput(String)
WidgetTarget FindItem(String, Int32)
WidgetTarget FindUnique(String)
property Boolean Animating { get; }
property Boolean Ready { get; }
property Component Root { get; }
Expand All @@ -1566,6 +1569,7 @@ struct CuiSharp.Hosting.HeadlessApp+WaitOutcome
property TimeSpan Elapsed { get; }
class CuiSharp.Hosting.HeadlessLoop
field String EnvironmentVariable
field String ViewportEnvironmentVariable
property IReadOnlyList<String> Known { get; }
static Boolean Requested(String[])
static Int32 Run(DrawFn, CuiAppOptions, TextReader, TextWriter)
Expand All @@ -1591,27 +1595,31 @@ struct CuiSharp.Hosting.WidgetTarget
WidgetTarget Click()
WidgetTarget Hover()
property RectF Rect { get; }
property SemanticRole Role { get; }
property SemanticState State { get; }
property String AutomationId { get; }
property String Kind { get; }
property String Text { get; }
property String Value { get; }
struct CuiSharp.HoverCardOpts
field Placement Placement
field Single Delay
field Single Width
enum CuiSharp.HttpMethod
class CuiSharp.HttpRequestBarUiExtensions
static RequestBarResult RequestBar(Ui, UiText, ref HttpVerb, ref String, Int32, RequestBarOpts)
static Void ResponseStatus(Ui, Int32, Double, Double)
class CuiSharp.HttpRequestBarUiExtensions+<G>$2E78AC6C4589E2D26F56ACB2C0F932B4
RequestBarResult RequestBar(UiText, ref HttpVerb, ref String, Int32, RequestBarOpts)
Void ResponseStatus(Int32, Double, Double)
class CuiSharp.HttpRequestBarUiExtensions+<G>$2E78AC6C4589E2D26F56ACB2C0F932B4+<M>$D152016828D0F2CB0A8B78500F4F70D3
enum CuiSharp.HttpVerb
Delete
Get
Head
Options
Patch
Post
Put
class CuiSharp.HttpRequestBarUiExtensions
static RequestBarResult RequestBar(Ui, UiText, ref HttpMethod, ref String, Int32, RequestBarOpts)
static Void ResponseStatus(Ui, Int32, Double, Double)
class CuiSharp.HttpRequestBarUiExtensions+<G>$2E78AC6C4589E2D26F56ACB2C0F932B4
RequestBarResult RequestBar(UiText, ref HttpMethod, ref String, Int32, RequestBarOpts)
Void ResponseStatus(Int32, Double, Double)
class CuiSharp.HttpRequestBarUiExtensions+<G>$2E78AC6C4589E2D26F56ACB2C0F932B4+<M>$D152016828D0F2CB0A8B78500F4F70D3
interface CuiSharp.IFileDialogProvider
FilePickResult Pick(CuiWindow, FileDialogOpts)
class CuiSharp.Icons
Expand Down Expand Up @@ -5458,23 +5466,93 @@ class CuiSharp.SelectionControlsUiExtensions+<G>$2E78AC6C4589E2D26F56ACB2C0F932B
Boolean Slider(UiText, ref Single, Single, Single, SliderOpts)
Boolean Switch(UiText, ref Boolean, CheckOpts)
class CuiSharp.SelectionControlsUiExtensions+<G>$2E78AC6C4589E2D26F56ACB2C0F932B4+<M>$D152016828D0F2CB0A8B78500F4F70D3
class CuiSharp.SemanticAccessibilityNode
Boolean Equals(Object)
Boolean Equals(SemanticAccessibilityNode)
Int32 GetHashCode()
SemanticAccessibilityNode <Clone>$()
String ToString()
Void Deconstruct(out SemanticRole, out String, out String, out SemanticState, out String, out RectF, out IReadOnlyList<SemanticAccessibilityNode>)
ctor(SemanticRole, String, String, SemanticState, String, RectF, IReadOnlyList<SemanticAccessibilityNode>)
property IReadOnlyList<SemanticAccessibilityNode> Children { get; set; }
property RectF Bounds { get; set; }
property SemanticRole Role { get; set; }
property SemanticState State { get; set; }
property String AutomationId { get; set; }
property String Name { get; set; }
property String Value { get; set; }
class CuiSharp.SemanticNode
Boolean TryFind(String, out SemanticNode)
IEnumerable<SemanticNode> Descendants()
SemanticAccessibilityNode ToAccessibility()
SemanticNode Find(String)
String Print(Boolean)
String Describe()
String Print(Boolean, Boolean)
String ToString()
property Boolean Detached { get; }
property Boolean HasOwnRect { get; }
property Boolean IsContainer { get; set; }
property Boolean IsEnabled { get; }
property Boolean IsFocused { get; }
property IReadOnlyList<SemanticNode> Children { get; }
property Int32 Depth { get; }
property RectF Rect { get; }
property SemanticNode Parent { get; }
property SemanticRole Role { get; }
property SemanticState State { get; }
property String AutomationId { get; }
property String Kind { get; }
property String Name { get; }
property String Path { get; }
property String Text { get; }
property String Value { get; }
property UInt32 Id { get; }
enum CuiSharp.SemanticRole
Button
CheckBox
ComboBox
Container
Dialog
Frame
Heading
Image
Link
List
ListItem
Menu
MenuItem
None
Other
ProgressBar
RadioButton
Separator
Slider
SpinButton
Switch
Tab
TabList
Table
TableCell
TableRow
Text
TextBox
Tooltip
Tree
TreeItem
class CuiSharp.SemanticRoles
static Boolean TryParse(String, out SemanticRole)
static SemanticRole Of(String)
static String Name(SemanticRole)
enum CuiSharp.SemanticState
Checked
Enabled
Expanded
Focused
None
ReadOnly
Selected
class CuiSharp.SemanticStates
static String Format(SemanticState)
struct CuiSharp.SemanticWidget
Boolean Contains(Single, Single)
String ToString()
Expand All @@ -5483,8 +5561,11 @@ struct CuiSharp.SemanticWidget
field Boolean IsContainer
field Int32 Depth
field RectF Rect
field SemanticState State
field String AutomationId
field String Kind
field String Text
field String Value
field UInt32 Id
property ValueTuple<Single, Single> Center { get; }
struct CuiSharp.Series
Expand Down Expand Up @@ -5527,8 +5608,15 @@ struct CuiSharp.SignatureOpts
field Size Width
field String Placeholder
struct CuiSharp.Size
Boolean TryGetPercent(out Single)
Boolean TryGetPoints(out Single)
String ToString()
field Size Fill
field Size Fit
property Boolean IsFill { get; }
property Boolean IsFit { get; }
property Boolean IsFixed { get; }
property Boolean IsPercent { get; }
static Size Grow(Single)
static Size Percent(Single)
static Size Px(Single)
Expand Down Expand Up @@ -6104,6 +6192,7 @@ struct CuiSharp.TreemapOpts
field Size Width
field String Format
struct CuiSharp.Ui
AutomationScope Automation(UiText)
Boolean DateToday(out Date)
Boolean FilterBar(UiText, ReadOnlySpan<FilterField>, Span<UInt32>, ref String, Int32)
Boolean KeyDown(Key)
Expand Down Expand Up @@ -6285,10 +6374,16 @@ struct CuiSharp.WheelOpts
field Size Width
struct CuiSharp.WidgetQuery
String ToString()
property Nullable<SemanticRole> Role { get; }
property String Kind { get; }
property String Text { get; }
property String Value { get; }
property String[] Path { get; }
static WidgetQuery Parse(String)
class CuiSharp.WidgetRecorder
property Boolean Enabled { get; }
static Void Note(IntPtr, String, UiText)
static Void Note(IntPtr, String, UiText, SemanticState)
static Void NoteValue(IntPtr, String, UiText, Boolean, SemanticState)
static Void NoteValue(IntPtr, String, UiText, Double, SemanticState)
static Void NoteValue(IntPtr, String, UiText, String, SemanticState)
13 changes: 10 additions & 3 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -277,8 +277,15 @@ makes a frame allocate. The snapshot itself is data that outlives the frame, so
outside the window `FrameStats` measures.

`SemanticNode` rebuilds that nesting; `WidgetQuery` is the vocabulary a search uses (a label, a
kind and a label, or a path) and it ranks: exact before prefix before substring, and an actionable
control before static text at the same tier.
kind and a label, a role, a value, or a path) and it ranks: exact before prefix before substring,
and an actionable control before static text at the same tier. A node also carries the
`SemanticRole`, an optional `Value`, `SemanticState` flags and an optional `AutomationId`: a
`ui.Id` scope supplies the native identity and the automation id together, while `ui.Automation`
supplies only the latter. `SemanticNode.ToAccessibility()` is the projection a UIA, AT-SPI or
NSAccessibility adapter consumes; the platform layers themselves stay ahead, not implied by the
recording layer. Values are captured as the wrapper already has them (a text field's string, a
slider's number, a toggle's bool) and formatted after the frame, so recording still adds 0 B to the
draw.

## Tests

Expand Down Expand Up @@ -314,7 +321,7 @@ wants them: everything after a standalone `--` is handed to the app untouched, a
even when it begins with a dash (`--wait-text -loading`), and a query is one quoted argument
(`click "Button Save type"`), because the app parses the query grammar and this tool does not.

A session is a command (`dotnet cui session < commands.txt`), not a flag. As a flag it could be
A session is a command (`dotnet cui session --script commands.txt`), not a flag. As a flag it could be
written beside a verb, and the verb would then be silently dropped; as a command the line says
which of the two things is happening.

Expand Down
Loading
Loading