@automerge/automerge-repo-react-hooks 1.0.2 → 1.0.4

package/dist/index.d.ts

@@ -1,7 +1,93 @@
+/**
+ * @packageDocumentation
+ *
+ * # React Hooks for Automerge Repo
+ *
+ * These hooks are provided as helpers for using Automerge in your React project.
+ *
+ * #### {@link useBootstrap}
+ * 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.
+ *
+ * #### {@link useLocalAwareness} & {@link useRemoteAwareness}
+ * 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.
+ *
+ * #### {@link useRepo}/{@link RepoContext}
+ * 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.
+ *
+ * #### {@link useDocument }
+ * Return a document & updater fn, by ID.
+ *
+ * #### {@link useHandle }
+ * Return a handle, by ID.
+ *
+ * ## Example usage
+ *
+ * ### App Setup
+ *
+ * ```ts
+ * import React, { StrictMode } from "react"
+ * import ReactDOM from "react-dom/client"
+ *
+ * import { Repo, DocCollection } from "@automerge/automerge-repo"
+ *
+ * import { BroadcastChannelNetworkAdapter } from "@automerge/automerge-repo-network-broadcastchannel"
+ *
+ * import App, { RootDocument } from "./App.js"
+ * import { RepoContext } from "@automerge/automerge-repo-react-hooks"
+ *
+ * // eslint-disable-next-line @typescript-eslint/no-unused-vars
+ * const sharedWorker = new SharedWorker(
+ *   new URL("./shared-worker.js", import.meta.url),
+ *   { type: "module", name: "@automerge/automerge-repo-shared-worker" }
+ * )
+ *
+ * async function getRepo(): Promise<DocCollection> {
+ *   return await Repo({
+ *     network: [
+ *       new BroadcastChannelNetworkAdapter(),
+ *     ],
+ *     sharePolicy: peerId => peerId.includes("shared-worker"),
+ *   })
+ * }
+ *
+ * const initFunction = (d: RootDocument) => {
+ *   d.items = []
+ * }
+ *
+ * const queryString = window.location.search // Returns:'?q=123'
+ *
+ * // Further parsing:
+ * const params = new URLSearchParams(queryString)
+ * const hostname = params.get("host") || "automerge-storage-demo.glitch.me"
+ *
+ * getRepo().then(repo => {
+ *   useBootstrap(repo, initFunction).then(rootDoc => {
+ *     const rootElem = document.getElementById("root")
+ *     if (!rootElem) {
+ *       throw new Error("The 'root' element wasn't found in the host HTML doc.")
+ *     }
+ *     const root = ReactDOM.createRoot(rootElem)
+ *     root.render(
+ *       <StrictMode>
+ *         <RepoContext.Provider value={repo}>
+ *           <App rootDocumentId={rootDoc.documentId} />
+ *         </RepoContext.Provider>
+ *       </StrictMode>
+ *     )
+ *   })
+ * })
+ * ```
+ */
 export { useDocument } from "./useDocument.js";
-export { useBootstrap } from './useBootstrap.js';
+export { useBootstrap, type UseBootstrapOptions } from './useBootstrap.js';
 export { useHandle } from "./useHandle.js";
 export { RepoContext, useRepo } from "./useRepo.js";
-export { useLocalAwareness } from './useLocalAwareness.js';
-export { useRemoteAwareness } from './useRemoteAwareness.js';
+export { useLocalAwareness, type UseLocalAwarenessProps } from './useLocalAwareness.js';
+export { useRemoteAwareness, type PeerStates, type Heartbeats, type UseRemoteAwarenessProps } 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;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAC1E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AACvF,OAAO,EAAE,kBAAkB,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,uBAAuB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -1,3 +1,89 @@
+/**
+ * @packageDocumentation
+ *
+ * # React Hooks for Automerge Repo
+ *
+ * These hooks are provided as helpers for using Automerge in your React project.
+ *
+ * #### {@link useBootstrap}
+ * 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.
+ *
+ * #### {@link useLocalAwareness} & {@link useRemoteAwareness}
+ * 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.
+ *
+ * #### {@link useRepo}/{@link RepoContext}
+ * 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.
+ *
+ * #### {@link useDocument }
+ * Return a document & updater fn, by ID.
+ *
+ * #### {@link useHandle }
+ * Return a handle, by ID.
+ *
+ * ## Example usage
+ *
+ * ### App Setup
+ *
+ * ```ts
+ * import React, { StrictMode } from "react"
+ * import ReactDOM from "react-dom/client"
+ *
+ * import { Repo, DocCollection } from "@automerge/automerge-repo"
+ *
+ * import { BroadcastChannelNetworkAdapter } from "@automerge/automerge-repo-network-broadcastchannel"
+ *
+ * import App, { RootDocument } from "./App.js"
+ * import { RepoContext } from "@automerge/automerge-repo-react-hooks"
+ *
+ * // eslint-disable-next-line @typescript-eslint/no-unused-vars
+ * const sharedWorker = new SharedWorker(
+ *   new URL("./shared-worker.js", import.meta.url),
+ *   { type: "module", name: "@automerge/automerge-repo-shared-worker" }
+ * )
+ *
+ * async function getRepo(): Promise<DocCollection> {
+ *   return await Repo({
+ *     network: [
+ *       new BroadcastChannelNetworkAdapter(),
+ *     ],
+ *     sharePolicy: peerId => peerId.includes("shared-worker"),
+ *   })
+ * }
+ *
+ * const initFunction = (d: RootDocument) => {
+ *   d.items = []
+ * }
+ *
+ * const queryString = window.location.search // Returns:'?q=123'
+ *
+ * // Further parsing:
+ * const params = new URLSearchParams(queryString)
+ * const hostname = params.get("host") || "automerge-storage-demo.glitch.me"
+ *
+ * getRepo().then(repo => {
+ *   useBootstrap(repo, initFunction).then(rootDoc => {
+ *     const rootElem = document.getElementById("root")
+ *     if (!rootElem) {
+ *       throw new Error("The 'root' element wasn't found in the host HTML doc.")
+ *     }
+ *     const root = ReactDOM.createRoot(rootElem)
+ *     root.render(
+ *       <StrictMode>
+ *         <RepoContext.Provider value={repo}>
+ *           <App rootDocumentId={rootDoc.documentId} />
+ *         </RepoContext.Provider>
+ *       </StrictMode>
+ *     )
+ *   })
+ * })
+ * ```
+ */
 export { useDocument } from "./useDocument.js";
 export { useBootstrap } from './useBootstrap.js';
 export { useHandle } from "./useHandle.js";

package/dist/useBootstrap.d.ts

@@ -1,28 +1,30 @@
 import { DocHandle, Repo } from "@automerge/automerge-repo";
 export declare const setHash: (hash: string, pushState?: boolean) => void;
 export declare const useHash: () => string;
+export interface UseBootstrapOptions<T> {
+    /** Key to use for the URL hash and localStorage */
+    key?: string;
+    /** Function returning a document handle called if lookup fails. Defaults to repo.create() */
+    onNoDocument?: (repo: Repo) => DocHandle<T>;
+    /** Function to call if automerge URL is invalid */
+    onInvalidAutomergeUrl?(repo: Repo, error: Error): DocHandle<T>;
+}
 /**
  * This hook is used to set up a single document as the base of an app session.
  * This is a common pattern for simple multiplayer apps with shareable URLs.
  *
- * It will first check for the document ID in the URL hash:
- *   //myapp/#documentId=[document ID]
- * Failing that, it will check for a `documentId` key in localStorage.
+ * It will first check for the automergeUrl in the URL hash:
+ *   //myapp/#automergeUrl=[document URL]
+ * Failing that, it will check for a `automergeUrl` key in localStorage.
  * Failing that, it will call onNoDocument, expecting a handle to be returned.
  *
  * The URL and localStorage will then be updated.
- * Finally, it will return the document ID.
+ * Finally, it will return the Automerge document's URL.
  *
  * @param {string?} props.key Key to use for the URL hash and localStorage
  * @param {function?} props.fallback Function returning a document handle called if lookup fails. Defaults to repo.create()
- * @param {function?} props.onInvalidDocumentId Function to call if documentId is invalid; signature (error) => (repo, onCreate)
+ * @param {function?} props.onInvalidAutomergeUrl Function to call if URL is invalid; signature (error) => (repo, onCreate)
  * @returns {DocHandle} The document handle
  */
-interface UseBootstrapOptions<T> {
-    key?: string;
-    onNoDocument?: (repo: Repo) => DocHandle<T>;
-    onInvalidDocumentId?(repo: Repo, error: Error): DocHandle<T>;
-}
-export declare const useBootstrap: <T>({ key, onNoDocument, onInvalidDocumentId, }?: UseBootstrapOptions<T>) => DocHandle<T>;
-export {};
+export declare const useBootstrap: <T>({ key, onNoDocument, onInvalidAutomergeUrl, }?: UseBootstrapOptions<T>) => DocHandle<T>;
 //# sourceMappingURL=useBootstrap.d.ts.map

package/dist/useBootstrap.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"useBootstrap.d.ts","sourceRoot":"","sources":["../src/useBootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAqB,MAAM,2BAA2B,CAAA;AAK9E,eAAO,MAAM,OAAO,SAAU,MAAM,8BAUnC,CAAA;AAGD,eAAO,MAAM,OAAO,cAQnB,CAAA;AAwBD,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,6FAA6F;IAC7F,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAA;IAC3C,mDAAmD;IACnD,qBAAqB,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;CAC/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,6FA8BxB,CAAA"}

package/dist/useBootstrap.js

@@ -1,4 +1,3 @@
-import { generateAutomergeUrl, } from "@automerge/automerge-repo";
 import { useEffect, useState, useMemo } from "react";
 import { useRepo } from "./useRepo.js";
 // Set URL hash
@@ -28,39 +27,54 @@ const setQueryParamValue = (key, value, hash) => {
     u.set(key, value);
     return u.toString();
 };
-const getDocumentId = (key, hash) => key && (getQueryParamValue(key, hash) || localStorage.getItem(key));
-const setDocumentId = (key, documentId) => {
+const getAutomergeUrl = (key, hash) => key && (getQueryParamValue(key, hash) || localStorage.getItem(key));
+const setAutomergeUrl = (key, automergeUrl) => {
     if (key) {
-        // Only set URL hash if document ID changed
-        if (documentId !== getQueryParamValue(key, window.location.hash))
-            setHash(setQueryParamValue(key, documentId, window.location.hash));
+        // Only set URL hash if automerge URL changed
+        if (automergeUrl !== getQueryParamValue(key, window.location.hash))
+            setHash(setQueryParamValue(key, automergeUrl, window.location.hash));
     }
     if (key)
-        localStorage.setItem(key, documentId);
+        localStorage.setItem(key, automergeUrl);
 };
-export const useBootstrap = ({ key = "documentId", onNoDocument = repo => repo.create(), onInvalidDocumentId, } = {}) => {
+/**
+ * This hook is used to set up a single document as the base of an app session.
+ * This is a common pattern for simple multiplayer apps with shareable URLs.
+ *
+ * It will first check for the automergeUrl in the URL hash:
+ *   //myapp/#automergeUrl=[document URL]
+ * Failing that, it will check for a `automergeUrl` key in localStorage.
+ * Failing that, it will call onNoDocument, expecting a handle to be returned.
+ *
+ * The URL and localStorage will then be updated.
+ * Finally, it will return the Automerge document's URL.
+ *
+ * @param {string?} props.key Key to use for the URL hash and localStorage
+ * @param {function?} props.fallback Function returning a document handle called if lookup fails. Defaults to repo.create()
+ * @param {function?} props.onInvalidAutomergeUrl Function to call if URL is invalid; signature (error) => (repo, onCreate)
+ * @returns {DocHandle} The document handle
+ */
+export const useBootstrap = ({ key = "automergeUrl", onNoDocument = repo => repo.create(), onInvalidAutomergeUrl, } = {}) => {
     const repo = useRepo();
     const hash = useHash();
     // Try to get existing document; else create a new one
     const handle = useMemo(() => {
-        const documentId = getDocumentId(key, hash);
+        const url = getAutomergeUrl(key, hash);
         try {
-            return documentId
-                ? repo.find(generateAutomergeUrl({ documentId }))
-                : onNoDocument(repo);
+            return url ? repo.find(url) : onNoDocument(repo);
         }
         catch (error) {
-            // Presumably the documentId was invalid
-            if (documentId && onInvalidDocumentId)
-                return onInvalidDocumentId(repo, error);
+            // Presumably the URL was invalid
+            if (url && onInvalidAutomergeUrl)
+                return onInvalidAutomergeUrl(repo, error);
             // Forward other errors
             throw error;
         }
-    }, [hash, repo, onNoDocument, onInvalidDocumentId]);
+    }, [hash, repo, onNoDocument, onInvalidAutomergeUrl]);
     // Update hashroute & localStorage on changes
     useEffect(() => {
         if (handle) {
-            setDocumentId(key, handle.documentId);
+            setAutomergeUrl(key, handle.url);
         }
     }, [hash, handle]);
     return handle;

package/dist/useDocument.d.ts

@@ -1,4 +1,12 @@
 import { ChangeFn, Doc } from "@automerge/automerge/next";
 import { AutomergeUrl } from "@automerge/automerge-repo";
-export declare function useDocument<T>(documentUrl?: AutomergeUrl): [Doc<T>, (changeFn: ChangeFn<T>) => void];
+/** A hook which returns a document identified by a URL and a function to change the document.
+ *
+ * @returns a tuple of the document and a function to change the document.
+ * The document will be `undefined` if the document is not available in storage or from any peers
+ *
+ * @remarks
+ * This requires a {@link RepoContext} to be provided by a parent component.
+ * */
+export declare function useDocument<T>(documentUrl?: AutomergeUrl): [Doc<T> | undefined, (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,QAAQ,EAAiB,GAAG,EAAE,MAAM,2BAA2B,CAAA;AACxE,OAAO,EAAE,YAAY,EAA0B,MAAM,2BAA2B,CAAA;AAIhF,wBAAgB,WAAW,CAAC,CAAC,EAAE,WAAW,CAAC,EAAE,YAAY,uBA4BR,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,2BAA2B,CAAA;AACxE,OAAO,EAAE,YAAY,EAA0B,MAAM,2BAA2B,CAAA;AAIhF;;;;;;;KAOK;AACL,wBAAgB,WAAW,CAAC,CAAC,EAAE,WAAW,CAAC,EAAE,YAAY,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CA6BhH"}

package/dist/useDocument.js

@@ -1,5 +1,13 @@
 import { useEffect, useState } from "react";
 import { useRepo } from "./useRepo.js";
+/** A hook which returns a document identified by a URL and a function to change the document.
+ *
+ * @returns a tuple of the document and a function to change the document.
+ * The document will be `undefined` if the document is not available in storage or from any peers
+ *
+ * @remarks
+ * This requires a {@link RepoContext} to be provided by a parent component.
+ * */
 export function useDocument(documentUrl) {
     const [doc, setDoc] = useState();
     const repo = useRepo();

package/dist/useHandle.d.ts

@@ -1,3 +1,8 @@
 import { AutomergeUrl, DocHandle } from "@automerge/automerge-repo";
+/** A hook which returns a {@link DocHandle} identified by a URL.
+ *
+ * @remarks
+ * This requires a {@link RepoContext} to be provided by a parent component.
+ */
 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,YAAY,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAInE,wBAAgB,SAAS,CAAC,CAAC,EAAE,YAAY,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC,CAAC,CAIrE"}
+{"version":3,"file":"useHandle.d.ts","sourceRoot":"","sources":["../src/useHandle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAInE;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,YAAY,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC,CAAC,CAIrE"}

package/dist/useHandle.js

@@ -1,5 +1,10 @@
 import { useState } from "react";
 import { useRepo } from "./useRepo.js";
+/** A hook which returns a {@link DocHandle} identified by a URL.
+ *
+ * @remarks
+ * This requires a {@link RepoContext} to be provided by a parent component.
+ */
 export function useHandle(automergeUrl) {
     const repo = useRepo();
     const [handle] = useState(repo.find(automergeUrl));

package/dist/useLocalAwareness.d.ts

@@ -1,4 +1,14 @@
 import { DocHandle } from "@automerge/automerge-repo";
+export interface UseLocalAwarenessProps {
+    /** The document handle to send ephemeral state on */
+    handle: DocHandle<unknown>;
+    /** Our user ID **/
+    userId: string;
+    /** The initial state object/primitive we should advertise */
+    initialState: any;
+    /** How frequently to send heartbeats */
+    heartbeatTime?: number;
+}
 /**
  * This hook maintains state for the local client.
  * Like React.useState, it returns a [state, setState] array.
@@ -8,18 +18,11 @@ import { DocHandle } from "@automerge/automerge-repo";
  * 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 {any} props.initialState Initial state object/primitive
  * @param {number?1500} props.heartbeatTime How often to send a heartbeat (in ms)
  * @returns [state, setState]
  */
-export interface UseLocalAwarenessProps {
-    handle: DocHandle<unknown>;
-    userId: string;
-    initialState: any;
-    heartbeatTime?: number;
-}
 export declare const useLocalAwareness: ({ handle, userId, initialState, heartbeatTime, }: UseLocalAwarenessProps) => any[];
 //# sourceMappingURL=useLocalAwareness.d.ts.map

package/dist/useLocalAwareness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLocalAwareness.d.ts","sourceRoot":"","sources":["../src/useLocalAwareness.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAErD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,GAAG,CAAA;IACjB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AACD,eAAO,MAAM,iBAAiB,qDAK3B,sBAAsB,UA6CxB,CAAA"}
+{"version":3,"file":"useLocalAwareness.d.ts","sourceRoot":"","sources":["../src/useLocalAwareness.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAErD,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IAC1B,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,6DAA6D;IAC7D,YAAY,EAAE,GAAG,CAAA;IACjB,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AACD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,qDAK3B,sBAAsB,UA6CxB,CAAA"}

package/dist/useLocalAwareness.js

@@ -1,6 +1,21 @@
 import { useEffect } from "react";
 import useStateRef from "react-usestateref";
 import { peerEvents } from "./useRemoteAwareness.js";
+/**
+ * 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.
+ *
+ * @param {string} props.userId Unique user ID. Clients can lie about this.
+ * @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 = ({ handle, userId, initialState, heartbeatTime = 15000, }) => {
     const [localState, setLocalState, localStateRef] = useStateRef(initialState);
     const setState = stateOrUpdater => {

package/dist/useRemoteAwareness.d.ts

@@ -1,6 +1,20 @@
 import { DocHandle } from "@automerge/automerge-repo";
 import { EventEmitter } from "eventemitter3";
 export declare const peerEvents: EventEmitter<string | symbol, any>;
+export interface UseRemoteAwarenessProps {
+    /** The handle to receive ephemeral state on */
+    handle: DocHandle<unknown>;
+    /** Our user ID */
+    localUserId?: string;
+    /** How long to wait (in ms) before marking a peer as offline */
+    offlineTimeout?: number;
+    /** Function to provide current epoch time */
+    getTime?: () => number;
+}
+/** A map from peer ID to their state */
+export type PeerStates = Record<string, any>;
+/** A map from peer ID to their last heartbeat timestamp */
+export type Heartbeats = Record<string, number>;
 /**
  *
  * This hook returns read-only state for remote clients.
@@ -13,13 +27,5 @@ export declare const peerEvents: EventEmitter<string | symbol, any>;
  * @param {function?} props.getTime Function to provide current epoch time (used for testing)
  * @returns [ peerStates: { [userId]: state, ... }, { [userId]: heartbeatEpochTime, ...} ]
  */
-export interface UseRemoteAwarenessProps {
-    handle: DocHandle<unknown>;
-    localUserId?: string;
-    offlineTimeout?: number;
-    getTime?: () => number;
-}
-export type PeerStates = Record<string, any>;
-export type Heartbeats = Record<string, number>;
 export declare const useRemoteAwareness: ({ handle, localUserId, offlineTimeout, getTime, }: UseRemoteAwarenessProps) => [PeerStates, Heartbeats];
 //# sourceMappingURL=useRemoteAwareness.d.ts.map

package/dist/useRemoteAwareness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useRemoteAwareness.d.ts","sourceRoot":"","sources":["../src/useRemoteAwareness.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAGrD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAG5C,eAAO,MAAM,UAAU,oCAAqB,CAAA;AAE5C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,MAAM,CAAA;CACvB;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAC5C,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAE/C,eAAO,MAAM,kBAAkB,sDAK5B,uBAAuB,KAAG,CAAC,UAAU,EAAE,UAAU,CA+CnD,CAAA"}
+{"version":3,"file":"useRemoteAwareness.d.ts","sourceRoot":"","sources":["../src/useRemoteAwareness.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAGrD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAG5C,eAAO,MAAM,UAAU,oCAAqB,CAAA;AAE5C,MAAM,WAAW,uBAAuB;IACtC,+CAA+C;IAC/C,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IAC1B,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,MAAM,CAAA;CACvB;AAED,wCAAwC;AACxC,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAC5C,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAE/C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,sDAK5B,uBAAuB,KAAG,CAAC,UAAU,EAAE,UAAU,CA+CnD,CAAA"}

package/dist/useRemoteAwareness.js

@@ -3,6 +3,18 @@ import useStateRef from "react-usestateref";
 import { EventEmitter } from "eventemitter3";
 // 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.handle A document handle to associate with
+ * @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 = ({ handle, localUserId, offlineTimeout = 30000, getTime = () => new Date().getTime(), }) => {
     // TODO: You should be able to use multiple instances of this hook on the same handle (write test)
     // TODO: This should support some kind of caching or memoization when switching between channelIDs

package/dist/useRepo.d.ts

@@ -1,5 +1,7 @@
 /// <reference types="react" />
 import { Repo } from "@automerge/automerge-repo";
+/** A [React context](https://react.dev/learn/passing-data-deeply-with-context) which provides access to an Automerge repo. */
 export declare const RepoContext: import("react").Context<Repo>;
+/** A [React hook](https://reactjs.org/docs/hooks-intro.html) which returns the Automerge repo from {@link RepoContext}. */
 export declare function useRepo(): Repo;
 //# sourceMappingURL=useRepo.d.ts.map

package/dist/useRepo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useRepo.d.ts","sourceRoot":"","sources":["../src/useRepo.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAA;AAGhD,eAAO,MAAM,WAAW,+BAAmC,CAAA;AAE3D,wBAAgB,OAAO,IAAI,IAAI,CAI9B"}
+{"version":3,"file":"useRepo.d.ts","sourceRoot":"","sources":["../src/useRepo.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAA;AAGhD,8HAA8H;AAC9H,eAAO,MAAM,WAAW,+BAAmC,CAAA;AAE3D,2HAA2H;AAC3H,wBAAgB,OAAO,IAAI,IAAI,CAI9B"}

package/dist/useRepo.js

@@ -1,5 +1,7 @@
 import { createContext, useContext } from "react";
+/** A [React context](https://react.dev/learn/passing-data-deeply-with-context) which provides access to an Automerge repo. */
 export const RepoContext = createContext(null);
+/** A [React hook](https://reactjs.org/docs/hooks-intro.html) which returns the Automerge repo from {@link RepoContext}. */
 export function useRepo() {
     const repo = useContext(RepoContext);
     if (!repo)

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@automerge/automerge-repo-react-hooks",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Hooks to access an Automerge Repo from your react app.",
-  "repository": "https://github.com/automerge/automerge-repo",
+  "repository": "https://github.com/automerge/automerge-repo/tree/master/packages/automerge-repo-react-hooks",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
   "license": "MIT",
-  "private": false,
   "type": "module",
   "main": "dist/index.js",
   "scripts": {
@@ -17,18 +16,18 @@
     "@automerge/automerge": "^2.1.0"
   },
   "dependencies": {
-    "@automerge/automerge-repo": "^1.0.2",
-    "eventemitter3": "^5.0.0",
+    "@automerge/automerge-repo": "^1.0.4",
+    "eventemitter3": "^5.0.1",
     "react": "^18.2.0",
     "react-usestateref": "^1.0.8"
   },
   "devDependencies": {
+    "@automerge/automerge": "^2.1.0",
     "@testing-library/react": "^14.0.0",
-    "@vitejs/plugin-react": "^4.0.2",
+    "@vitejs/plugin-react": "^3.0.0",
     "jsdom": "^22.1.0",
-    "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "vite-plugin-top-level-await": "^1.3.1",
+    "vite-plugin-top-level-await": "^1.3.0",
     "vite-plugin-wasm": "^3.2.2",
     "vitest": "^0.33.0"
   },
@@ -43,5 +42,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "c72b9ec33c3a1f7f39ad20cb4fa0d766afe42158"
+  "gitHead": "17fd5260f9af3e65da636fef084e8c04d6c4bed0"
 }

package/src/index.ts

@@ -1,6 +1,92 @@
+/**
+ * @packageDocumentation
+ *
+ * # React Hooks for Automerge Repo
+ * 
+ * These hooks are provided as helpers for using Automerge in your React project.
+ * 
+ * #### {@link useBootstrap}
+ * 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.
+ * 
+ * #### {@link useLocalAwareness} & {@link useRemoteAwareness}
+ * 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.
+ * 
+ * #### {@link useRepo}/{@link RepoContext}
+ * 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.
+ * 
+ * #### {@link useDocument }
+ * Return a document & updater fn, by ID.
+ * 
+ * #### {@link useHandle }
+ * Return a handle, by ID.
+ * 
+ * ## Example usage
+ * 
+ * ### App Setup
+ * 
+ * ```ts
+ * import React, { StrictMode } from "react"
+ * import ReactDOM from "react-dom/client"
+ * 
+ * import { Repo, DocCollection } from "@automerge/automerge-repo"
+ * 
+ * import { BroadcastChannelNetworkAdapter } from "@automerge/automerge-repo-network-broadcastchannel"
+ * 
+ * import App, { RootDocument } from "./App.js"
+ * import { RepoContext } from "@automerge/automerge-repo-react-hooks"
+ * 
+ * // eslint-disable-next-line @typescript-eslint/no-unused-vars
+ * const sharedWorker = new SharedWorker(
+ *   new URL("./shared-worker.js", import.meta.url),
+ *   { type: "module", name: "@automerge/automerge-repo-shared-worker" }
+ * )
+ * 
+ * async function getRepo(): Promise<DocCollection> {
+ *   return await Repo({
+ *     network: [
+ *       new BroadcastChannelNetworkAdapter(),
+ *     ],
+ *     sharePolicy: peerId => peerId.includes("shared-worker"),
+ *   })
+ * }
+ * 
+ * const initFunction = (d: RootDocument) => {
+ *   d.items = []
+ * }
+ * 
+ * const queryString = window.location.search // Returns:'?q=123'
+ * 
+ * // Further parsing:
+ * const params = new URLSearchParams(queryString)
+ * const hostname = params.get("host") || "automerge-storage-demo.glitch.me"
+ * 
+ * getRepo().then(repo => {
+ *   useBootstrap(repo, initFunction).then(rootDoc => {
+ *     const rootElem = document.getElementById("root")
+ *     if (!rootElem) {
+ *       throw new Error("The 'root' element wasn't found in the host HTML doc.")
+ *     }
+ *     const root = ReactDOM.createRoot(rootElem)
+ *     root.render(
+ *       <StrictMode>
+ *         <RepoContext.Provider value={repo}>
+ *           <App rootDocumentId={rootDoc.documentId} />
+ *         </RepoContext.Provider>
+ *       </StrictMode>
+ *     )
+ *   })
+ * })
+ * ```
+ */
 export { useDocument } from "./useDocument.js"
-export { useBootstrap } from './useBootstrap.js'
+export { useBootstrap, type UseBootstrapOptions } from './useBootstrap.js'
 export { useHandle } from "./useHandle.js"
 export { RepoContext, useRepo } from "./useRepo.js"
-export { useLocalAwareness } from './useLocalAwareness.js'
-export { useRemoteAwareness } from './useRemoteAwareness.js'
+export { useLocalAwareness, type UseLocalAwarenessProps } from './useLocalAwareness.js'
+export { useRemoteAwareness, type PeerStates, type Heartbeats, type UseRemoteAwarenessProps } from './useRemoteAwareness.js'

package/src/useBootstrap.ts

@@ -1,9 +1,4 @@
-import {
-  DocHandle,
-  Repo,
-  type DocumentId,
-  generateAutomergeUrl,
-} from "@automerge/automerge-repo"
+import { DocHandle, Repo, type AutomergeUrl } from "@automerge/automerge-repo"
 import { useEffect, useState, useMemo } from "react"
 import { useRepo } from "./useRepo.js"
 
@@ -41,69 +36,70 @@ const setQueryParamValue = (key: string, value, hash): string => {
   return u.toString()
 }
 
-const getDocumentId = (key: string, hash: string) =>
+const getAutomergeUrl = (key: string, hash: string) =>
   key && (getQueryParamValue(key, hash) || localStorage.getItem(key))
 
-const setDocumentId = (key: string, documentId: DocumentId) => {
+const setAutomergeUrl = (key: string, automergeUrl: AutomergeUrl) => {
   if (key) {
-    // Only set URL hash if document ID changed
-    if (documentId !== getQueryParamValue(key, window.location.hash))
-      setHash(setQueryParamValue(key, documentId, window.location.hash))
+    // Only set URL hash if automerge URL changed
+    if (automergeUrl !== getQueryParamValue(key, window.location.hash))
+      setHash(setQueryParamValue(key, automergeUrl, window.location.hash))
   }
-  if (key) localStorage.setItem(key, documentId)
+  if (key) localStorage.setItem(key, automergeUrl)
+}
+
+export interface UseBootstrapOptions<T> {
+  /** Key to use for the URL hash and localStorage */
+  key?: string
+  /** Function returning a document handle called if lookup fails. Defaults to repo.create() */
+  onNoDocument?: (repo: Repo) => DocHandle<T>
+  /** Function to call if automerge URL is invalid */
+  onInvalidAutomergeUrl?(repo: Repo, error: Error): DocHandle<T>
 }
 
 /**
  * This hook is used to set up a single document as the base of an app session.
  * This is a common pattern for simple multiplayer apps with shareable URLs.
  *
- * It will first check for the document ID in the URL hash:
- *   //myapp/#documentId=[document ID]
- * Failing that, it will check for a `documentId` key in localStorage.
+ * It will first check for the automergeUrl in the URL hash:
+ *   //myapp/#automergeUrl=[document URL]
+ * Failing that, it will check for a `automergeUrl` key in localStorage.
  * Failing that, it will call onNoDocument, expecting a handle to be returned.
  *
  * The URL and localStorage will then be updated.
- * Finally, it will return the document ID.
+ * Finally, it will return the Automerge document's URL.
  *
  * @param {string?} props.key Key to use for the URL hash and localStorage
  * @param {function?} props.fallback Function returning a document handle called if lookup fails. Defaults to repo.create()
- * @param {function?} props.onInvalidDocumentId Function to call if documentId is invalid; signature (error) => (repo, onCreate)
+ * @param {function?} props.onInvalidAutomergeUrl Function to call if URL is invalid; signature (error) => (repo, onCreate)
  * @returns {DocHandle} The document handle
  */
-interface UseBootstrapOptions<T> {
-  key?: string
-  onNoDocument?: (repo: Repo) => DocHandle<T>
-  onInvalidDocumentId?(repo: Repo, error: Error): DocHandle<T>
-}
-
 export const useBootstrap = <T>({
-  key = "documentId",
+  key = "automergeUrl",
   onNoDocument = repo => repo.create(),
-  onInvalidDocumentId,
+  onInvalidAutomergeUrl,
 }: UseBootstrapOptions<T> = {}): DocHandle<T> => {
   const repo = useRepo()
   const hash = useHash()
 
   // Try to get existing document; else create a new one
   const handle = useMemo((): DocHandle<T> => {
-    const documentId = getDocumentId(key, hash) as DocumentId | undefined
+    const url = getAutomergeUrl(key, hash) as AutomergeUrl | undefined
     try {
-      return documentId
-        ? repo.find(generateAutomergeUrl({ documentId }))
-        : onNoDocument(repo)
+      return url ? repo.find(url) : onNoDocument(repo)
     } catch (error) {
-      // Presumably the documentId was invalid
-      if (documentId && onInvalidDocumentId)
-        return onInvalidDocumentId(repo, error)
+      // Presumably the URL was invalid
+      if (url && onInvalidAutomergeUrl)
+        return onInvalidAutomergeUrl(repo, error)
       // Forward other errors
       throw error
     }
-  }, [hash, repo, onNoDocument, onInvalidDocumentId])
+  }, [hash, repo, onNoDocument, onInvalidAutomergeUrl])
 
   // Update hashroute & localStorage on changes
   useEffect(() => {
     if (handle) {
-      setDocumentId(key, handle.documentId)
+      setAutomergeUrl(key, handle.url)
     }
   }, [hash, handle])
 

package/src/useDocument.ts

@@ -3,7 +3,15 @@ import { AutomergeUrl, DocHandleChangePayload } from "@automerge/automerge-repo"
 import { useEffect, useState } from "react"
 import { useRepo } from "./useRepo.js"
 
-export function useDocument<T>(documentUrl?: AutomergeUrl) {
+/** A hook which returns a document identified by a URL and a function to change the document. 
+ *
+ * @returns a tuple of the document and a function to change the document.
+ * The document will be `undefined` if the document is not available in storage or from any peers
+ * 
+ * @remarks
+ * This requires a {@link RepoContext} to be provided by a parent component. 
+ * */
+export function useDocument<T>(documentUrl?: AutomergeUrl): [Doc<T> | undefined, (changeFn: ChangeFn<T>) => void] {
   const [doc, setDoc] = useState<Doc<T>>()
   const repo = useRepo()
 
@@ -31,5 +39,5 @@ export function useDocument<T>(documentUrl?: AutomergeUrl) {
     handle.change(changeFn, options)
   }
 
-  return [doc, changeDoc] as [Doc<T>, (changeFn: ChangeFn<T>) => void]
+  return [doc, changeDoc]
 }

package/src/useHandle.ts

@@ -2,6 +2,11 @@ import { AutomergeUrl, DocHandle } from "@automerge/automerge-repo"
 import { useState } from "react"
 import { useRepo } from "./useRepo.js"
 
+/** A hook which returns a {@link DocHandle} identified by a URL.
+ *
+ * @remarks
+ * This requires a {@link RepoContext} to be provided by a parent component.
+ */
 export function useHandle<T>(automergeUrl: AutomergeUrl): DocHandle<T> {
   const repo = useRepo()
   const [handle] = useState<DocHandle<T>>(repo.find(automergeUrl))

package/src/useLocalAwareness.ts

@@ -3,6 +3,16 @@ import useStateRef from "react-usestateref"
 import { peerEvents } from "./useRemoteAwareness.js"
 import { DocHandle } from "@automerge/automerge-repo"
 
+export interface UseLocalAwarenessProps {
+  /** The document handle to send ephemeral state on */
+  handle: DocHandle<unknown>
+  /** Our user ID **/
+  userId: string
+  /** The initial state object/primitive we should advertise */
+  initialState: any
+  /** How frequently to send heartbeats */
+  heartbeatTime?: number
+}
 /**
  * This hook maintains state for the local client.
  * Like React.useState, it returns a [state, setState] array.
@@ -12,19 +22,12 @@ import { DocHandle } from "@automerge/automerge-repo"
  * 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 {any} props.initialState Initial state object/primitive
  * @param {number?1500} props.heartbeatTime How often to send a heartbeat (in ms)
  * @returns [state, setState]
  */
-export interface UseLocalAwarenessProps {
-  handle: DocHandle<unknown>
-  userId: string
-  initialState: any
-  heartbeatTime?: number
-}
 export const useLocalAwareness = ({
   handle,
   userId,

package/src/useRemoteAwareness.ts

@@ -6,6 +6,22 @@ import { EventEmitter } from "eventemitter3"
 // Emits new_peer event when a new peer is seen
 export const peerEvents = new EventEmitter()
 
+export interface UseRemoteAwarenessProps {
+  /** The handle to receive ephemeral state on */
+  handle: DocHandle<unknown>
+  /** Our user ID */
+  localUserId?: string
+  /** How long to wait (in ms) before marking a peer as offline */
+  offlineTimeout?: number
+  /** Function to provide current epoch time */
+  getTime?: () => number
+}
+
+/** A map from peer ID to their state */
+export type PeerStates = Record<string, any>
+/** A map from peer ID to their last heartbeat timestamp */
+export type Heartbeats = Record<string, number>
+
 /**
  *
  * This hook returns read-only state for remote clients.
@@ -18,16 +34,6 @@ export const peerEvents = new EventEmitter()
  * @param {function?} props.getTime Function to provide current epoch time (used for testing)
  * @returns [ peerStates: { [userId]: state, ... }, { [userId]: heartbeatEpochTime, ...} ]
  */
-export interface UseRemoteAwarenessProps {
-  handle: DocHandle<unknown>
-  localUserId?: string
-  offlineTimeout?: number
-  getTime?: () => number
-}
-
-export type PeerStates = Record<string, any>
-export type Heartbeats = Record<string, number>
-
 export const useRemoteAwareness = ({
   handle,
   localUserId,

package/src/useRepo.ts

@@ -1,8 +1,10 @@
 import { Repo } from "@automerge/automerge-repo"
 import { createContext, useContext } from "react"
 
+/** A [React context](https://react.dev/learn/passing-data-deeply-with-context) which provides access to an Automerge repo. */
 export const RepoContext = createContext<Repo | null>(null)
 
+/** A [React hook](https://reactjs.org/docs/hooks-intro.html) which returns the Automerge repo from {@link RepoContext}. */
 export function useRepo(): Repo {
   const repo = useContext(RepoContext)
   if (!repo) throw new Error("Repo was not found on RepoContext.")

package/typedoc.json

@@ -0,0 +1,5 @@
+{
+    "extends": "../../typedoc.base.json",
+    "entryPoints": ["src/index.ts"],
+    "readme": "none"
+}