FE-588: Add basic Scenario support

[kube]

Kapture.2026-04-15.at.00.36.31.mp4

🌟 What is the purpose of this PR?

Adds basic Scenario support to Petrinaut. A Scenario is a reusable initial configuration (parameter overrides + initial token state) that can be selected before running a simulation.

This is a first pass — future work should harmonize the type system across Color dimensions, Net Parameters, and Scenario Parameters, which all share similar structure but are currently modeled independently.

At a high level, this PR introduces: scenario CRUD (create/edit/save), an expression-based LSP for scenario fields (with type-checking, completions, hover), a scenario compiler that evaluates expressions into concrete simulation state, and the UI to select and configure scenarios before running.

🔗 Related links

• FE-588

🔍 What does this change?

Scenario data model

• Add Scenario type with scenario parameters, parameter overrides, and initial state (discriminated union: per_place with string | number[][] or code with string)
• Add ScenarioParameter with types: real, integer, boolean, ratio
• Zod validation schema for persistence
• File format schema updated to match

Scenario form & drawers

• Create/View/Edit scenario via Drawer (TanStack Form for state management)
• Form-level validation: name required + unique, identifiers snake_case + unique
• LSP-gated submit: Save/Create disabled when TypeScript errors exist
• Footer shows error count badge + first error message
• Inline red outline on inputs with LSP diagnostics (shown on blur only)
• Form reset after successful create

LSP integration

• temp/scenario/initialize, didChange, kill protocol messages
• Virtual TypeScript files for each expression (function-wrapped with correct return types)
• scenario object for accessing scenario parameters in expressions
• Suffix support on VirtualFile for expression wrapping
• Pending message queue for React child-first effect ordering
• Only lint active initial state mode (per-place vs code)
• Skip empty expressions

Scenario compiler (compile-scenario.ts)

• Hardened new Function() evaluation (strict mode, prototype-less frozen objects, shadowed globals)
• Three-phase: scenario defaults → parameter overrides → initial state
• Supports per-place expressions (number), colored place data (number[][]), and code-mode (full function body returning object keyed by place name)
• 22+ tests covering evaluation, error handling, and sandboxing

Simulation integration

• SimulationContext gains selectedScenarioId, scenarioParameterValues, compiledScenarioResult
• Compiled scenario overrides parameterValues and initialMarking in context
• initialize() reads from effective (scenario-overridden) refs
• Scenario mutations (addScenario, updateScenario, removeScenario) bypass simulate-mode read-only guard

Simulation Settings

• Scenario picker dropdown with Edit/Create/Manage buttons
• Boolean params render as Switch, ratio params as Slider + NumberInput
• Scenario parameter values editable, recompiled on every change
• Place initial state shown as read-only when scenario active

UI polish

• Sticky section headers with gradient fade
• Drawer animation fix (remove forwards to avoid transform stacking context)
• Single-line CodeEditor: no vertical scroll, Enter works with suggest widget
• Select dropdown z-index fix, portal default changed to false
• Wider drawer (640px, max 90vw - 20px)

Examples

• SIR model: scenarios with population (int) + infected_ratio (ratio) params, expression-derived initial state
• Satellites: rename earth_radius → planet_radius, add gravity_force/planet_radius scenario params
• Satellites (non-launcher): "All Around the World" code-mode scenario
• Production Machines: flag RawMaterial/AvailableMachines as initial state

Other

• Metrics tab placeholder (disabled) in Simulate view
• Move simulation error display from Settings to Diagnostics tab
• Scrollable parameters list in Simulation Settings

🛡 What tests cover this?

• compile-scenario.test.ts: 25 tests covering expression evaluation, scenario parameters, Math functions, ternaries, rounding, error handling, sandboxing (prototype chain, globals), and colored place data

❓ How to test this?

1. Open the SIR or Satellites example
2. Go to Simulate mode → Scenarios tab → Create a scenario
3. Add scenario parameters, set parameter overrides with expressions
4. Verify LSP completions and error highlighting in expression editors
5. Select the scenario in Simulation Settings → verify parameters update
6. Press Play → confirm simulation uses scenario's initial state and parameters

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	Apr 16, 2026 9:15am
petrinaut	Ready	Preview	Apr 16, 2026 9:15am

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
hashdotdesign	Ignored	Preview	Apr 16, 2026 9:15am
hashdotdesign-tokens	Ignored	Preview	Apr 16, 2026 9:15am

[kube]

• FE-591: Add Metrics: timeline picker, compiler, and drawer #8633
• FE-588: Add basic Scenario support #8609 👈 (View in Graphite)
• FE-570: Replace SVG simulation timeline with uPlot #8627
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 82406f1. Configure here.}