Add Petrinaut optimization UI capability

Author: kube

.changeset/fresh-optimizers-stream.md

@@ -0,0 +1,6 @@
+---
+"@hashintel/petrinaut-core": minor
+"@hashintel/petrinaut": minor
+---
+
+Add an optional host-provided optimization stream and show an Optimization toggle when it is available.

apps/petrinaut-website/src/main/app.tsx

@@ -1,11 +1,17 @@
 import { BrunchDemoApp } from "./app/brunch-demo/brunch-demo-app";
 import { isBrunchDemoRoute } from "./app/brunch-demo/brunch-route";
 import { LocalStorageDemoApp } from "./app/local-storage-demo/local-storage-demo-app";
+import { OptimizationDemoApp } from "./app/optimization-demo/optimization-demo-app";
+import { isOptimizationDemoRoute } from "./app/optimization-demo/optimization-route";
 
 export const DemoApp = () => {
   if (isBrunchDemoRoute()) {
     return <BrunchDemoApp />;
   }
 
+  if (isOptimizationDemoRoute()) {
+    return <OptimizationDemoApp />;
+  }
+
   return <LocalStorageDemoApp />;
 };

apps/petrinaut-website/src/main/app/optimization-demo/fake-optimization-provider.tsx

@@ -0,0 +1,24 @@
+import { PetrinautOptimizationContext } from "@hashintel/petrinaut/react";
+
+import type { PetrinautOptimization } from "@hashintel/petrinaut-core";
+import type { FC, PropsWithChildren } from "react";
+
+const wait = (durationMs: number) =>
+  new Promise<void>((resolve) => window.setTimeout(resolve, durationMs));
+
+const fakeOptimization: PetrinautOptimization = {
+  async *optimize() {
+    for (let value = 0; value < Number.MAX_SAFE_INTEGER; value += 1) {
+      yield value;
+      await wait(1_000);
+    }
+  },
+};
+
+export const FakeOptimizationProvider: FC<PropsWithChildren> = ({
+  children,
+}) => (
+  <PetrinautOptimizationContext value={fakeOptimization}>
+    {children}
+  </PetrinautOptimizationContext>
+);

apps/petrinaut-website/src/main/app/optimization-demo/optimization-demo-app.tsx

@@ -0,0 +1,8 @@
+import { LocalStorageDemoApp } from "../local-storage-demo/local-storage-demo-app";
+import { FakeOptimizationProvider } from "./fake-optimization-provider";
+
+export const OptimizationDemoApp = () => (
+  <FakeOptimizationProvider>
+    <LocalStorageDemoApp />
+  </FakeOptimizationProvider>
+);

apps/petrinaut-website/src/main/app/optimization-demo/optimization-route.ts

@@ -0,0 +1,5 @@
+export const isOptimizationDemoRoute = (): boolean => {
+  const path = window.location.pathname.replace(/\/+$/u, "") || "/";
+
+  return path === "/optimization";
+};

apps/petrinaut-website/vercel.json

@@ -11,6 +11,10 @@
     {
       "source": "/brunch",
       "destination": "/"
+    },
+    {
+      "source": "/optimization",
+      "destination": "/"
     }
   ],
   "functions": {

libs/@hashintel/petrinaut-core/src/index.ts

@@ -78,6 +78,7 @@ export type {
   PetrinautCommands,
   PetrinautMutations,
 } from "./instance";
+export type { PetrinautOptimization } from "./optimization";
 export { createPetrinautActions } from "./actions";
 export type {
   CreatePetrinautActionsOptions,

libs/@hashintel/petrinaut-core/src/optimization.ts

@@ -0,0 +1,9 @@
+/**
+ * Host-provided optimization capability for Petrinaut.
+ *
+ * The initial contract intentionally has no inputs: experiment properties and
+ * optimization configuration will be added as that integration is defined.
+ */
+export type PetrinautOptimization = {
+  optimize(): AsyncIterable<number>;
+};

libs/@hashintel/petrinaut/docs/experiments.md

@@ -22,6 +22,8 @@ Experiments live under the **Simulate** [global mode](drawing-a-net.md#global-mo
 | **Time step (dt)**      | `1`                               | Same meaning as in single-run simulations (see [Simulation](simulation.md#time-step-dt)).                                                                                                                          |
 | **Max time (seconds)**  | `180`                             | Each run advances until simulation time reaches this value, then completes.                                                                                                                                        |
 
+When Petrinaut is embedded with an optimization provider, the **Experiment** section also shows an **Optimization** toggle. The toggle is hidden when the host does not provide optimization, including on the default Petrinaut demo route. The demo site's `/optimization` route supplies a fake provider for previewing this surface. Optimization configuration and execution will be added in a later release.
+
 The model used is a snapshot of the current net at the time you press **Run**. Editing the net afterwards does not change runs that have already started.
 
 > Currently, an experiment can only run against one scenario at a time. To compare scenarios, create one experiment per scenario.

libs/@hashintel/petrinaut/src/react/index.ts

@@ -17,6 +17,8 @@ export {
   NetManagementContext,
   type NetManagement,
 } from "./net-management-context";
+export { PetrinautOptimizationContext } from "./optimization-context";
+export type { PetrinautOptimization } from "./optimization-context";
 export { ExperimentsContext, isExperimentActive } from "./experiments/context";
 export type {
   CreateExperimentInput,