H-5261: Add Petrinaut x Automerge POC (#72)

* petrinaut-automerge

* delete sim-core pre-push hook

* update readme

* clean up logging a bit

* redirect engine-web main

* revert package.json change

Author: CiaranMn

.config/husky/pre-push

@@ -1,47 +1,43 @@
 {
-  "name": "@hashintel/engine-web",
-  "version": "0.1.1",
-  "description": "HASH Core JavaScript bindings",
-  "repository": "https://github.com/hashintel/labs",
-  "license": "AGPL-3.0-only",
-  "scripts": {
-    "clean": "rimraf dist dist-node wasm/bundler wasm/node",
-    "prebuild": "wasm-pack build --target bundler --out-dir wasm/bundler --out-name hash",
-    "build": "npx tsc",
-    "prebuild:node": "wasm-pack build --target nodejs --out-dir wasm/node --out-name hash",
-    "build:node": "tsc --module commonjs --outdir dist-node",
-    "fmt": "prettier --write --cache \"*.{ts,js,json}\" \"{scripts,src}/**/*.{ts,js,json}\" && eslint --quiet --fix \"*.{ts,js,json}\" \"{scripts,src}/**/*.{ts,js,json}\"",
-    "lint": "prettier --check --cache \"*.{ts,js,json}\" \"{scripts,src}/**/*.{ts,js,json}\"  && eslint --quiet \"*.{ts,js,json}\" \"{scripts,src}/**/*.{ts,js,json}\" && tsc --noEmit",
-    "pretest": "yarn prebuild:node",
-    "test": "jest",
-    "prepare": "npx npm-run-all clean build build:node",
-    "prod-env": "cross-env-shell NODE_OPTIONS=\"--max_old_space_size=4096 --openssl-legacy-provider\" NODE_ENV=production",
-    "dev-env": "cross-env-shell NODE_OPTIONS=\"--max_old_space_size=4096 --openssl-legacy-provider\" NODE_ENV=development",
-    "build-stdlib": "yarn prod-env webpack --mode production",
-    "build-stdlib-dev": "yarn dev-env webpack --mode development"
-  },
-  "files": [
-    "dist/**/*",
-    "dist-node/**/*",
-    "wasm/**/*"
-  ],
-  "jest": {
-    "preset": "ts-jest/presets/js-with-babel",
-    "testEnvironment": "node",
-    "globals": {
-      "ts-jest": {
-        "babelConfig": true
-      }
-    }
-  },
-  "dependencies": {
-    "jstat": "1.9.4",
-    "node-fetch": "2.6.1",
-    "promise-worker-transferable": "github:hashdeps/promise-worker-transferable",
-    "rxjs": "6.6.6"
-  },
-  "main": "dist-node/index.js",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "devDependencies": {}
+	"name": "@hashintel/engine-web",
+	"version": "0.1.1",
+	"description": "HASH Core JavaScript bindings",
+	"repository": "https://github.com/hashintel/labs",
+	"license": "AGPL-3.0-only",
+	"scripts": {
+		"clean": "rimraf dist dist-node wasm/bundler wasm/node",
+		"prebuild": "wasm-pack build --target bundler --out-dir wasm/bundler --out-name hash",
+		"build": "npx tsc",
+		"prebuild:node": "wasm-pack build --target nodejs --out-dir wasm/node --out-name hash",
+		"build:node": "tsc --module commonjs --outdir dist-node",
+		"fmt": "prettier --write --cache \"*.{ts,js,json}\" \"{scripts,src}/**/*.{ts,js,json}\" && eslint --quiet --fix \"*.{ts,js,json}\" \"{scripts,src}/**/*.{ts,js,json}\"",
+		"lint": "prettier --check --cache \"*.{ts,js,json}\" \"{scripts,src}/**/*.{ts,js,json}\"  && eslint --quiet \"*.{ts,js,json}\" \"{scripts,src}/**/*.{ts,js,json}\" && tsc --noEmit",
+		"pretest": "yarn prebuild:node",
+		"test": "jest",
+		"prepare": "npx npm-run-all clean build build:node",
+		"prod-env": "cross-env-shell NODE_OPTIONS=\"--max_old_space_size=4096 --openssl-legacy-provider\" NODE_ENV=production",
+		"dev-env": "cross-env-shell NODE_OPTIONS=\"--max_old_space_size=4096 --openssl-legacy-provider\" NODE_ENV=development",
+		"build-stdlib": "yarn prod-env webpack --mode production",
+		"build-stdlib-dev": "yarn dev-env webpack --mode development"
+	},
+	"files": ["dist/**/*", "dist-node/**/*", "wasm/**/*"],
+	"jest": {
+		"preset": "ts-jest/presets/js-with-babel",
+		"testEnvironment": "node",
+		"globals": {
+			"ts-jest": {
+				"babelConfig": true
+			}
+		}
+	},
+	"dependencies": {
+		"jstat": "1.9.4",
+		"node-fetch": "2.6.1",
+		"promise-worker-transferable": "github:hashdeps/promise-worker-transferable",
+		"rxjs": "6.6.6"
+	},
+	"main": "dist-node/index.js",
+	"module": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"devDependencies": {}
 }

apps/sim-core/packages/engine-web/package.json

@@ -0,0 +1,35 @@
+# Petrinaut x Automerge
+
+This is a POC of [Petrinaut](https://github.com/hashintel/hash/tree/main/libs/%40hashintel/petrinaut) (a Petri net editor) with an [Automerge](https://automerge.org/) backend.
+
+## Setup
+
+```bash
+cd pocs/petrinaut-automerge
+yarn
+```
+
+Run `yarn dev` and navigate to http://localhost:5173 to see the app running.
+
+## Known issues
+
+1. Some changes in the UI don't create a granular update and are therefore are not good candidates for exploring visual diffing.
+
+   - **Granular updates**: add node; add connection; move node; edit net title; auto-layout (click 'layout' button, only nodes that actually move will have their x and y position updated)
+   - **Coarse updates**: edit token types (overwrites entire object); edit node title (overwrites entire title, doesn't use `changeText`); edit node token markings (overwrites entire object).
+2. Sometimes the app will hang at different points when trying to retrieve data from the Automerge sync server. This can typically be temporarily resolved by removing the root Automerge URL from local storage, and visiting http://localhost:5173 to start a new one (remove any Automerge URL from the address). I don't know why this happens. **This is why there are a lot of logs relating to `useDocument`** – so I can see where it hangs. These can be deleted.
+3. When creating a new net, MUI Autocomplete thinks the value is undefined. Unclear why this is (it should be defined), not going to invest time in it right now.
+
+## Questions re. Automerge
+1. Why known issue (2) happens
+2. What the best way is of subscribing to patches as they change (There's currently a hacky version in `petrinaut-wrapper.tsx` which logs out patches on every render if the head has changed)
+3. When/why will there be more than one `head`?
+
+## TODOs
+
+1. Put POC into Patchwork
+2. Discuss approach to visual diffing
+   - have Petrinaut be aware of change history
+   - ability to explore change history, with appropriate visual indicators for diffs (deletions, additions)
+3. Add more granular updates
+4. Allow deleting nodes / edges

pocs/petrinaut-automerge/README.md

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <link rel="icon" type="image/png" href="/hash.svg" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Petrinaut & Automerge</title>
+</head>
+
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+
+</html>

pocs/petrinaut-automerge/index.html

@@ -0,0 +1,36 @@
+{
+	"name": "petrinaut-automerge",
+	"private": true,
+	"version": "0.0.1",
+	"type": "module",
+	"scripts": {
+		"dev": "vite",
+		"build": "tsc && vite build",
+		"lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+		"preview": "vite preview"
+	},
+	"dependencies": {
+		"@automerge/react": "^2.0.0",
+		"@emotion/react": "11.14.0",
+		"@emotion/styled": "11.14.1",
+		"@hashintel/design-system": "0.0.9-canary.2",
+		"@hashintel/petrinaut": "0.0.4",
+		"@mui/material": "5.18.0",
+		"react": "18.3.1",
+		"react-dom": "18.3.1",
+		"react-use": "17.6.0",
+		"vite-plugin-wasm": "3.3.0"
+	},
+	"devDependencies": {
+		"@types/react": "18.3.12",
+		"@types/react-dom": "18.3.1",
+		"@vitejs/plugin-react": "4.3.3",
+		"eslint": "8.45.0",
+		"eslint-plugin-react-hooks": "4.6.0",
+		"eslint-plugin-react-refresh": "0.4.3",
+		"typescript": "5.2",
+		"typescript-eslint": "7.3.1",
+		"vite": "5"
+	},
+	"packageManager": "[email protected]+sha256.c17d3797fb9a9115bf375e31bfd30058cac6bc9c3b8807a3d8cb2094794b51ca"
+}

pocs/petrinaut-automerge/package.json

@@ -0,0 +1,5 @@
+html,
+body,
+#root {
+  height: 100%;
+}

pocs/petrinaut-automerge/public/hash.svg

@@ -0,0 +1,59 @@
+import React, { Suspense } from "react";
+import ReactDOM from "react-dom/client";
+import {
+	Repo,
+	BroadcastChannelNetworkAdapter,
+	WebSocketClientAdapter,
+	IndexedDBStorageAdapter,
+	RepoContext,
+	type DocHandle,
+} from "@automerge/react";
+import { CssBaseline, ThemeProvider } from "@mui/material";
+import { CacheProvider } from "@emotion/react";
+import { createEmotionCache, theme } from "@hashintel/design-system/theme";
+
+import App from "./main/app.tsx";
+import "./index.css";
+
+import { getOrCreateRoot, type RootDocument } from "./rootDoc.ts";
+
+const repo = new Repo({
+	network: [
+		new BroadcastChannelNetworkAdapter(),
+		new WebSocketClientAdapter("wss://sync.automerge.org"),
+	],
+	storage: new IndexedDBStorageAdapter(),
+});
+
+// Add the repo to the global window object so it can be accessed in the browser console
+// This is useful for debugging and testing purposes.
+declare global {
+	interface Window {
+		repo: Repo;
+		// We also add the handle to the global window object for debugging
+		handle: DocHandle<RootDocument>;
+	}
+}
+window.repo = repo;
+
+const emotionCache = createEmotionCache();
+
+// Depending if we have an AutomergeUrl, either find or create the document
+const rootDocUrl = getOrCreateRoot(repo);
+window.handle = await repo.find(rootDocUrl);
+
+// biome-ignore lint/style/noNonNullAssertion: we know it exists
+ReactDOM.createRoot(document.getElementById("root")!).render(
+	<React.StrictMode>
+		<Suspense fallback={<div>Suspense fallback...</div>}>
+			<RepoContext.Provider value={repo}>
+				<CacheProvider value={emotionCache}>
+					<ThemeProvider theme={theme}>
+						<CssBaseline />
+						<App rootDocUrl={window.handle.url} />
+					</ThemeProvider>
+				</CacheProvider>
+			</RepoContext.Provider>
+		</Suspense>
+	</React.StrictMode>,
+);

pocs/petrinaut-automerge/src/index.css

@@ -0,0 +1,97 @@
+import {
+	isValidAutomergeUrl,
+	useDocument,
+	useRepo,
+	type AutomergeUrl,
+} from "@automerge/react";
+import { useHash } from "react-use";
+import type { RootDocument } from "../rootDoc";
+import { useCallback, useMemo, useState } from "react";
+import { type PetriNet, PetrinautWrapper } from "./app/petrinaut-wrapper";
+import { defaultTokenTypes } from "@hashintel/petrinaut";
+
+const createDefaultPetriNet = (): PetriNet => ({
+	petriNetDefinition: {
+		arcs: [],
+		nodes: [],
+		tokenTypes: JSON.parse(JSON.stringify(defaultTokenTypes)),
+	},
+	title: "New Petri Net",
+});
+
+function App({ rootDocUrl }: { rootDocUrl: AutomergeUrl }) {
+	const [hash, setHash] = useHash();
+	const cleanHash = hash.slice(1); // Remove the leading '#'
+	const selectedDocUrl =
+		cleanHash && isValidAutomergeUrl(cleanHash)
+			? (cleanHash as AutomergeUrl)
+			: undefined;
+
+	const [hasAddedFirstNet, setHasAddedFirstNet] = useState(false);
+
+	const repo = useRepo();
+
+	console.log("Before useDocument in app.tsx, rootDocUrl", rootDocUrl);
+
+	const [rootDoc, changeRootDoc] = useDocument<RootDocument>(rootDocUrl, {
+		suspense: true,
+	});
+
+	console.log("loaded rootDoc in app.tsx", rootDoc);
+
+	const petriNetUrls = useMemo(() => {
+		return rootDoc?.petriNetUrls ?? [];
+	}, [rootDoc]);
+
+	const createAndSelectPetriNet = useCallback(
+		(petriNet: PetriNet | null) => {
+			const newPetriNet = repo.create<PetriNet>(
+				petriNet ?? createDefaultPetriNet(),
+			);
+
+			changeRootDoc((rootDoc) => {
+				rootDoc.petriNetUrls.push(newPetriNet.url);
+			});
+
+			setHash(newPetriNet.url);
+		},
+		[repo, changeRootDoc, setHash],
+	);
+
+	if (!selectedDocUrl) {
+		console.log("No selected doc url");
+		const firstOption = petriNetUrls[0];
+
+		if (firstOption) {
+			console.log("Setting hash to first option", firstOption);
+			setHash(firstOption);
+		} else if (!hasAddedFirstNet) {
+			console.log("Creating new petri net");
+			createAndSelectPetriNet(null);
+			setHasAddedFirstNet(true);
+		}
+		return null;
+	}
+
+	console.log("Before useDocument in app.tsx, selectedDocUrl", selectedDocUrl);
+
+	const [selectedPetriNetDoc, changeSelectedPetriNetDoc] =
+		useDocument<PetriNet>(selectedDocUrl, { suspense: true });
+
+	console.log("loaded selectedPetriNetDoc in app.tsx", selectedPetriNetDoc);
+
+	return (
+		<PetrinautWrapper
+			changePetriNetDoc={changeSelectedPetriNetDoc}
+			createAndSelectPetriNet={createAndSelectPetriNet}
+			loadPetriNetFromUrl={(url) => {
+				setHash(url);
+			}}
+			rootDoc={rootDoc}
+			selectedPetriNetUrl={selectedDocUrl}
+			selectedPetriNetDoc={selectedPetriNetDoc}
+		/>
+	);
+}
+
+export default App;