Simulate stage¶

Status: PROPOSED

Simulate is the planned stage in docs/ui/ui-plan.md:120–139,208–215. The stage composition and new summary/toggle surfaces are PROPOSED. Existing playback behavior is tagged HOW IT IS with code citations.

Simulator mode opens in Simulate. Slicer mode can enter it after generation; the stage is a task, not a different engine session.

flowchart LR
  O["Open or generate toolpath"] --> P["Play / scrub"]
  P --> A["Auto-pause near finding"]
  A --> F["Open finding detail"]
  F --> X["Change settings or region"]
  X --> R["Re-slice and replay"]

Playback controls¶

The planned stage reuses the current shared PlaybackPanel; it does not create a second timer or playhead.

Control	Behavior	Honesty
Play / pause	Start or stop progressive drawing	HOW IT IS — the button exists (`src/Nps.Shell/Controls/PlaybackPanel.axaml:34–40`) and toggles the app timer (`src/SimulatorApp/MainWindow.axaml.cs:811–837`)
Speed	Set 0.1×–10× playback rate	HOW IT IS — slider range and default are real (`src/Nps.Shell/Controls/PlaybackPanel.axaml:59–63`); the app recomputes timer interval (`src/SimulatorApp/MainWindow.axaml.cs:839–847`)
Step back / forward	Move one G-code move	HOW IT IS — the two buttons exist (`src/Nps.Shell/Controls/PlaybackPanel.axaml:41–52`) and route through `SetSimulationState` (`src/SimulatorApp/MainWindow.axaml.cs:917–936`)
Auto-pause	Stop when forward playback enters a finding’s immediate move neighborhood	HOW IT IS — enabled by default (`src/Nps.Shell/Controls/PlaybackPanel.axaml:66–70`); rule is a pinned finding with `abs(findingMove − simMove) < 2` on a forward step (`src/SimulatorApp/MainWindow.axaml.cs:938–957`)
Move readout	Show current move / total moves	HOW IT IS (`src/Nps.Shell/Controls/PlaybackPanel.axaml:55–56`)
Scrubber	Jump to a move; pause during user input and conditionally resume	HOW IT IS (`src/Nps.Shell/Controls/PlaybackPanel.axaml:72–84`; `src/SimulatorApp/MainWindow.axaml.cs:850–915`)
Severity markers	Mark pinned findings on the scrubber	HOW IT IS — marker canvas and `SetMarkers` are wired (`src/Nps.Shell/Controls/PlaybackPanel.axaml:72–84`; `src/Nps.Shell/Controls/PlaybackPanel.axaml.cs:303–313`)

PROPOSED — Simulate makes this panel the default inspector tab in both ProductModes. Space additionally toggles play only while the Simulate viewport has focus; P remains the global playback key subject to focus scoping. See Keyboard and gestures.

Auto-pause precision

The current check pauses at distance 0 or 1 from any pinned finding, not at an exact “two moves before” offset and not only for Critical severity. The prototype retains the real rule unless a later product decision changes it.

Scrubber contract¶

HOW IT IS — pressing either the thumb or track records whether playback was active and pauses the timer. Releasing resumes only when it was active before the press (src/SimulatorApp/MainWindow.axaml.cs:868–915). Intermediate drag values are suppressed and the committed value drives ViewportSetSimulationState (src/Nps.Shell/Controls/PlaybackPanel.axaml.cs:454–484; src/SimulatorApp/MainWindow.axaml.cs:855–865).

PROPOSED — marker color communicates severity, hover names the finding, and clicking a marker opens Findings at that row. Unpinned findings remain in the list but have no timeline marker.

Findings summary bar¶

PROPOSED — the left sidebar shows a compact summary:

Readout	Action
`C:3 W:7 I:12`	Open Findings with the clicked severity filter active
`WarpGrid: ok` or risk summary	Open the relevant finding/overlay context
Current move / total	Keep playback position visible while the inspector changes

The counts come from existing findings-summary exports. HOW IT IS — the host already snapshots summaries through GetAnalysisFindingsSummaryCount and GetAnalysisFindingsSummary (src/Nps.EngineHost/EngineSession.cs:455–475). The sidebar summary and click-to-prefilter behavior are PROPOSED.

The status bar mirrors clickable C3 W7 I12 chips. It never invents zeroes before analysis has run.

Findings triage loop¶

PROPOSED — playback, overlays, and Findings form one loop:

Play or scrub until a severity marker is reached.
Auto-pause stops in the marker’s immediate move neighborhood.
Select the finding to focus its layer and move.
Read message, suggestion, category, and warp coordinates in the detail pane.
If the fix changes non-planar settings or a region, return to Prepare.
Re-slice, return to Simulate, and replay the same area.
Confirm the risk band and severity count improve.

HOW IT IS — Findings already has severity/category chips, a list, and a detail pane (src/Nps.Shell/Controls/FindingsPanel.axaml:35–119). Selecting a row raises FindingSelected (src/Nps.Shell/Controls/FindingsPanel.axaml.cs:328–332) and the Simulator focuses its layer/playhead (src/SimulatorApp/MainWindow.axaml.cs:665–727). Stage routing, prefiltered summary clicks, and non-planar fix actions remain PROPOSED.

Mesh underlay¶

PROPOSED — a visible Mesh underlay toggle controls a translucent model behind the toolpath in Prepare and Simulate.

HOW IT IS — Simulator already owns a MeshCanvasPainter and paints the MeshController snapshot before toolpath moves (src/SimulatorApp/MainWindow.axaml.cs:30–35,1008–1020). Slicer does not mount that background today. Promotion to both stages/ProductModes and the user-facing toggle are PROPOSED.

State	Planned result
On	Translucent loaded mesh remains visible behind played moves
Off	Toolpath only
Parsed G-code without a matching mesh	Toggle disabled with “No mesh loaded”

Warp deform¶

PROPOSED — Warp deform becomes an explicit toggle, separate from choosing a color-by field. It calls the existing ViewportSetWarpParams route and states its scale in the tooltip/readout.

HOW IT IS — selecting Warp Risk currently turns deformation on at scale 5; other overlay modes turn it off (src/Nps.Shell/ViewportController.cs:627–634,646–649). The explicit toggle is new and must not silently change when a user only changes color mapping.

Loaded-path provenance¶

Path source	Simulate behavior	Demo badge
Generated through the current demo generator	Playback is available after moves are presented	PROPOSED badge on
Parsed text G-code or BGCODE	Playback is available after parse/analyze	Badge off
No moves / parse failure	Empty state or error; no stale playback	No new provenance state

HOW IT IS — parsed paths reset playback to move 0 and populate the shared panel with move count and markers (src/SimulatorApp/MainWindow.axaml.cs:398–436). The badge itself is PROPOSED; see Honesty.

Empty states¶

State	Planned message	Status
No toolpath	`No toolpath loaded` + Open G-code	PROPOSED
Toolpath, no findings	`No findings for current analysis`	PROPOSED presentation over an empty real summary
Finding without move pin	Keep it in the list; no scrubber marker	PROPOSED presentation matching the current marker rule
No mesh	Disable Mesh underlay and Warp deform with reasons	PROPOSED