FE-1584: Run the website's optimization demo in the browser

[kube]

Important

Experimental
Behind the In-browser optimization feature flag.

Summary

Before this PR, the website's optimization demo needed the Python optimizer service running behind a dev proxy, so the main demo never showed an Optimizations tab and the /optimization route was the only way to try a study.

This PR provides the in-browser optimizer on the main demo through PetrinautOptimizationContext, so a visitor who enables the experimental setting runs whole studies in their tab. /optimization stays the Python-service variant for local development, behind the existing VITE_PETRINAUT_OPT_PROVIDER=service. User guide describes the in-browser mode, its drawer, Stop and Continue, parallel steps and the Surface; architecture docs describe the shared study library and the browser runtime.

9517_5.mp4

Links

• Ticket FE-1584
• Docs The browser runtime
• Docs The subprocess boundary › One study, two drivers
• Docs The sweep surface
• Docs Optimization
• Docs Visual settings

Changes

Website

• BrowserOptimizationProvider wraps the main demo with createBrowserOptimization()

  Optimizations tab appears once the visitor enables the setting; no build variable involved.

• /optimization stays the service-backed demo behind VITE_PETRINAUT_OPT_PROVIDER=service

  Documented in .env.example and the README's "Optimization demo" section.

• No CSP change needed

  vercel.json sets frame-ancestors only; a future CSP needs worker-src 'self', wasm-unsafe-eval, and script and connect sources for jsDelivr and PyPI.

User guide

• "Creating an optimization" covers Runs per step, the Seed field, the Backend switch and the optimizer's random start-up steps
• "Watching results" describes the connected study's drawer

  Steps as dots on the Surface with the field filling in, the metric line streaming for the followed step, Stop and Continue, the settle on the best, the refinement rule, the activity list.

• New "Running in the browser" section

  Setting path, first-run download, following steps, Parallel steps and the computing chip, picking parameters after completion, Stop and Continue semantics, keeping the tab open, parity with the service.

• Visual settings entry for the new setting

Architecture docs

• Browser runtime page with a sequence diagram of one trial and the study-handle lifecycle

  Data flow, following and refinement, a "Stop, Continue and parallel steps" section, what each side owns, parity with the service.

• "One study, two drivers" section on the subprocess boundary page
• Sweep surface page says which surface samples a grid and which draws the optimizer's steps

Test coverage

• Existing @apps/petrinaut-website unit suite, lint:tsc and build
• lint:arch-docs:

  Layer annotations and links of the authored pages.

• Manual run in the browser:

  Main demo with the setting off shows no Optimizations tab.
  With it on, a study follows each step, streams the metric line, stops and continues, completes with a best value, and a Surface click refines the picked point.
  /optimization is not found without the variable; no console errors.

How to test

• Open Petrinaut preview on Vercel
• Viewport controls > Settings > Simulation > In-browser optimization

  Expect Simulate to gain an Optimizations tab

• Menu > Load example > Vaccination Campaign
• Simulate > Optimizations > Create
• Optimize vaccination_coverage and contact_reduction, minimize Total cost, 8 steps, 3 runs per step, 2 parallel steps, Run

  Expect two rings in flight on the Surface, dots landing, the field filling in, the Total cost line streaming

• Stop

  Expect Stopped, the navigation on the best dot, refinement to 100 runs

• Continue

  Expect the study resuming with continued numbering, then Complete

• Click a corner of the Surface

  Expect "8 runs · cannot beat the best"

• Drag the coverage slider towards the best dot

  Expect refinement climbing and the metric line restreaming

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 4, 2026 12:36pm UTC
petrinaut	Ready	Preview	Sep 4, 2026 12:36pm UTC
petrinaut-docs	Ready	Preview	Sep 4, 2026 12:36pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 4, 2026 12:36pm UTC