# Workbench UI design

## Summary

Implemented Leptos simulator prototype retains variant B's floating tools, without variant or phase toggles. Two independently loadable full switched converters reproduce thesis **Figure 2.1 Dickson** and **Figure 2.2 Ladder**, not Figure 2.3 phase equivalents. Validated oriented incidence matrices drive two-terminal SVG components and net routes. Explicit Run snapshots editable component and operating values, then shows original **prototype** RSCC/loss estimates, sweep plots, plus separately derived ideal no-load voltage compatibility. No private QFA backend, loaded-output model, or validated loss result is exposed. Bottom drawer occupies its own scrollable layout row and expands. Generated visual: [workbench-ui-feedback-design-visual.html](workbench-ui-feedback-design-visual.html).

Production decisions below remain targets unless explicitly scoped here. Persistence, guest access, invitations, general terminal editing, component insertion, segment handles, ELK, and Plotly are **not implemented**.

## Terms

### workbench

Leptos workbench prototype in ports/workbench-prototype-rust for editing and analyzing switched-capacitor converter architectures.

Avoid: `legacy workbench`.

### terminal

One of exactly two electrical connection points owned by a component.

Avoid: `component node`, `central point`.

### net

Electrical connection joining component terminals directly or through shared connectivity.

Avoid: `component`.

## Why

Review the running workbench UI and provide concrete feedback about what should change.

Retain floating tools, remove phase switching, model every component with two terminals, and derive nets from architecture matrices. Layout never defines electrical connectivity. Dickson uses the existing native architecture fixture; Ladder uses an explicitly approved thesis transcription because native generator is defective (see reference mapping below). Simulator algorithms and charge-flow intermediates remain private IP. Current client combines public ideal KVL compatibility analysis with clearly labelled original heuristic prototype estimates; it is not native QFA or physical loss validation.

## Locked decisions

### Target user

Decision: **Engineers familiar with power electronics but new to this tool**

Engineering familiarity permits exact domain language while still requiring discoverable controls and clear result explanations; this gives broader utility without turning workbench into a tutorial.

Rejected:
- **Researchers already fluent in switched-capacitor design** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.
- **Students learning converter architecture and QFA** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.

### Schematic symbol engine

Decision: **SVG symbols implemented in Leptos**

SVG preserves browser interaction, terminal hit-testing, and direct net editing without adding LaTeX server infrastructure. Use Circuitikz notation as visual reference, not runtime engine.

Rejected:
- **Circuitikz rendered through a server pipeline** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.
- **Import an existing browser schematic library** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.

### First release form

Decision: **Hosted public web app**

Hosted access lowers evaluation friction while a local package supports reproducible research and sensitive designs; cost is maintaining two deployment paths.

Rejected:
- **Local open-source application** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.
- **Hosted app plus reproducible local package** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.

### Hosted access boundary

Decision: **Invite-only named researchers and engineers**

Invite-only access protects simulator control during validation, limits support load, and creates direct research feedback. Cost is slower adoption and manual onboarding.

Rejected:
- **Anyone with an account** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.
- **Public anonymous access with usage limits** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.

### Design confidentiality

Decision: **Process transiently and store nothing by default**

No default storage minimizes confidentiality risk and lowers trust barriers for unpublished converter work. Saved projects can be added later with explicit consent.

Rejected:
- **Save private projects under each account** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.
- **Store designs for product research and model improvement** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.

### Loss-input responsibility

Decision: **Preset defaults with optional expert overrides**

Presets give credible baseline results and keep proprietary model detail server-side; expert overrides support real use without forcing every user through a long setup.

Rejected:
- **Curated server-side technology presets** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.
- **User enters every device and operating parameter** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.

### Result transparency

Decision: **Value, units, and named assumptions**

Named assumptions make results auditable enough for engineering use without revealing proprietary computational intermediates or implementation formulas.

Rejected:
- **Add formulas but omit internal vectors** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.
- **Values only** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.

### Schematic routing engine

Decision: **ELK.js layered orthogonal routing**

ELK.js remains the production candidate and needs a focused converter-loop/fixed-port proof. **Approved reference-slice ceiling:** thesis-like component placement plus horizontal net-rail metadata; routes are recomputed from actual terminals after component movement. Background halos mark nonconnecting crossings; filled dots mark branching. This constrained reference renderer is not adoption of a general custom router. Large moves may overlap symbols or different-net segments; arbitrary topology insertion, obstacle avoidance, segment handles, and ELK remain deferred. Reset restores reference placement.

Rejected:
- **Graphviz WASM routing** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.
- **Custom deterministic orthogonal router** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.

### Results visualization stack

Decision: **Plotly.js through wasm-bindgen/web-sys**

Plotly.js provides engineering-friendly interactive axes, hover, zoom, legends, export, and broad chart types. Leptos can own state while a small JS boundary owns plot lifecycle. Cost is bundle size and imperative cleanup.

Rejected:
- **Apache ECharts through wasm-bindgen/web-sys** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.
- **Rust-native egui_plot or plotters** — lost because it adds the trade-offs identified in this decision and does not match selected control, privacy, or workflow boundary.

## Routine choices

- **Primary review goal:** Improve visual polish and consistency
- **Feedback scope:** Layout and interaction changes within existing features
- **Terminal connection behavior:** Drag directly from one terminal to another
- **Net branching:** Allow branches only from explicit junction dots
- **Client project storage:** IndexedDB autosave plus explicit JSON import/export
- **Invitation identity:** Email magic-link invitations
- **Crossing-wire semantics:** Crossings never connect without a junction dot
- **Guest capability (production target):** Unsaved editor and bounded analysis; “transient” refers to retention, not time-domain simulation
- **Wire routing:** Orthogonal segments with automatic routing
- **Analysis pane placement:** Bottom drawer below schematic
- **Guest simulation limits:** Rate limit and cap topology size
- **Routing correction:** Drag generated segment handles
- **Analysis execution:** Explicit Run button
- **Guest limit response:** Explain limit and offer invitation request
- **Analysis result scope:** Values, units, assumptions only; private charge-flow vectors and symbolic intermediates never exposed.
- **Component insertion:** Drag symbols from a compact component palette
- **Stale result behavior:** Keep results visible with a prominent stale marker
- **Drawer expansion extent:** Resizable up to nearly full workspace height

## Verified facts

- Current prototype is Leptos 0.8 CSR under `ports/workbench-prototype-rust`.
- Existing repository includes Dickson topology and matrix generators; generated connectivity must be source of truth for schematic graph.
- Circuitikz is suitable as notation/reference and document rendering, not as interactive browser schematic model.
- ELK.js supports browser graph layout, explicit ports, and orthogonal routing; adoption still requires converter-loop proof.
- Plotly.js can be integrated behind a small JavaScript boundary while Leptos owns application state.

## Risks

- Incorrect mapping from topology matrices to component terminals would produce electrically false schematics.
- Automatic routing may produce poor closed-loop converter layouts; proof must cover fixed ports, junctions, crossings, and incremental edits.
- Hosted loss estimates can appear authoritative unless presets, overrides, units, and assumptions remain visible.
- Guest simulation requires topology-size and request-rate enforcement.
- Client-only projects can be lost with browser data; explicit JSON export is required.
- Private simulator endpoints need access control and must never expose charge-flow vectors or symbolic intermediates.

## Deferred

- Named researcher outreach and release validation cohort selection follow implementation proof.
- Exact guest and invited-user compute limits require capacity measurements.

## Implemented reference mapping and analysis boundary

`ports/workbench-prototype-rust/src/model.rs` constructs reduced incidence matrices, validates each completed column has one +1 and one −1, and decodes terminals. Reference n0 is reconstructed by `-sum(column)`. Source and selected output are explicit metadata. Exactly two binary activation rows supported. Geometry and analysis snapshots are separate: moves do not mark results stale; input/reference changes retain previous run visibly stale.

**Dickson Figure 2.1:** capacitor endpoints C1=(n2,n6), C2=(n3,n5), C3=(n4,n0); S1..S7=(n1,n2),(n2,n3),(n3,n4),(n4,n5),(n5,n0),(n6,n0),(n4,n6). Source=(n1,n0), output=(n4,n0). Same ordering as `dickson_arch(3)` and MATLAB R2021a fixture. Phase 1 odd, phase 2 even; no phase selector.

**Ladder Figure 2.2:** independently transcribed thesis architecture, **not generated by `ladder_arch` and not MATLAB parity**. C1=(n1,n3), C2=(n2,n4), C3=(n3,n5), C4=(n4,n6), C5=(n5,n0). Six serial switches S1..S6=(n1,n2),(n2,n3),(n3,n4),(n4,n5),(n5,n6),(n6,n0). Source=(n1,n0), output=(n5,n0). Printed switch labels top-to-bottom are S1,S1,S2,S3,S4,S5; UI normalizes positions to S1..S6. Odd/even activation by normalized position is an explicit reconstructed assumption, approved for this reference fixture. `ladder_matrix.m` uses `A_caps(end-1)=1` linear indexing into first column and leaves final column empty; also lacks Figure 2.2 source-connected first capacitor. MATLAB repair and characterization precede any native Ladder parity claim (ADR-0002); no MATLAB files changed.

Ideal solver builds phase-specific node potentials with source=1, closed-switch equality, and shared capacitor voltage differences across both phases. Gaussian elimination rejects inconsistent/underdetermined constraints and non-phase-invariant selected output. Both independent matrices derive Vout/Vsrc=1/3, 8 V at 24 V. No ratio constant drives displayed analysis. Floating-point tolerance 1e-9; no-load ideal result is not loaded performance, charge-flow, loss, or transient simulation.

Tests cover exact capacitor endpoints, both phase contractions, ratio, invalid matrices/phases/output, terminal-attached orthogonal routes, and geometry invariance. Browser inspected generated SVG screenshots for both references. Live Leptos acceptance passed through parent-owned HTTP hosting: both references, ratio/output, editable simulator controls, stale snapshots, keyboard movement, responsive drawer, and expanded analysis were browser-checked. Public preview remains transient deployment infrastructure, not production hosting.

Regenerate visual from same Rust model/renderer (repository root):

```sh
cargo run --manifest-path ports/workbench-prototype-rust/Cargo.toml --example design_visual -- docs/workbench-ui-feedback-design-visual.html
```

Visual is static layout preview with independent converter selection, not a second editor. No raster schematics or separately invented SVG wiring. Public hosted URL previously returned FRP Not Found; no deployment claim.