FE-756: petrinaut product walkthrough

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

@@ -7,6 +7,7 @@ import {
   Petrinaut,
   type PetrinautAiChatTransport,
   type PetrinautAiMessage,
+  WalkthroughProvider,
 } from "@hashintel/petrinaut/ui";
 
 import { useSentryFeedbackAction } from "./app/sentry-feedback-button";
@@ -15,6 +16,7 @@ import {
   type SDCPNInLocalStorage,
   useLocalStorageSDCPNs,
 } from "./app/use-local-storage-sdcpns";
+import { walkthroughSteps } from "./app/walkthrough/walkthrough-steps";
 
 import type {
   MinimalNetMetadata,
@@ -279,18 +281,20 @@ export const DevApp = () => {
 
   return (
     <div style={{ height: "100vh", width: "100vw" }}>
-      <Petrinaut
-        aiAssistant={aiAssistant}
-        handle={activeHandle.handle}
-        existingNets={existingNets}
-        createNewNet={createNewNet}
-        hideNetManagementControls={false}
-        loadPetriNet={loadPetriNet}
-        readonly={false}
-        setTitle={setTitle}
-        title={currentNet.title}
-        viewportActions={[sentryFeedbackAction]}
-      />
+      <WalkthroughProvider steps={walkthroughSteps}>
+        <Petrinaut
+          aiAssistant={aiAssistant}
+          handle={activeHandle.handle}
+          existingNets={existingNets}
+          createNewNet={createNewNet}
+          hideNetManagementControls={false}
+          loadPetriNet={loadPetriNet}
+          readonly={false}
+          setTitle={setTitle}
+          title={currentNet.title}
+          viewportActions={[sentryFeedbackAction]}
+        />
+      </WalkthroughProvider>
     </div>
   );
 };

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

@@ -0,0 +1,71 @@
+// Videos must fill their 16:9 frame edge-to-edge. Avoid card-inside-the-card
+// framing (i.e. don't include a nested chrome window around the actual UI) —
+// the dialog already provides its own container.
+import introVideo from "./videos/01-intro-example.mp4";
+import experimentsVideo from "./videos/02-experiments-example.mp4";
+import aiVideo from "./videos/03-ai-example.mp4";
+
+import type { WalkthroughStep } from "@hashintel/petrinaut/ui";
+
+export const walkthroughSteps: WalkthroughStep[] = [
+  {
+    id: "welcome",
+    title: "Welcome to Petrinaut",
+    body: (
+      <>
+        <p>
+          <strong>Petrinaut</strong> is a workshop for building, simulating, and
+          analyzing Petri nets: a mathematical formalism for modelling
+          distributed systems.
+        </p>
+        <p>
+          People use it to analyze supply chains, workflows, chemical reactions,
+          epidemics, network protocols — anywhere multiple things happen at once
+          and influence each other.
+        </p>
+      </>
+    ),
+    videoHref: introVideo,
+    videoAlt: "The Petrinaut editor with an example net on the canvas",
+  },
+  {
+    id: "simulate",
+    title: "Simulate, experiment, and query your model",
+    body: (
+      <>
+        <p>
+          With your system modelled as a Petri net, you can explore and optimise
+          outcomes across different scenarios — for example, the failure rate of
+          a manufacturing line, or the throughput of a queueing system.
+        </p>
+        <p>
+          <strong>Petrinaut</strong> lets you run experiments on complex
+          probabilistic processes and build custom metrics to inspect the
+          results.
+        </p>
+      </>
+    ),
+    videoHref: experimentsVideo,
+    videoAlt: "Simulation view showing experiment results and a chart",
+  },
+  {
+    id: "build",
+    title: "Build your first model",
+    body: (
+      <>
+        <p>
+          To build your first model, use the drag-and-drop canvas or ask the AI
+          assistant to build one for you.
+        </p>
+        <p>
+          Describe what you want to simulate and the assistant edits your net
+          directly — adding places and transitions, writing custom firing rules,
+          and fixing errors as you iterate.
+        </p>
+      </>
+    ),
+    videoHref: aiVideo,
+    videoAlt:
+      "Canvas alongside the AI assistant panel mid-conversation editing the net",
+  },
+];

libs/@hashintel/petrinaut/src/ui/components/walkthrough/index.ts

@@ -0,0 +1,7 @@
+export { WalkthroughContext } from "./walkthrough-context";
+export type {
+  WalkthroughContextValue,
+  WalkthroughStep,
+} from "./walkthrough-context";
+export { WalkthroughProvider } from "./walkthrough-provider";
+export { WalkthroughDialog } from "./walkthrough-dialog";

libs/@hashintel/petrinaut/src/ui/components/walkthrough/walkthrough-context.ts

@@ -0,0 +1,20 @@
+import { createContext } from "react";
+
+export type WalkthroughStep = {
+  id: string;
+  title: string;
+  body: React.ReactNode;
+  videoHref: string;
+  videoAlt: string;
+};
+
+export type WalkthroughContextValue = {
+  isOpen: boolean;
+  open: () => void;
+  close: () => void;
+  steps: WalkthroughStep[];
+};
+
+export const WalkthroughContext = createContext<WalkthroughContextValue | null>(
+  null,
+);