view-sweep

Shared UI and server toolkit for parameter-sweep exploration dashboards.

View-sweep provides theming, Plotly chart conventions, widget primitives, data-provider adapters, and FastAPI server scaffolding — extracted from phase-sweep and designed to serve multiple projects across static, server, and desktop deployment modes.

Layers

• spec/ — the contract. TOML sources, committed JSON sidecars, a generated CSS file per palette, and a generated Plotly layout.template per palette variant.
• css/viewsweep.css — chrome and widget styles on .vs- classes, driven entirely by --vs-* custom properties.
• js/ — vanilla ES modules, no build step. Theme controller, Plotly layout builder, DOM widgets, chrome (tabs, panels, status bar), PNG export, and data providers (fetch, WebSocket, static, Tauri).
• py/ — view-sweep-server: create_app(AppConfig) app factory, ConnectionManager + /ws endpoint, protocol types. Wheels carry the browser assets; editable installs serve them from the checkout.

Browser usage

<script>document.documentElement.dataset.theme = localStorage.getItem("vs-theme") || "light";</script>
<link rel="stylesheet" href="/view-sweep/spec/palettes/engineering.css">
<link rel="stylesheet" href="/view-sweep/css/viewsweep.css">
<script src="/vendor/plotly.min.js"></script>
<script type="module">
  import { initTheme, loadPalette, bindThemeToggle } from "/view-sweep/js/theme.js";
  import { createPlot, loadPlotSpec } from "/view-sweep/js/plot.js";
  import { mountTabs, mountPanel, mountStatusBar } from "/view-sweep/js/chrome.js";
  import { FetchProvider } from "/view-sweep/js/providers/fetch.js";
  import { WebSocketProvider } from "/view-sweep/js/providers/websocket.js";

  const theme = initTheme({ palette: await loadPalette("/view-sweep/spec/palettes/engineering.json") });
  bindThemeToggle(document.querySelector("#theme-toggle"), theme);
  const plot = createPlot({ spec: await loadPlotSpec("/view-sweep/spec/plot.json"), theme });

  const api = new FetchProvider();
  const ws = new WebSocketProvider().connect();
  ws.onReconnect(async () => ws.subscribeJobs((await api.fetch("api/jobs")).map((j) => j.id)));

  const tabs = mountTabs({ tabBar: document.querySelector("#tabs"), paneHost: document.querySelector("#panes"),
                           tabs: [{ id: "waveforms", label: "Waveforms" }] });
  const panel = mountPanel({ id: "br", title: "Br waveform" });
  tabs.panes.get("waveforms").append(panel.card);
  document.addEventListener("vs:theme-change", () => Plotly.react(el, traces, plot.layout()));
</script>

Panels subscribe to the vs:* events listed in spec/events.toml rather than to chrome internals. Plotly is a peer dependency; view-sweep never ships one.

Development

uv sync --group dev
uv run python scripts/generate_json.py --check   # sidecars match TOML
uv run pytest                                    # contract, protocol, node, browser
node --test tests/js/*.test.mjs                             # JS logic tests alone

Browser tests run in headless Chromium when one is found (or set VS_CHROME); otherwise they skip.

License

Apache-2.0 — see LICENSE.

Contributing

See CONTRIBUTING.md.