CRDT for documents (1/6): bring up Automerge-backed collaboration (prototype)

.gitignore

@@ -1,4 +1,5 @@
 bin/
+pkg/automerge/internal/reference/wasm/target/
 node_modules/
 .cache/
 .turbo

GNUmakefile

@@ -2,6 +2,7 @@ NPROC ?=	$(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _
 MAKEFLAGS := --jobs=$(NPROC)
 
 CAT ?=	cat
+CARGO ?=	cargo
 CP ?=	cp
 DOCKER ?=	docker
 GO ?=	go
@@ -13,12 +14,14 @@ NPM ?=	npm
 NPX ?=	npx
 OPENSSL ?=	openssl
 SED ?= sed
+SHA256SUM ?= sha256sum
 SYFT ?=	syft
 TAIL ?= tail
 ECHO ?= echo
 GOLINTCMD ?= golangci-lint
 SWIFTLINTCMD ?= swiftlint
 SWIFTCMD ?= swift
+RUST_TOOLCHAIN ?= 1.89.0
 SWIFT_ENROLL_UI ?= cmd/probo-agent/installer/macos/enroll-ui
 SWIFT_FORMAT_CONFIG ?= .swift-format
 SWIFTLINT_CONFIG ?= .swiftlint.yml
@@ -104,6 +107,9 @@ EMBEDDED= apps/console/dist/index.html \
 	apps/compliance-portal/dist/index.html \
 	@probo/emails
 
+AUTOMERGE_REFERENCE_DIR=	pkg/automerge/internal/reference
+AUTOMERGE_REFERENCE_WASM=	$(AUTOMERGE_REFERENCE_DIR)/reference.wasm
+
 PROBOD_BIN_EXTRA_DEPS=
 PROBOD_BIN=	bin/probod
 PROBOD_SRC=	cmd/probod/main.go
@@ -208,6 +214,11 @@ test-verbose: test ## Run tests with verbose output
 test-short: TEST_FLAGS+=-short
 test-short: test ## Run short tests only
 
+.PHONY: test-automerge-conformance
+test-automerge-conformance: ## Test Go binary compatibility with official Automerge JS
+	AUTOMERGE_JS_ORACLE=$(CURDIR)/packages/automerge-conformance/oracle.mjs \
+		$(GO_BASE) test -count=1 ./pkg/automerge
+
 .PHONY: coverage-report
 coverage-report: test ## Generate HTML coverage report
 	$(GO) tool cover -html=coverage.out -o coverage.html
@@ -414,6 +425,18 @@ pkg/server/api/complianceportal/v1/schema.graphql: pkg/server/api/complianceport
 .PHONY: generate
 generate: $(GENERATED)
 
+.PHONY: generate-automerge-reference
+generate-automerge-reference: ## Rebuild the embedded official Automerge WASM backend
+	cd $(AUTOMERGE_REFERENCE_DIR)/wasm && \
+		$(CARGO) +$(RUST_TOOLCHAIN) build --locked --release --target wasm32-wasip1
+	$(CP) $(AUTOMERGE_REFERENCE_DIR)/wasm/target/wasm32-wasip1/release/probo_automerge_reference.wasm $(AUTOMERGE_REFERENCE_WASM)
+	cd $(AUTOMERGE_REFERENCE_DIR) && $(SHA256SUM) reference.wasm > reference.wasm.sha256
+
+.PHONY: audit-automerge-reference
+audit-automerge-reference: ## Audit Automerge Rust advisories, licenses, bans, and sources
+	cd $(AUTOMERGE_REFERENCE_DIR)/wasm && \
+		$(CARGO) +$(RUST_TOOLCHAIN) deny check
+
 .PHONY: embed
 embed: $(EMBEDDED)
 

apps/console/package.json

@@ -10,6 +10,8 @@
     "preview": "vite preview"
   },
   "dependencies": {
+    "@automerge/automerge": "^3.4.0",
+    "@automerge/prosemirror": "^0.2.0",
     "@hookform/resolvers": "^5.7.1",
     "@phosphor-icons/react": "^2.1.10",
     "@probo/coredata": "^1.0.0",

apps/console/src/pages/organizations/documents/description/DocumentDescriptionPage.tsx

@@ -19,8 +19,13 @@
 // SOFTWARE.
 
 import { formatError } from "@probo/helpers";
-import { RichEditor, useToast } from "@probo/ui";
-import { useCallback, useState } from "react";
+import {
+  createRichEditorAutomergeDocument,
+  RichEditor,
+  supportsRichEditorCollaboration,
+  useToast,
+} from "@probo/ui";
+import { useCallback, useEffect, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { type PreloadedQuery, useMutation, usePreloadedQuery } from "react-relay";
 import { useOutletContext } from "react-router";
@@ -30,8 +35,20 @@ import { useDebounceCallback } from "usehooks-ts";
 import type { DocumentDescriptionPage_updateContentMutation } from "#/__generated__/core/DocumentDescriptionPage_updateContentMutation.graphql";
 import type { DocumentDescriptionPageQuery } from "#/__generated__/core/DocumentDescriptionPageQuery.graphql";
 
+import {
+  type AutomergeDocumentHandle,
+  connectAutomergeDocument,
+} from "./_lib/AutomergeDocumentHandle";
+
 const autoSaveIntervalMs = 1000;
 
+type CollaborationState = {
+  versionID: string;
+  handle?: AutomergeDocumentHandle;
+  failed?: boolean;
+  reconnecting?: boolean;
+};
+
 export const documentDescriptionPageQuery = graphql`
   query DocumentDescriptionPageQuery($documentId: ID! $versionId: ID! $versionSpecified: Boolean!) {
     # We use this on /documents/:documentId/versions/:versionId/description
@@ -158,6 +175,86 @@ export function DocumentDescriptionPage(props: {
     && document.canUpdate
     && document.status !== "ARCHIVED"
     && document.writeMode !== "GENERATED";
+  const collaborationSupported = canEdit
+    && supportsRichEditorCollaboration(currentVersion.content);
+  const [collaboration, setCollaboration] = useState<CollaborationState>();
+
+  useEffect(() => {
+    if (!collaborationSupported) return;
+
+    let cancelled = false;
+    let activeHandle: AutomergeDocumentHandle | undefined;
+
+    void connectAutomergeDocument(
+      currentVersion.id,
+      content => createRichEditorAutomergeDocument(content),
+      (connected) => {
+        if (cancelled) return;
+
+        setCollaboration({
+          versionID: currentVersion.id,
+          handle: activeHandle,
+          reconnecting: !connected,
+        });
+        if (!connected) {
+          toast({
+            title: t("documentDescriptionPage.errors.title"),
+            description: t("documentDescriptionPage.errors.save"),
+            variant: "error",
+          });
+        }
+      },
+    ).then((handle) => {
+      if (cancelled) {
+        handle.close();
+        return;
+      }
+
+      activeHandle = handle;
+      setCollaboration({
+        versionID: currentVersion.id,
+        handle,
+      });
+    }).catch((error) => {
+      if (cancelled) return;
+
+      setCollaboration({
+        versionID: currentVersion.id,
+        failed: true,
+      });
+      toast({
+        title: t("documentDescriptionPage.errors.title"),
+        description: error instanceof Error
+          ? error.message
+          : t("documentDescriptionPage.errors.save"),
+        variant: "error",
+      });
+    });
+
+    return () => {
+      cancelled = true;
+      activeHandle?.close();
+    };
+  }, [
+    collaborationSupported,
+    currentVersion.id,
+    t,
+    toast,
+  ]);
+
+  const collaborationConnecting = collaborationSupported
+    && (
+      collaboration?.versionID !== currentVersion.id
+      || (!collaboration?.handle && !collaboration?.failed)
+    );
+  const collaborationHandle = collaborationSupported
+    && collaboration?.versionID === currentVersion.id
+    && !collaboration.failed
+    ? collaboration.handle
+    : undefined;
+  const collaborationReconnecting = collaborationSupported
+    && collaboration?.versionID === currentVersion.id
+    && collaboration.reconnecting;
 
   // The editor key must change on explicit actions (delete draft, edit
   // title/type) but NOT on auto-save side effects (cursor preservation).
@@ -199,7 +296,8 @@ export function DocumentDescriptionPage(props: {
       className="flex-1"
       content={currentVersion.content}
       data-theme="document"
-      disabled={!canEdit}
+      disabled={!canEdit || collaborationConnecting || collaborationReconnecting}
+      collaborationHandle={collaborationHandle}
       onChangeContent={handleUpdate}
     />
   );