Add machine workshop, typed logic, mechanics and sensor-driven ECUs

docs/WORKSHOP_UI_PLAN.md

@@ -0,0 +1,258 @@
+# 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.