Enhance simulation context and provider: Introduce SimulationFrameState and SimulationFrameStateDiff types, update currently viewed frame handling, and refactor related components for improved state management and clarity.

Author: kube

libs/@hashintel/petrinaut/src/state/simulation-context.ts

@@ -9,6 +9,53 @@ export type SimulationState =
   | "Error"
   | "Paused";
 
+/**
+ * State of a simulation frame.
+ */
+export type SimulationFrameState = {
+  number: number;
+  time: number;
+  places: {
+    [placeId: string]:
+      | {
+          /** Number of tokens in the place at the time of the frame. */
+          tokenCount: number;
+        }
+      | undefined;
+  };
+  transitions: {
+    [transitionId: string]:
+      | {
+          /** Time since last firing of the transition at the time of the frame. */
+          timeSinceLastFiring: number;
+        }
+      | undefined;
+  };
+};
+
+/**
+ * Difference between two simulation frame states.
+ */
+export type SimulationFrameStateDiff = {
+  currentFrame: SimulationFrameState;
+  comparedFrame: SimulationFrameState;
+  places: {
+    [placeId: string]:
+      | {
+          tokenCount: number;
+        }
+      | undefined;
+  };
+  transitions: {
+    [transitionId: string]:
+      | {
+          /** Number of times this transition fired since the compared frame. */
+          firingCount: number;
+        }
+      | undefined;
+  };
+};
+
 export type InitialMarking = Map<
   string,
   { values: Float64Array; count: number }
@@ -25,7 +72,16 @@ export type SimulationContextValue = {
   errorItemId: string | null;
   parameterValues: Record<string, string>;
   initialMarking: InitialMarking;
-  currentlyViewedFrame: number;
+  /**
+   * The currently viewed simulation frame state.
+   * Null when no simulation is running or no frames exist.
+   */
+  currentViewedFrame: SimulationFrameState | null;
+  /**
+   * The difference between the currently viewed frame and the previous frame.
+   * Null when no simulation is running, no frames exist, or viewing frame 0.
+   */
+  currentViewedFrameDiff: SimulationFrameStateDiff | null;
   dt: number;
 
   // Actions
@@ -41,7 +97,7 @@ export type SimulationContextValue = {
   run: () => void;
   pause: () => void;
   reset: () => void;
-  setCurrentlyViewedFrame: (frameIndex: number) => void;
+  setCurrentViewedFrame: (frameIndex: number) => void;
 };
 
 const DEFAULT_CONTEXT_VALUE: SimulationContextValue = {
@@ -51,7 +107,8 @@ const DEFAULT_CONTEXT_VALUE: SimulationContextValue = {
   errorItemId: null,
   parameterValues: {},
   initialMarking: new Map(),
-  currentlyViewedFrame: 0,
+  currentViewedFrame: null,
+  currentViewedFrameDiff: null,
   dt: 0.01,
   setInitialMarking: () => {},
   setParameterValue: () => {},
@@ -62,7 +119,7 @@ const DEFAULT_CONTEXT_VALUE: SimulationContextValue = {
   run: () => {},
   pause: () => {},
   reset: () => {},
-  setCurrentlyViewedFrame: () => {},
+  setCurrentViewedFrame: () => {},
 };
 
 export const SimulationContext = createContext<SimulationContextValue>(

libs/@hashintel/petrinaut/src/state/simulation-provider.tsx

@@ -14,6 +14,8 @@ import {
   type InitialMarking,
   SimulationContext,
   type SimulationContextValue,
+  type SimulationFrameState,
+  type SimulationFrameStateDiff,
   type SimulationState,
 } from "./simulation-context";
 
@@ -24,7 +26,10 @@ type SimulationStateValues = {
   errorItemId: string | null;
   parameterValues: Record<string, string>;
   initialMarking: InitialMarking;
-  currentlyViewedFrame: number;
+  /** Internal frame index for tracking which frame is being viewed */
+  currentViewedFrameIndex: number | null;
+  /** Internal frame index for tracking which frame was previously viewed */
+  previousViewedFrameIndex: number | null;
   dt: number;
 };
 
@@ -35,10 +40,87 @@ const initialStateValues: SimulationStateValues = {
   errorItemId: null,
   parameterValues: {},
   initialMarking: new Map(),
-  currentlyViewedFrame: 0,
+  currentViewedFrameIndex: null,
+  previousViewedFrameIndex: null,
   dt: 0.01,
 };
 
+/**
+ * Converts a simulation frame to a SimulationFrameState.
+ */
+function buildFrameState(
+  simulation: SimulationContextValue["simulation"],
+  frameIndex: number,
+): SimulationFrameState | null {
+  if (!simulation || simulation.frames.length === 0) {
+    return null;
+  }
+
+  const frame = simulation.frames[frameIndex];
+  if (!frame) {
+    return null;
+  }
+
+  const places: SimulationFrameState["places"] = {};
+  for (const [placeId, placeData] of frame.places) {
+    places[placeId] = {
+      tokenCount: placeData.count,
+    };
+  }
+
+  const transitions: SimulationFrameState["transitions"] = {};
+  for (const [transitionId, transitionData] of frame.transitions) {
+    transitions[transitionId] = {
+      timeSinceLastFiring: transitionData.timeSinceLastFiring,
+    };
+  }
+
+  return {
+    number: frameIndex,
+    time: frame.time,
+    places,
+    transitions,
+  };
+}
+
+/**
+ * Computes the difference between two simulation frames.
+ */
+function buildFrameStateDiff(
+  currentFrame: SimulationFrameState,
+  comparedFrame: SimulationFrameState,
+): SimulationFrameStateDiff {
+  const places: SimulationFrameStateDiff["places"] = {};
+  for (const placeId of Object.keys(currentFrame.places)) {
+    const currentTokenCount = currentFrame.places[placeId]?.tokenCount ?? 0;
+    const comparedTokenCount = comparedFrame.places[placeId]?.tokenCount ?? 0;
+    places[placeId] = {
+      tokenCount: currentTokenCount - comparedTokenCount,
+    };
+  }
+
+  const transitions: SimulationFrameStateDiff["transitions"] = {};
+  for (const transitionId of Object.keys(currentFrame.transitions)) {
+    const currentTimeSinceLastFiring =
+      currentFrame.transitions[transitionId]?.timeSinceLastFiring ?? 0;
+    // Count firings: if timeSinceLastFiring is 0, the transition just fired
+    // We need to count how many times it fired between the two frames
+    // For simplicity, we count 1 if it fired in current frame (timeSinceLastFiring === 0)
+    // and the compared frame had a non-zero timeSinceLastFiring
+    const justFired = currentTimeSinceLastFiring === 0;
+    transitions[transitionId] = {
+      firingCount: justFired ? 1 : 0,
+    };
+  }
+
+  return {
+    currentFrame,
+    comparedFrame,
+    places,
+    transitions,
+  };
+}
+
 /**
  * Internal component that subscribes to simulation state changes
  * and shows notifications when appropriate.
@@ -190,7 +272,8 @@ export const SimulationProvider: React.FC<SimulationProviderProps> = ({
             state: "Paused",
             error: null,
             errorItemId: null,
-            currentlyViewedFrame: 0,
+            currentViewedFrameIndex: 0,
+            previousViewedFrameIndex: null,
           };
         } catch (error) {
           // eslint-disable-next-line no-console
@@ -253,7 +336,8 @@ export const SimulationProvider: React.FC<SimulationProviderProps> = ({
             state: newState,
             error: null,
             errorItemId: null,
-            currentlyViewedFrame: updatedSimulation.currentFrameNumber,
+            previousViewedFrameIndex: prev.currentViewedFrameIndex,
+            currentViewedFrameIndex: updatedSimulation.currentFrameNumber,
           };
         } catch (error) {
           // eslint-disable-next-line no-console
@@ -358,7 +442,8 @@ export const SimulationProvider: React.FC<SimulationProviderProps> = ({
         error: null,
         errorItemId: null,
         parameterValues,
-        currentlyViewedFrame: 0,
+        currentViewedFrameIndex: null,
+        previousViewedFrameIndex: null,
         // Keep initialMarking when resetting - it's configuration, not simulation state
       }));
     },
@@ -384,7 +469,7 @@ export const SimulationProvider: React.FC<SimulationProviderProps> = ({
         return { ...prev, state: newState };
       }),
 
-    setCurrentlyViewedFrame: (frameIndex: number) =>
+    setCurrentViewedFrame: (frameIndex: number) =>
       setStateValues((prev) => {
         if (!prev.simulation) {
           throw new Error(
@@ -395,12 +480,52 @@ export const SimulationProvider: React.FC<SimulationProviderProps> = ({
         const totalFrames = prev.simulation.frames.length;
         const clampedIndex = Math.max(0, Math.min(frameIndex, totalFrames - 1));
 
-        return { ...prev, currentlyViewedFrame: clampedIndex };
+        return {
+          ...prev,
+          previousViewedFrameIndex: prev.currentViewedFrameIndex,
+          currentViewedFrameIndex: clampedIndex,
+        };
       }),
   };
 
+  // Compute the currently viewed frame state
+  const currentViewedFrame =
+    stateValues.currentViewedFrameIndex !== null
+      ? buildFrameState(
+          stateValues.simulation,
+          stateValues.currentViewedFrameIndex,
+        )
+      : null;
+
+  // Compute the frame diff (comparing current frame with previous frame)
+  let currentViewedFrameDiff: SimulationFrameStateDiff | null = null;
+  if (
+    currentViewedFrame &&
+    stateValues.currentViewedFrameIndex !== null &&
+    stateValues.previousViewedFrameIndex !== null
+  ) {
+    const previousFrame = buildFrameState(
+      stateValues.simulation,
+      stateValues.previousViewedFrameIndex,
+    );
+    if (previousFrame) {
+      currentViewedFrameDiff = buildFrameStateDiff(
+        currentViewedFrame,
+        previousFrame,
+      );
+    }
+  }
+
   const contextValue: SimulationContextValue = {
-    ...stateValues,
+    simulation: stateValues.simulation,
+    state: stateValues.state,
+    error: stateValues.error,
+    errorItemId: stateValues.errorItemId,
+    parameterValues: stateValues.parameterValues,
+    initialMarking: stateValues.initialMarking,
+    dt: stateValues.dt,
+    currentViewedFrame,
+    currentViewedFrameDiff,
     ...actions,
   };
 

libs/@hashintel/petrinaut/src/views/Editor/components/BottomBar/simulation-controls.tsx

@@ -73,8 +73,8 @@ export const SimulationControls: React.FC<SimulationControlsProps> = ({
     run,
     pause,
     dt,
-    currentlyViewedFrame,
-    setCurrentlyViewedFrame,
+    currentViewedFrame,
+    setCurrentViewedFrame,
   } = use(SimulationContext);
 
   const { setBottomPanelOpen, setActiveBottomPanelTab } = use(EditorContext);
@@ -90,7 +90,8 @@ export const SimulationControls: React.FC<SimulationControlsProps> = ({
   const hasSimulation = simulation !== null;
   const isRunning = simulationState === "Running";
   const isComplete = simulationState === "Complete";
-  const elapsedTime = simulation ? currentlyViewedFrame * simulation.dt : 0;
+  const frameIndex = currentViewedFrame?.number ?? 0;
+  const elapsedTime = currentViewedFrame?.time ?? 0;
 
   const getPlayPauseTooltip = () => {
     if (isDisabled) {
@@ -178,7 +179,7 @@ export const SimulationControls: React.FC<SimulationControlsProps> = ({
           <div className={frameInfoStyle}>
             <div>Frame</div>
             <div>
-              {currentlyViewedFrame + 1} / {totalFrames}
+              {frameIndex + 1} / {totalFrames}
             </div>
             <div className={elapsedTimeStyle}>{elapsedTime.toFixed(3)}s</div>
           </div>
@@ -187,10 +188,10 @@ export const SimulationControls: React.FC<SimulationControlsProps> = ({
             type="range"
             min="0"
             max={Math.max(0, totalFrames - 1)}
-            value={currentlyViewedFrame}
+            value={frameIndex}
             disabled={isDisabled}
             onChange={(event) =>
-              setCurrentlyViewedFrame(Number(event.target.value))
+              setCurrentViewedFrame(Number(event.target.value))
             }
             className={sliderStyle}
           />

libs/@hashintel/petrinaut/src/views/Editor/panels/PropertiesPanel/initial-state-editor.tsx

@@ -254,24 +254,21 @@ export const InitialStateEditor: React.FC<InitialStateEditorProps> = ({
   const internalResize = useResizable(250);
   const { height, isResizing, containerRef, startResize } = internalResize;
 
-  const {
-    initialMarking,
-    setInitialMarking,
-    simulation,
-    currentlyViewedFrame,
-  } = use(SimulationContext);
+  const { initialMarking, setInitialMarking, simulation, currentViewedFrame } =
+    use(SimulationContext);
 
   // Determine if we should show current simulation state or initial marking
   const hasSimulation = simulation !== null && simulation.frames.length > 0;
+  const frameIndex = currentViewedFrame?.number ?? 0;
 
   // Get current marking for this place - either from simulation frame or initial marking
   const getCurrentMarkingData = (): {
     values: Float64Array;
     count: number;
   } | null => {
     if (hasSimulation) {
-      // Get from currently viewed frame
-      const currentFrame = simulation.frames[currentlyViewedFrame];
+      // Get from currently viewed frame (need raw frame for buffer access)
+      const currentFrame = simulation.frames[frameIndex];
       if (!currentFrame) {
         return null;
       }