ARCADIA-Studio/harness/release-native-ux-audit.md

First-release native UX audit — 2026-09-05

Independent, bounded review of the existing V2 executable against the new first-release objective. No application source or existing model was modified by this review. Computer Use used the supported @oai/sky native API; screenshots were captured and visually inspected after each meaningful action.

Environment and scope

• Windows packaged executable: dist/ArcadiaStudio-Windows/arcadia-studio.exe, SHA-256 e2aec2ac935e270c6185729cbb76f8323b381654c04dbde7aae90c4628a98a20.
• Actual application window 2560154. Startup client 1440×900; compact client 1100×700, changed through the native system-menu Size operation.
• Exercised startup demo, guide, New, first architecture view, entity creation/properties, allocated activity creation, minimum layout/Fit, model search, invalid-property rejection/Revert, native save/open and normal close.
• Disposable UI-authored fixture: D:/CodexBuilds/Capella2-v2-01a06e2e/final-ui-review/release-native-audit-new-project.arcadia.
• Original Capella window 3673208 was left untouched. The review app was closed using Alt+F4; a subsequent process query found no arcadia-studio process. Native session ownership is released.
• This pass did not launch the server or re-exercise all OA/SA semantics. It is additional first-release UX evidence, not a replacement for the V2 verification reports.

Findings requiring first-release action

R1 — Built-in help does not yet satisfy the new navigable tutorial requirement

Priority: P1 requirement gap. Clicked Engineering guide and read both its initial viewport and remaining content. It contains seven static cards plus Open coastal rescue example. The concepts are accurate and concise, but there is no table of contents, topic navigation, help search, practical sequence of controls for common modeling tasks, contextual topic access or shortcut/reference section. The sidebar Search is model-element search and does not search help. views.rs::guide confirms the seven-card implementation.

A first-time engineer is told to allocate activities, connect exchanges and review transitions without being shown the actual sequence of controls or the distinction between semantic ownership and a diagram placement. The new objective explicitly requests easy navigation/exploration and clear information on common modeling scenarios and application use.

Feasible fix: a small built-in article/topic browser with search and related topics, a first-project walkthrough, OA/SA boundary and allocation explanations, transition review tutorial, scenarios/states/data/interfaces, traceability, text/lint/recovery, files/shortcuts and API integration. Keep it native and available offline; reuse concise content instead of adding a general documentation framework. Add contextual links where the user already encounters these operations.

R2 — Open/New/Demo forget the actual window size; Fit becomes wrong

Priority: P2 reproducible functional defect. At the minimum size, an authored entity with one allocated activity fits correctly at 95%. Saved the model through the native Save As dialog, then Ctrl+O reopened that exact file. The app immediately displayed 150%, with the nested activity and parent clipped under the right inspector and below the canvas. Clicked Fit and took an additional fresh screenshot: it remained 150% and clipped. Thus Fit itself no longer repairs the view until another physical resize event updates app state.

The fixture has two elements, one Allocation and two diagram nodes. File bytes confirm those records; no malformed geometry is involved. app.rs::reset replaces the complete application with Self::with_project(project), whose window_size is the launch default 1440×900. fit() uses that field. The native window remains 1100×700 and does not need to emit another resize when a file opens.

Fix: preserve the current native window_size across project replacement, then fit. Apply this to every reset caller (New/Open/Demo). Add a regression that sends WindowResized, resets/loads a model, then checks Fit uses that preserved viewport. Reverify saved fixture opening at minimum and default sizes.

R3 — At minimum size, search results are initially entirely below the visible sidebar

Priority: P2 usability. At 1100×700, the eight navigation rows and creation controls place Search at the very bottom. Typing rescue produces no visible result. Scrolling the entire sidebar then reveals Rescue coordinator, while the perspective switch and upper navigation disappear. This is functioning search, but a frequent navigation action gives no visible feedback until the user discovers the outer scroll. views.rs puts navigation, creation, search and all results into one scrollable column.

Feasible fix: reserve useful visible height for search results and provide a compact navigation treatment at short window heights, or separate the explorer from navigation. Also give an explicit no-results state. Preserve usable hit targets and verify both supported sizes. This matters more as the new release grows its modeling and help features.

Observed strengths and recovery behavior

1. Startup is reliable and visually intentional: the rich demo opens with 39 objects, 23 links and zero checks; nesting is understandable.
2. New gives a useful empty-state instruction and Create architecture view button. Creating the view immediately produces an editable OA view.
3. Entity → At root creates and selects a visible node. Renaming it Rescue coordinator and Apply changes updates the diagram. Choosing Activity while that participant is selected changes the second create action to Allocated; clicking it creates an Allocation and visibly nests the activity. This is a clear, efficient interaction worth preserving.
4. At the minimum size before reopening, Fit renders the authored nested pair fully. The toolbar and inspector remain reachable with appropriate panel scrolling. There was no general overlap of controls.
5. Entered bad alias in Stable source alias. Apply rejected it without changing the accepted node (invalid_alias: Invalid or reserved alias 'bad alias'.). Revert restored new_activity. This recovery works. The feedback is currently only a small footer line; field-local guidance and valid alias examples would help but are lower priority than R1–R3.
6. Native Save As accepted the disposable absolute path, reported All changes saved/Project saved and produced canonical text containing the expected two elements, allocation and placements. Ctrl+O reopened the exact file with two objects/one link/zero checks; semantics were preserved despite R2's viewport regression.

Review disposition

First-release UX completion is not yet proven. R1 is an explicit new requirement gap; R2 is a verified existing defect; R3 is a practical compact-layout navigation problem. No crash, accepted-model corruption or destructive recovery was observed in this bounded pass. Root was notified of R1 and R2 immediately; this report completes the independent audit and provides concrete next verification steps.