@automerge/automerge-repo-react-hooks 0.2.1 → 1.0.0-alpha.2

package/README.md

@@ -1,5 +1,28 @@
 # React Hooks for Automerge Repo
 
+These hooks are provided as helpers for using Automerge in your React project.
+
+#### [useBootstrap](./src/useBootstrap.ts)
+This hook is used to load a document based on the URL hash, for example `//myapp/#documentId=[document ID]`.
+It can also load the document ID from localStorage, or create a new document if none is specified.
+
+#### [useLocalAwareness](./src/useLocalAwareness.ts) & [useRemoteAwareness](./src/useRemoteAwareness.ts)
+These hooks implement ephemeral awareness/presence, similar to [Yjs Awareness](https://docs.yjs.dev/getting-started/adding-awareness).
+They allow temporary state to be shared, such as cursor positions or peer online/offline status. 
+
+Ephemeral messages are replicated between peers, but not saved to the Automerge doc, and are used for temporary updates that will be discarded.
+
+#### [useRepo/RepoContext](./src/useRepo.ts)
+Use RepoContext to set up react context for an Automerge repo.
+Use useRepo to lookup the repo from context.
+Most hooks depend on RepoContext being available.
+
+#### [useDocument](./src/useDocument.ts)
+Return a document & updater fn, by ID.
+
+#### [useHandle](./src/useHandle.ts)
+Return a handle, by ID.
+
 ## Example usage
 
 ### App Setup

package/dist/index.d.ts

@@ -2,4 +2,6 @@ export { useDocument } from "./useDocument.js";
 export { useBootstrap } from './useBootstrap.js';
 export { useHandle } from "./useHandle.js";
 export { RepoContext, useRepo } from "./useRepo.js";
+export { useLocalAwareness } from './useLocalAwareness.js';
+export { useRemoteAwareness } from './useRemoteAwareness.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -2,3 +2,5 @@ export { useDocument } from "./useDocument.js";
 export { useBootstrap } from './useBootstrap.js';
 export { useHandle } from "./useHandle.js";
 export { RepoContext, useRepo } from "./useRepo.js";
+export { useLocalAwareness } from './useLocalAwareness.js';
+export { useRemoteAwareness } from './useRemoteAwareness.js';

package/dist/useBootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useBootstrap.d.ts","sourceRoot":"","sources":["../src/useBootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAc,IAAI,EAAE,MAAM,2BAA2B,CAAA;AAKvE,eAAO,MAAM,OAAO,SAAU,MAAM,8BAUnC,CAAA;AAGD,eAAO,MAAM,OAAO,cAQnB,CAAA;AAwBD;;;;;;;;;;;;;;;;GAgBG;AACH,UAAU,mBAAmB,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAA;IAC3C,mBAAmB,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;CAC7D;AAED,eAAO,MAAM,YAAY,2FAgCxB,CAAA"}
+{"version":3,"file":"useBootstrap.d.ts","sourceRoot":"","sources":["../src/useBootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,IAAI,EAGL,MAAM,2BAA2B,CAAA;AAKlC,eAAO,MAAM,OAAO,SAAU,MAAM,8BAUnC,CAAA;AAGD,eAAO,MAAM,OAAO,cAQnB,CAAA;AAwBD;;;;;;;;;;;;;;;;GAgBG;AACH,UAAU,mBAAmB,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAA;IAC3C,mBAAmB,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;CAC7D;AAED,eAAO,MAAM,YAAY,2FAgCxB,CAAA"}

package/dist/useBootstrap.js

@@ -1,3 +1,4 @@
+import { generateAutomergeUrl, } from "@automerge/automerge-repo";
 import { useEffect, useState, useMemo } from "react";
 import { useRepo } from "./useRepo.js";
 // Set URL hash
@@ -42,15 +43,15 @@ export const useBootstrap = ({ key = "documentId", onNoDocument = repo => repo.c
     const hash = useHash();
     // Try to get existing document; else create a new one
     const handle = useMemo(() => {
-        const existingDocumentId = getDocumentId(key, hash);
+        const documentId = getDocumentId(key, hash);
         try {
-            return existingDocumentId
-                ? repo.find(existingDocumentId)
+            return documentId
+                ? repo.find(generateAutomergeUrl({ documentId }))
                 : onNoDocument(repo);
         }
         catch (error) {
             // Presumably the documentId was invalid
-            if (existingDocumentId && onInvalidDocumentId)
+            if (documentId && onInvalidDocumentId)
                 return onInvalidDocumentId(repo, error);
             // Forward other errors
             throw error;

package/dist/useDocument.d.ts

@@ -1,4 +1,4 @@
-import { Doc, ChangeFn } from "@automerge/automerge";
-import { DocumentId } from "@automerge/automerge-repo";
-export declare function useDocument<T>(documentId?: DocumentId): [Doc<T>, (changeFn: ChangeFn<T>) => void];
+import { ChangeFn, Doc } from "@automerge/automerge";
+import { AutomergeUrl } from "@automerge/automerge-repo";
+export declare function useDocument<T>(documentUrl?: AutomergeUrl): [Doc<T>, (changeFn: ChangeFn<T>) => void];
 //# sourceMappingURL=useDocument.d.ts.map

package/dist/useDocument.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDocument.d.ts","sourceRoot":"","sources":["../src/useDocument.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAiB,MAAM,sBAAsB,CAAA;AACnE,OAAO,EAAE,UAAU,EAAyB,MAAM,2BAA2B,CAAA;AAI7E,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,UAAU,uBAyBL,SAAS,CAAC,CAAC,KAAK,IAAI,EACpE"}
+{"version":3,"file":"useDocument.d.ts","sourceRoot":"","sources":["../src/useDocument.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAiB,GAAG,EAAE,MAAM,sBAAsB,CAAA;AACnE,OAAO,EAAE,YAAY,EAA0B,MAAM,2BAA2B,CAAA;AAIhF,wBAAgB,WAAW,CAAC,CAAC,EAAE,WAAW,CAAC,EAAE,YAAY,uBA4BR,SAAS,CAAC,CAAC,KAAK,IAAI,EACpE"}

package/dist/useDocument.js

@@ -1,17 +1,17 @@
 import { useEffect, useState } from "react";
 import { useRepo } from "./useRepo";
-export function useDocument(documentId) {
+export function useDocument(documentUrl) {
     const [doc, setDoc] = useState();
     const repo = useRepo();
-    const handle = documentId ? repo.find(documentId) : null;
+    const handle = documentUrl ? repo.find(documentUrl) : null;
     useEffect(() => {
         if (!handle)
             return;
-        handle.value().then(v => setDoc(v));
-        const onPatch = (h) => setDoc(h.patchInfo.after);
-        handle.on("patch", onPatch);
+        handle.doc().then(v => setDoc(v));
+        const onChange = (h) => setDoc(h.doc);
+        handle.on("change", onChange);
         const cleanup = () => {
-            handle.removeListener("patch", onPatch);
+            handle.removeListener("change", onChange);
         };
         return cleanup;
     }, [handle]);

package/dist/useHandle.d.ts

@@ -1,3 +1,3 @@
-import { DocHandle, DocumentId } from "@automerge/automerge-repo";
-export declare function useHandle<T>(documentId: DocumentId): DocHandle<T>;
+import { AutomergeUrl, DocHandle } from "@automerge/automerge-repo";
+export declare function useHandle<T>(automergeUrl: AutomergeUrl): DocHandle<T>;
 //# sourceMappingURL=useHandle.d.ts.map

package/dist/useHandle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useHandle.d.ts","sourceRoot":"","sources":["../src/useHandle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAIjE,wBAAgB,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,CAIjE"}
+{"version":3,"file":"useHandle.d.ts","sourceRoot":"","sources":["../src/useHandle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAInE,wBAAgB,SAAS,CAAC,CAAC,EAAE,YAAY,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC,CAAC,CAIrE"}

package/dist/useHandle.js

@@ -1,7 +1,7 @@
 import { useState } from "react";
 import { useRepo } from "./useRepo.js";
-export function useHandle(documentId) {
+export function useHandle(automergeUrl) {
     const repo = useRepo();
-    const [handle] = useState(repo.find(documentId));
+    const [handle] = useState(repo.find(automergeUrl));
     return handle;
 }

package/dist/useLocalAwareness.d.ts

@@ -0,0 +1,24 @@
+/**
+ * This hook maintains state for the local client.
+ * Like React.useState, it returns a [state, setState] array.
+ * It is intended to be used alongside useRemoteAwareness.
+ *
+ * When state is changed it is broadcast to all clients.
+ * It also broadcasts a heartbeat to let other clients know it is online.
+ *
+ * Note that userIds aren't secure (yet). Any client can lie about theirs.
+ * ChannelID is usually just your documentID with some extra characters.
+ *
+ * @param {string} props.userId Unique user ID. Clients can lie about this.
+ * @param {string} props.channelId Which channel to send messages on. This *must* be unique.
+ * @param {any} props.initialState Initial state object/primitive
+ * @param {number?1500} props.heartbeatTime How often to send a heartbeat (in ms)
+ * @returns [state, setState]
+ */
+export declare const useLocalAwareness: ({ userId, channelId: channelIdUnprefixed, initialState, heartbeatTime }?: {
+    userId: any;
+    channelId: any;
+    initialState: any;
+    heartbeatTime?: number;
+}) => any[];
+//# sourceMappingURL=useLocalAwareness.d.ts.map

package/dist/useLocalAwareness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLocalAwareness.d.ts","sourceRoot":"","sources":["../src/useLocalAwareness.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB;;;;;WAyD7B,CAAC"}

package/dist/useLocalAwareness.js

@@ -0,0 +1,66 @@
+// @ts-nocheck
+import { useRepo } from "./useRepo";
+import { useEffect } from "react";
+import useStateRef from "react-usestateref";
+import { peerEvents, CHANNEL_ID_PREFIX } from "./useRemoteAwareness";
+/**
+ * This hook maintains state for the local client.
+ * Like React.useState, it returns a [state, setState] array.
+ * It is intended to be used alongside useRemoteAwareness.
+ *
+ * When state is changed it is broadcast to all clients.
+ * It also broadcasts a heartbeat to let other clients know it is online.
+ *
+ * Note that userIds aren't secure (yet). Any client can lie about theirs.
+ * ChannelID is usually just your documentID with some extra characters.
+ *
+ * @param {string} props.userId Unique user ID. Clients can lie about this.
+ * @param {string} props.channelId Which channel to send messages on. This *must* be unique.
+ * @param {any} props.initialState Initial state object/primitive
+ * @param {number?1500} props.heartbeatTime How often to send a heartbeat (in ms)
+ * @returns [state, setState]
+ */
+export const useLocalAwareness = ({ userId, channelId: channelIdUnprefixed, initialState, heartbeatTime = 15000 } = {}) => {
+    const channelId = CHANNEL_ID_PREFIX + channelIdUnprefixed;
+    const [localState, setLocalState, localStateRef] = useStateRef(initialState);
+    const { ephemeralData } = useRepo();
+    const setState = (stateOrUpdater) => {
+        const state = typeof stateOrUpdater === "function"
+            ? stateOrUpdater(localStateRef.current)
+            : stateOrUpdater;
+        setLocalState(state);
+        // TODO: Send deltas instead of entire state
+        ephemeralData.broadcast(channelId, [userId, state]);
+    };
+    useEffect(() => {
+        // Send periodic heartbeats
+        const heartbeat = () => void ephemeralData.broadcast(channelId, [userId, localStateRef.current]);
+        heartbeat(); // Initial heartbeat
+        // TODO: we don't need to send a heartbeat if we've changed state recently; use recursive setTimeout instead of setInterval
+        const heartbeatIntervalId = setInterval(heartbeat, heartbeatTime);
+        return () => void clearInterval(heartbeatIntervalId);
+    }, [userId, channelId, heartbeatTime, ephemeralData]);
+    useEffect(() => {
+        // Send entire state to new peers
+        let broadcastTimeoutId;
+        const newPeerEvents = peerEvents.on("new_peer", (e) => {
+            if (e.channelId !== channelId)
+                return;
+            broadcastTimeoutId = setTimeout(() => void ephemeralData.broadcast(channelId, [
+                userId,
+                localStateRef.current,
+            ]), 500 // Wait for the peer to be ready
+            );
+        });
+        return () => {
+            newPeerEvents.off();
+            broadcastTimeoutId && clearTimeout(broadcastTimeoutId);
+        };
+    }, [userId, channelId, peerEvents]);
+    // TODO: Send an "offline" message on unmount
+    // useEffect(
+    //   () => () => void ephemeralData.broadcast(channelId, null), // Same as Yjs awareness
+    //   []
+    // );
+    return [localState, setState];
+};

package/dist/useRemoteAwareness.d.ts

@@ -0,0 +1,22 @@
+import EventEmitter from "eventemitter3";
+export declare const CHANNEL_ID_PREFIX = "aw\n";
+export declare const peerEvents: EventEmitter<string | symbol, any>;
+/**
+ *
+ * This hook returns read-only state for remote clients.
+ * It also returns their heartbeat status.
+ * It is intended to be used alongside useLocalAwareness.
+ *
+ * @param {string} props.channelId Which channel to send messages on. This *must* be unique.
+ * @param {string?} props.localUserId Automerge BroadcastChannel sometimes sends us our own messages; optionally filters them
+ * @param {number?30000} props.offlineTimeout How long to wait (in ms) before marking a peer as offline
+ * @param {function?} props.getTime Function to provide current epoch time (used for testing)
+ * @returns [ peerStates: { [userId]: state, ... }, { [userId]: heartbeatEpochTime, ...} ]
+ */
+export declare const useRemoteAwareness: ({ channelId: channelIdUnprefixed, localUserId, offlineTimeout, getTime, }?: {
+    channelId: any;
+    localUserId: any;
+    offlineTimeout?: number;
+    getTime?: () => number;
+}) => {}[];
+//# sourceMappingURL=useRemoteAwareness.d.ts.map

package/dist/useRemoteAwareness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRemoteAwareness.d.ts","sourceRoot":"","sources":["../src/useRemoteAwareness.ts"],"names":[],"mappings":"AAIA,OAAO,YAAY,MAAM,eAAe,CAAC;AAGzC,eAAO,MAAM,iBAAiB,SAAS,CAAC;AAGxC,eAAO,MAAM,UAAU,oCAAqB,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB;;;;;UA0D9B,CAAC"}

package/dist/useRemoteAwareness.js

@@ -0,0 +1,76 @@
+// @ts-nocheck
+import { useRepo } from "./useRepo";
+import { useEffect } from "react";
+import useStateRef from "react-usestateref";
+import EventEmitter from "eventemitter3";
+// Add this to the beginning of every channel ID to help prevent collisions
+export const CHANNEL_ID_PREFIX = "aw\n";
+// Emits new_peer event when a new peer is seen
+export const peerEvents = new EventEmitter();
+/**
+ *
+ * This hook returns read-only state for remote clients.
+ * It also returns their heartbeat status.
+ * It is intended to be used alongside useLocalAwareness.
+ *
+ * @param {string} props.channelId Which channel to send messages on. This *must* be unique.
+ * @param {string?} props.localUserId Automerge BroadcastChannel sometimes sends us our own messages; optionally filters them
+ * @param {number?30000} props.offlineTimeout How long to wait (in ms) before marking a peer as offline
+ * @param {function?} props.getTime Function to provide current epoch time (used for testing)
+ * @returns [ peerStates: { [userId]: state, ... }, { [userId]: heartbeatEpochTime, ...} ]
+ */
+export const useRemoteAwareness = ({ channelId: channelIdUnprefixed, localUserId, offlineTimeout = 30000, getTime = () => new Date().getTime(), } = {}) => {
+    // TODO: You should be able to use multiple instances of this hook on the same channelID (write test)
+    // TODO: This should support some kind of caching or memoization when switching between channelIDs
+    const channelId = CHANNEL_ID_PREFIX + channelIdUnprefixed;
+    const [peerStates, setPeerStates, peerStatesRef] = useStateRef({});
+    const [heartbeats, setHeartbeats, heartbeatsRef] = useStateRef({});
+    const { ephemeralData } = useRepo(); // EphemeralData API lets us send messages to peers on the automerge document
+    useEffect(() => {
+        // Receive incoming message
+        const handleIncomingUpdate = (event) => {
+            try {
+                if (event.channelId !== channelId)
+                    return;
+                const [userId, state] = event.data;
+                if (userId === localUserId)
+                    return;
+                if (!heartbeatsRef.current[userId])
+                    peerEvents.emit("new_peer", event); // Let useLocalAwareness know we've seen a new peer
+                setPeerStates({
+                    ...peerStatesRef.current,
+                    [userId]: state,
+                });
+                setHeartbeats({
+                    ...heartbeatsRef.current,
+                    [userId]: getTime(),
+                });
+            }
+            catch (e) {
+                return;
+            }
+        };
+        // Remove peers we haven't seen recently
+        const pruneOfflinePeers = () => {
+            const peerStates = peerStatesRef.current;
+            const heartbeats = heartbeatsRef.current;
+            const time = getTime();
+            for (const key in heartbeats) {
+                if (time - heartbeats[key] > offlineTimeout) {
+                    delete peerStates[key];
+                    delete heartbeats[key];
+                }
+            }
+            setPeerStates(peerStates);
+            setHeartbeats(heartbeats);
+        };
+        ephemeralData.on("data", handleIncomingUpdate);
+        // Check for offline peers every `offlineTimeout` ms
+        const pruneOfflinePeersIntervalId = setInterval(pruneOfflinePeers, offlineTimeout);
+        return () => {
+            ephemeralData.removeListener("data", handleIncomingUpdate);
+            clearInterval(pruneOfflinePeersIntervalId);
+        };
+    }, [channelId, localUserId, offlineTimeout, getTime, ephemeralData]);
+    return [peerStates, heartbeats];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo-react-hooks",
-  "version": "0.2.1",
+  "version": "1.0.0-alpha.2",
   "description": "Hooks to access an Automerge Repo from your react app.",
   "repository": "https://github.com/automerge/automerge-repo",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
@@ -10,10 +10,27 @@
   "main": "dist/index.js",
   "scripts": {
     "build": "tsc",
+    "test": "vitest run",
     "watch": "npm-watch"
   },
+  "peerDependencies": {
+    "@automerge/automerge": "^2.1.0-alpha.10"
+  },
   "dependencies": {
-    "@automerge/automerge-repo": "^0.2.1"
+    "@automerge/automerge-repo": "^1.0.0-alpha.2",
+    "eventemitter3": "^5.0.0",
+    "react": "^18.2.0",
+    "react-usestateref": "^1.0.8"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^14.0.0",
+    "@vitejs/plugin-react": "^4.0.2",
+    "jsdom": "^22.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "vite-plugin-top-level-await": "^1.3.1",
+    "vite-plugin-wasm": "^3.2.2",
+    "vitest": "^0.33.0"
   },
   "watch": {
     "build": {
@@ -26,5 +43,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7f048ecaa62eb1246f54773c6b10bada0767497b"
+  "gitHead": "b5830dde8f135b694809698aaad2a9fdc79a9898"
 }

package/src/index.ts

@@ -2,3 +2,5 @@ export { useDocument } from "./useDocument.js"
 export { useBootstrap } from './useBootstrap.js'
 export { useHandle } from "./useHandle.js"
 export { RepoContext, useRepo } from "./useRepo.js"
+export { useLocalAwareness } from './useLocalAwareness.js'
+export { useRemoteAwareness } from './useRemoteAwareness.js'

package/src/useBootstrap.ts

@@ -1,4 +1,9 @@
-import { DocHandle, DocumentId, Repo } from "@automerge/automerge-repo"
+import {
+  DocHandle,
+  Repo,
+  type DocumentId,
+  generateAutomergeUrl,
+} from "@automerge/automerge-repo"
 import { useEffect, useState, useMemo } from "react"
 import { useRepo } from "./useRepo.js"
 
@@ -27,7 +32,7 @@ export const useHash = () => {
 }
 
 // Get a key from a query-param-style URL hash
-const getQueryParamValue = (key: string, hash) =>
+const getQueryParamValue = (key: string, hash: string) =>
   new URLSearchParams(hash.substr(1)).get(key)
 
 const setQueryParamValue = (key: string, value, hash): string => {
@@ -36,10 +41,10 @@ const setQueryParamValue = (key: string, value, hash): string => {
   return u.toString()
 }
 
-const getDocumentId = (key, hash) =>
+const getDocumentId = (key: string, hash: string) =>
   key && (getQueryParamValue(key, hash) || localStorage.getItem(key))
 
-const setDocumentId = (key, documentId) => {
+const setDocumentId = (key: string, documentId: DocumentId) => {
   if (key) {
     // Only set URL hash if document ID changed
     if (documentId !== getQueryParamValue(key, window.location.hash))
@@ -81,14 +86,14 @@ export const useBootstrap = <T>({
 
   // Try to get existing document; else create a new one
   const handle = useMemo((): DocHandle<T> => {
-    const existingDocumentId = getDocumentId(key, hash)
+    const documentId = getDocumentId(key, hash) as DocumentId | undefined
     try {
-      return existingDocumentId
-        ? repo.find(existingDocumentId as DocumentId)
+      return documentId
+        ? repo.find(generateAutomergeUrl({ documentId }))
         : onNoDocument(repo)
     } catch (error) {
       // Presumably the documentId was invalid
-      if (existingDocumentId && onInvalidDocumentId)
+      if (documentId && onInvalidDocumentId)
         return onInvalidDocumentId(repo, error)
       // Forward other errors
       throw error

package/src/useDocument.ts

@@ -1,29 +1,32 @@
-import { Doc, ChangeFn, ChangeOptions } from "@automerge/automerge"
-import { DocumentId, DocHandlePatchPayload } from "@automerge/automerge-repo"
+import { ChangeFn, ChangeOptions, Doc } from "@automerge/automerge"
+import { AutomergeUrl, DocHandleChangePayload } from "@automerge/automerge-repo"
 import { useEffect, useState } from "react"
 import { useRepo } from "./useRepo"
 
-export function useDocument<T>(documentId?: DocumentId) {
+export function useDocument<T>(documentUrl?: AutomergeUrl) {
   const [doc, setDoc] = useState<Doc<T>>()
   const repo = useRepo()
 
-  const handle = documentId ? repo.find<T>(documentId) : null
+  const handle = documentUrl ? repo.find<T>(documentUrl) : null
 
   useEffect(() => {
     if (!handle) return
 
-    handle.value().then(v => setDoc(v))
+    handle.doc().then(v => setDoc(v))
 
-    const onPatch = (h: DocHandlePatchPayload<T>) => setDoc(h.patchInfo.after)
-    handle.on("patch", onPatch)
+    const onChange = (h: DocHandleChangePayload<T>) => setDoc(h.doc)
+    handle.on("change", onChange)
     const cleanup = () => {
-      handle.removeListener("patch", onPatch)
+      handle.removeListener("change", onChange)
     }
 
     return cleanup
   }, [handle])
 
-  const changeDoc = (changeFn: ChangeFn<T>, options?: ChangeOptions<T> | undefined) => {
+  const changeDoc = (
+    changeFn: ChangeFn<T>,
+    options?: ChangeOptions<T> | undefined
+  ) => {
     if (!handle) return
     handle.change(changeFn, options)
   }

package/src/useHandle.ts

@@ -1,9 +1,9 @@
-import { DocHandle, DocumentId } from "@automerge/automerge-repo"
+import { AutomergeUrl, DocHandle } from "@automerge/automerge-repo"
 import { useState } from "react"
 import { useRepo } from "./useRepo.js"
 
-export function useHandle<T>(documentId: DocumentId): DocHandle<T> {
+export function useHandle<T>(automergeUrl: AutomergeUrl): DocHandle<T> {
   const repo = useRepo()
-  const [handle] = useState<DocHandle<T>>(repo.find(documentId))
+  const [handle] = useState<DocHandle<T>>(repo.find(automergeUrl))
   return handle
 }

package/src/useLocalAwareness.ts

@@ -0,0 +1,81 @@
+// @ts-nocheck
+import { useRepo } from "./useRepo";
+import { useEffect } from "react";
+import useStateRef from "react-usestateref";
+import { peerEvents, CHANNEL_ID_PREFIX } from "./useRemoteAwareness";
+
+/**
+ * This hook maintains state for the local client.
+ * Like React.useState, it returns a [state, setState] array.
+ * It is intended to be used alongside useRemoteAwareness.
+ *
+ * When state is changed it is broadcast to all clients.
+ * It also broadcasts a heartbeat to let other clients know it is online.
+ *
+ * Note that userIds aren't secure (yet). Any client can lie about theirs.
+ * ChannelID is usually just your documentID with some extra characters.
+ *
+ * @param {string} props.userId Unique user ID. Clients can lie about this.
+ * @param {string} props.channelId Which channel to send messages on. This *must* be unique.
+ * @param {any} props.initialState Initial state object/primitive
+ * @param {number?1500} props.heartbeatTime How often to send a heartbeat (in ms)
+ * @returns [state, setState]
+ */
+export const useLocalAwareness = ({
+  userId,
+  channelId: channelIdUnprefixed,
+  initialState,
+  heartbeatTime = 15000
+} = {}) => {
+  const channelId = CHANNEL_ID_PREFIX + channelIdUnprefixed;
+  const [localState, setLocalState, localStateRef] = useStateRef(initialState);
+  const { ephemeralData } = useRepo();
+
+  const setState = (stateOrUpdater) => {
+    const state =
+      typeof stateOrUpdater === "function"
+        ? stateOrUpdater(localStateRef.current)
+        : stateOrUpdater;
+    setLocalState(state);
+    // TODO: Send deltas instead of entire state
+    ephemeralData.broadcast(channelId, [userId, state]);
+  };
+
+  useEffect(() => {
+    // Send periodic heartbeats
+    const heartbeat = () =>
+      void ephemeralData.broadcast(channelId, [userId, localStateRef.current]);
+    heartbeat(); // Initial heartbeat
+    // TODO: we don't need to send a heartbeat if we've changed state recently; use recursive setTimeout instead of setInterval
+    const heartbeatIntervalId = setInterval(heartbeat, heartbeatTime);
+    return () => void clearInterval(heartbeatIntervalId);
+  }, [userId, channelId, heartbeatTime, ephemeralData]);
+
+  useEffect(() => {
+    // Send entire state to new peers
+    let broadcastTimeoutId;
+    const newPeerEvents = peerEvents.on("new_peer", (e) => {
+      if (e.channelId !== channelId) return;
+      broadcastTimeoutId = setTimeout(
+        () =>
+          void ephemeralData.broadcast(channelId, [
+            userId,
+            localStateRef.current,
+          ]),
+        500 // Wait for the peer to be ready
+      );
+    });
+    return () => {
+      newPeerEvents.off();
+      broadcastTimeoutId && clearTimeout(broadcastTimeoutId);
+    };
+  }, [userId, channelId, peerEvents]);
+
+  // TODO: Send an "offline" message on unmount
+  // useEffect(
+  //   () => () => void ephemeralData.broadcast(channelId, null), // Same as Yjs awareness
+  //   []
+  // );
+
+  return [localState, setState];
+};