FluidSimCpp/docs/WORKSHOP_UI_PLAN.md

# Workshop UI rework

Design specification, updated 2026-11-01. Implementation status is listed below.
Physical parts, typed signals and ECU requirements are defined in the
[machine systems roadmap](MECHANICAL_BUILDER_PLAN.md).

## Implementation status

The first UI pass implements the dark theme, shared adaptive panel geometry,
resizing/collapse with saved preferences, library search/categories and previews,
an Objects list, a measured inspector with stacked property fields, fitted control
labels and hover disclosure, direct click/drag connections, persistent Run/Pause/
Step controls, navigable checks, and a separate resizable oscilloscope dock.
Existing ECU assignment ports use input rings and filled output circles; gas
ports retain their physical semantics. The Sense inspector now adds physical
sensor taps, unresolved binding repair and per-sample live outputs, using green
Number and red Boolean output dots. Sensor attachments remain locked during Test.

The builder and desktop UI regressions pass. Rendered review covers empty, ECU,
Checks, Meters, running/paused and collapsed layouts at 1920x1080 and 1280x720.

Logic/split views now share the running machine, with a searchable node library,
typed click/drag wiring, reference selection, live values/controls, parameter
inspectors and compact number trends. Input rings/output circles and red Boolean/
green Number colors are checked in rendered output. Thirteen focused suites pass;
graph and split layouts are reviewed at 1920x1080 and 1280x720.

Grouped ECU connectors follow their runtime systems. Automatic DPI/UI scale
overrides, an object hierarchy with
visibility groups, richer property grouping/help and pinned operator controls
remain follow-up UI work. Their design below remains the intended direction.

## Confirmed direction

- Dark engineering editor with compact toolbars, clear panels and restrained
  colors. Reserve strong colors for signal types, selection and relevant state.
- Separate **3D** and **Logic** tabs, with an optional split view. Selection and
  running simulation are shared across views; camera and canvas navigation state
  remain independent. Switching views does not restart Test.
- Connect by dragging between ports or clicking a port then its target. A
  dedicated Connect mode is not required. Escape cancels a pending connection.
- Signal inputs are hollow rings; outputs are filled circles. Boolean is red,
  Number green. Bidirectional physical ports use neutral domain symbols.
- Panels remain in predictable positions, resize and collapse, and remember
  their widths. Provide a reset-layout action and constrain restored sizes to
  the current window so the central workspace stays usable.
- The library uses compact rows with small previews, categories and search.
  Selecting an item shows a larger preview with its purpose and essential ports.
- Starting Test preserves the current workspace, selection and navigation state.
  Lock structural edits while allowing safe live tuning and logic inspection.
- Test starts running. Pause and Step remain visible; Step is enabled when
  paused, with a tooltip explaining that state when disabled.
- Primary design target is a 1920x1080 desktop window. The first priority is
  consistent appearance and layout, especially preventing text/control overlap.
- Remaining routine design decisions are made autonomously, per user direction.

## Layout and visual baseline

Use a shared layout/component layer rather than individually positioned controls.
Rendering and hit testing consume the same computed rectangles. Define shared
theme values for spacing, typography, surfaces, borders and interaction states.

Initial dimensions below are logical pixels at 100% UI scale, and may be tuned
through visual review while preserving the agreed structure.

| Element | Default |
| --- | --- |
| Spacing | 4 px base unit; 8 px control gaps; 12 px panel padding; 16 px section gaps |
| Typography | 14 px body/fields, 12 px secondary labels, 16 px section titles; measured line height |
| Controls | 30 px minimum row height, increased when text or UI scale requires it |
| Top command bar | 44 px, with less-used file actions in a menu |
| Workspace toolbar | 36 px; 3D/Logic tabs and split toggle stay discoverable |
| Left panel | 260 px default; resizable between 220 and 420 px |
| Inspector | 340 px default; resizable between 280 and 520 px |
| Bottom area | Collapsed initially; 240 px default when opened, vertically resizable |
| Status bar | 24 px minimum; longer messages go to Checks or a tooltip |
| UI scale | Auto from display scaling, plus 100%, 125%, 150% and 200% overrides |

Use a neutral charcoal palette with clear panel boundaries and one restrained
selection accent. Reuse the same fields, buttons, tabs, badges and menus across
all views. Strong red/green remains reserved for the agreed signal types; add
icons/text to distinguish faults and success from those types.

Support a 1280x720 window at 100% scale through a compact layout. As available
logical space shrinks, move secondary toolbar actions into an overflow menu,
collapse the library/object panel, and offer the inspector as a temporary panel.
Preserve access to required actions and readable text instead of shrinking fonts.
If split view cannot fit two usable canvases, use a single tab and explain why
split is unavailable. Large UI scaling follows the same compact behavior.

Choose a vertical split by default: 3D left, Logic right, with a draggable divider
and a swap action. Remember divider position, panel widths/collapse states and
active view in user preferences; clamp them on restore. Store machine-specific
camera/canvas layout separately from physical geometry and signal values.

### Text and overlap rules

- Measure text before layout. Use content-sized rows and explicit minimum sizes;
  never assume every property label fits a fixed width.
- Inspector rows place label, value, unit and optional action in separate layout
  cells. Narrow inspectors stack labels above fields; units never cover digits.
- Wrap help and diagnostic text and grow the row. Ellipsize long names only in
  compact lists/tabs, with the complete name available on hover and in selection.
- Clip rendering and pointer handling to the same panel scroll region. Fixed
  headers and footers reserve their own space so scrolling content cannot cover
  buttons, tabs or trace controls.
- Tooltips and menus reposition within the window and respect their anchor.
  Keep the focused text field visible when scrolling or opening a panel.
- Lay out ECU ports from descriptor rows with adequate label/value space; nodes
  grow vertically as ports expand. Wires route away from pin labels before bends.
- World labels use screen-space placement with collision suppression; prioritize
  selected/hovered labels and expose the rest on demand. Hidden labels must not
  hide the underlying port's tooltip or named connection-list access.

## Workspace structure

Proposed layout: a slim document/command bar, workspace tabs, a left library/object
panel, central workspace, right inspector, and optional bottom diagnostics/traces.
Use resize handles and collapse controls within this predictable layout.

- Top bar: machine name, unsaved status, file actions, undo/redo and simulation
  controls. Show current run state unambiguously even in Logic view.
- 3D toolbar: Select, Move, Rotate, Route, snapping and fit/focus. Connection
  gestures work directly on visible ports and do not start a transform drag.
- Logic toolbar: node search/add, frame selection/all, connection filters and
  live-value visibility. Node creation targets the canvas under the pointer.
- Library: parts, sensors, logic nodes and saved assemblies with search and
  categories, displayed as compact rows with small previews. Show a larger
  selected-item preview and compatibility when adding from a signal port.
- Objects: named parts, sensors, shafts, ECUs and assemblies. Search, select,
  focus, rename and hide without removing simulation membership.
- Inspector: selection identity, grouped properties, connections and contextual
  help. Show units next to editable values and explain locked Build properties.
- Bottom area: navigable checks, traces and event history. Selecting an issue
  locates the relevant part, port or connection in the appropriate view.
- Status bar: current gesture, keyboard hints and short feedback. Important
  failures remain in Checks rather than disappearing with a transient message.

## Core workflows

### Place and configure

Search for a part, select it, preview placement, then click to place. Shift repeats
placement. Escape cancels. Placed parts immediately expose a name and the small
set of essential properties; advanced groups expand on demand. Preserve current
copy/paste, assembly and undo workflows as the UI changes.

For multiple selections show selection count, pivot and mixed values. Edits apply
only to compatible properties; do not display one arbitrary part's value as a
shared value. Selection/focus is synchronized with the object tree and Logic view.

### Connect

Hover highlights a port with name, domain, direction, units and connection state.
Dragging from it or clicking it begins a preview. Compatible targets stand out;
incompatible targets explain the reason. A separate checkmark/cross communicates
validity without overwriting the red/green signal colors.

Keep ring centers easy to pick and port target size readable at any zoom. For
overlapping ports provide a named candidate chooser. Clicking a part body selects
it; hovering a hidden port must not silently steal a move gesture.

Signal connections do not move physical parts. Gas connections keep their current
geometry/snapping rules and show the proposed pipe path before commit. Physical
port alignment errors are visible. Disconnect/reconnect commands are available
from ports and the inspector; all connection edits are undoable.

### Add sensors and configure ECUs

Use Add sensor on a selected part or a specific pipe location. Offer supported
sensor types, show the tap/pickup marker, and create a matching Logic reference.
Selecting either representation reveals its host and measurement location.

ECU inspector groups Required, Connected and Optional inputs by function. Keep
connected ports visible and let optional groups expand. A guided checklist helps
choose a strategy, attach required sensors and assign actuator targets. Every
measurement displays units, source, validity and fallback state.

### Inspect and test

Simulation controls are independent of 3D/Logic tab selection. Distinguish Run,
Pause, Step and Stop/return-to-edit. Show simulation speed and time. Structural
properties explain why editing is locked during Test; safe live tuning shows
its applied value without resetting the machine.

Entering Test does not switch to a different workspace or change selection.
Keep the current 3D camera, Logic canvas and split-view arrangement. Stopping
returns to editing in that same context; live tuning retains existing persistence
and undo behavior. Start running immediately, with Pause and Step available in
the persistent simulation controls.

Hovering a signal reveals its current value; the inspector can pin it to a trace
or control panel. Physical measurements can also be added from the selected part.
Readouts identify the shaft, sensor or port they measure. Missing and invalid
signals never display as an ordinary zero or false state.

## Readability and interaction requirements

- Text and controls respond to window size and UI scaling. Scroll panels rather
  than drawing controls outside their bounds; avoid the current fixed-coordinate
  overlap risk as parts and properties grow.
- Focused numeric fields accept keyboard edits, units are visible, and invalid
  input remains editable with a local explanation. Escape cancels the edit;
  shortcuts do not trigger transforms while typing in a field.
- Preserve useful shortcuts, add visible tooltips, and keep camera gestures
  separate from node-canvas gestures. Document both in a compact help overlay.
- Selection, warning and disabled states remain legible in the dark theme.
  Signal meaning is also conveyed through labels and direction shapes.
- Keep the viewport stable when changing selection. Fit/focus is explicit.
  Unrelated panel refreshes must not jump scroll position or steal text focus.
- Keep raw rendering and UI state ownership explicit so panel rendering remains
  reliable after 3D drawing. Rendering optimization must preserve hit testing.

## Delivery slices

1. Appearance and layout foundation: shared controls/theme, responsive panels,
   typography, text measurement, clipping and consistent input handling. Rework
   the existing workshop first so today's parts already have a coherent UI.
2. Descriptor-driven inspector, connection gestures, named ports and filters.
3. Searchable library/object tree, then Logic tab and optional split view with
   shared selection, stable node layout and live values.
4. Sensor placement and grouped ECU connector workflow.
5. Integrated test controls, traces, checks and pinned operator controls.

Coordinate these slices with the systems roadmap: UI can display a type only
after document/runtime descriptors define it. Validate layouts at the agreed
minimum window size and scaling, connection picking in dense assemblies, keyboard
focus, save/restore behavior and the same workflows across 3D, Logic and split view.

## Navigation decisions

Keep the existing familiar 3D controls: Alt+left drag or right drag on empty space
orbits, middle drag pans, wheel zooms, F focuses selection and Home fits all.
An actual drag orbits; right click without dragging opens the context menu.
UI interaction consumes input before viewport handling, and text editing captures
its shortcuts. Escape cancels the active gesture before clearing selection.

Logic uses wheel zoom about the pointer and middle drag to pan. Plain left click
selects, Shift modifies selection, and dragging empty canvas makes a selection
rectangle. Drag nodes by their header, ports by their connector and panel sizes
by their divider; the pointer/hover state identifies the pending action.

## First milestone acceptance

Review the existing single-cylinder, flat-six and V8 imports with long names,
multi-selection, pipe route editing, ECU properties, Checks and instruments.
Exercise empty, selected, hovered, disabled, focused, invalid and running states.

At 1920x1080 and 1280x720 at 100% scale, and at representative larger display
scales, verify that text never overlaps unrelated controls, field units remain
readable, panels scroll within bounds and essential commands stay reachable.
Resize while editing, reopen saved panel layouts, expand long property groups
and open menus near window edges. Appearance/layout review is required before
adding the new systems' more complex panels. Later slices repeat this review for
the dense ECU connector view, Logic and split view as they become available.

No further preference decisions are blocking this plan. Implementation will use
these defaults and adjust details through focused visual and interaction review.