@tangle-network/ui 11.5.0 → 11.7.0

package/src/editor/editor-lazy.test.tsx

@@ -0,0 +1,102 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { Component, type ReactNode, Suspense } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { retryableLazyEditor } from "./editor-lazy";
+import { MissingEditorPeersError } from "./editor-peers";
+
+/** Catches the rejection the lazy component throws, and can mount it again. */
+class ResettableBoundary extends Component<
+  { children: ReactNode },
+  { failure: Error | null }
+> {
+  state = { failure: null as Error | null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { failure: error };
+  }
+
+  render() {
+    if (this.state.failure) {
+      return (
+        <button type="button" onClick={() => this.setState({ failure: null })}>
+          failed: {this.state.failure.message}
+        </button>
+      );
+    }
+    return this.props.children;
+  }
+}
+
+function Loaded() {
+  return <span>editor</span>;
+}
+
+/** React reports a caught render error on the console; the assertions read it. */
+let consoleError: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  consoleError.mockRestore();
+});
+
+function renderRetryable(load: () => Promise<typeof Loaded>) {
+  const lazyEditor = retryableLazyEditor(load);
+  function Host() {
+    const LazyEditor = lazyEditor();
+    return (
+      <Suspense fallback={<span>loading</span>}>
+        <LazyEditor />
+      </Suspense>
+    );
+  }
+  return render(
+    <ResettableBoundary>
+      <Host />
+    </ResettableBoundary>,
+  );
+}
+
+describe("retryableLazyEditor", () => {
+  it("re-attempts the load after a transient failure", async () => {
+    // `lazy` caches its first rejection for the life of the component, so one
+    // failed chunk fetch would otherwise hold the editor broken until a full
+    // page reload.
+    const load = vi
+      .fn<() => Promise<typeof Loaded>>()
+      .mockRejectedValueOnce(new Error("Failed to fetch dynamically imported module"))
+      .mockResolvedValue(Loaded);
+
+    renderRetryable(load);
+
+    const retry = await screen.findByRole("button");
+    expect(retry).toHaveTextContent("Failed to fetch dynamically imported module");
+    expect(load).toHaveBeenCalledTimes(1);
+
+    fireEvent.click(retry);
+
+    expect(await screen.findByText("editor")).toBeInTheDocument();
+    expect(load).toHaveBeenCalledTimes(2);
+  });
+
+  it("keeps a missing peer permanent, so a remount does not import it again", async () => {
+    // A package does not install itself mid-session. Retrying would only
+    // repeat the same failure and hide the install list behind a loop.
+    const load = vi
+      .fn<() => Promise<typeof Loaded>>()
+      .mockRejectedValue(new MissingEditorPeersError("Install @tiptap/react."));
+
+    renderRetryable(load);
+
+    const retry = await screen.findByRole("button");
+    expect(retry).toHaveTextContent("Install @tiptap/react.");
+    expect(load).toHaveBeenCalledTimes(1);
+
+    fireEvent.click(retry);
+
+    expect(await screen.findByRole("button")).toHaveTextContent("Install @tiptap/react.");
+    expect(load).toHaveBeenCalledTimes(1);
+  });
+});

package/src/editor/editor-lazy.ts

@@ -0,0 +1,40 @@
+import { type ComponentType, lazy, type LazyExoticComponent } from "react";
+import { isMissingEditorPeersError } from "./editor-peers";
+
+/**
+ * Builds a `lazy` editor component that a remount can re-attempt.
+ *
+ * `lazy` caches its first rejection for the life of the component. That is
+ * right for a missing peer, which stays missing for the session, and wrong for
+ * a transient chunk fetch: one failed network request would otherwise hold the
+ * editor broken until a full page reload.
+ *
+ * The returned function gives the component to render, and a caller must call
+ * it on every render: a transient failure replaces the component, and a caller
+ * that holds the one it got earlier keeps replaying the cached rejection.
+ *
+ * A `MissingEditorPeersError` keeps the cached rejection, so the install list
+ * reaches the consumer's error boundary once and the loader does not run
+ * again. Any other rejection replaces the component, so the next mount — an
+ * error boundary that resets, or a remount by the parent — starts a fresh
+ * attempt.
+ */
+export function retryableLazyEditor<P extends object>(
+  loadComponent: () => Promise<ComponentType<P>>,
+): () => LazyExoticComponent<ComponentType<P>> {
+  function build(): LazyExoticComponent<ComponentType<P>> {
+    return lazy(async () => {
+      try {
+        return { default: await loadComponent() };
+      } catch (error) {
+        if (!isMissingEditorPeersError(error)) {
+          current = build();
+        }
+        throw error;
+      }
+    });
+  }
+
+  let current = build();
+  return () => current;
+}

package/src/editor/editor-loading.tsx

@@ -0,0 +1,25 @@
+"use client";
+
+import { cn } from "../lib/utils";
+
+/**
+ * Stands in for an editor while its optional peers load. The editors reach
+ * tiptap through a dynamic import, so an editor's first frame waits for that
+ * chunk. The live region announces the wait, which a screen reader has no
+ * other way to notice. Callers put their own minimum height first, so a
+ * caller-supplied className still wins.
+ */
+export function EditorLoadingPlaceholder({ className }: { className?: string }) {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className={cn(
+        "flex w-full items-center justify-center rounded-lg border border-border border-dashed bg-muted text-muted-foreground text-sm",
+        className,
+      )}
+    >
+      Loading editor…
+    </div>
+  );
+}

package/src/editor/editor-peers.test.ts

@@ -0,0 +1,250 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  asMissingEditorPeersError,
+  isMissingEditorPeersError,
+  isMissingPeerError,
+} from "./editor-peers";
+
+/** The namespace shape each peer has when it is installed. */
+const installedPeers: Record<string, Record<string, unknown>> = {
+  "@tiptap/react": { useEditor: () => null, EditorContent: () => null },
+  "@tiptap/starter-kit": { default: { configure: () => ({}) } },
+  "@tiptap/extension-collaboration": { default: { configure: () => ({}) } },
+  "@tiptap/extension-collaboration-caret": { default: { configure: () => ({}) } },
+  "@hocuspocus/provider": { HocuspocusProvider: class {} },
+  yjs: { Doc: class {} },
+};
+
+/**
+ * Loads the module under test with the named peers replaced. The loaders read
+ * their peers through a dynamic import, so the substitution has to happen
+ * before the module graph is built — hence the reset and the dynamic import.
+ */
+async function loadPeerLoaders(
+  replacements: Record<string, Record<string, unknown>> = {},
+) {
+  vi.resetModules();
+  for (const specifier of Object.keys(installedPeers)) {
+    const namespace = replacements[specifier] ?? installedPeers[specifier];
+    vi.doMock(specifier, () => namespace);
+  }
+  return await import("./editor-peers");
+}
+
+afterEach(() => {
+  vi.resetModules();
+});
+
+describe("isMissingPeerError", () => {
+  it("recognises what each bundler and runtime says for an uninstalled package", () => {
+    const messages = [
+      // Vite's stub for an optional peer that is not installed.
+      'Could not resolve "@tiptap/react" imported by "@tangle-network/ui". Is it installed?',
+      // Node ESM.
+      "Cannot find package '@tiptap/react' imported from /app/index.js",
+      // CommonJS.
+      "Cannot find module '@tiptap/react'",
+      // webpack.
+      "Module not found: Error: Can't resolve '@tiptap/react' in '/app'",
+      // esbuild.
+      'Failed to resolve entry for package "@tiptap/react"',
+    ];
+
+    for (const message of messages) {
+      expect(isMissingPeerError(new Error(message)), message).toBe(true);
+    }
+  });
+
+  it("leaves a transient chunk failure to report its own cause", () => {
+    // Enriching this one with "install the peers" sends the reader to the
+    // wrong fix, and the peers are already installed.
+    expect(
+      isMissingPeerError(new Error("Failed to fetch dynamically imported module")),
+    ).toBe(false);
+    expect(isMissingPeerError(new Error("Network request failed"))).toBe(false);
+    expect(isMissingPeerError("Could not resolve")).toBe(false);
+  });
+});
+
+describe("editor optional peer loaders", () => {
+  it("returns the namespaces the editors call", async () => {
+    const { loadCollaborationPeers, loadDocumentEditorPeers } = await loadPeerLoaders();
+
+    const documentPeers = await loadDocumentEditorPeers();
+    expect(documentPeers.react.useEditor).toBe(installedPeers["@tiptap/react"].useEditor);
+    expect(documentPeers.starterKit.default).toBe(
+      installedPeers["@tiptap/starter-kit"].default,
+    );
+
+    const collaborationPeers = await loadCollaborationPeers();
+    expect(collaborationPeers.hocuspocus.HocuspocusProvider).toBe(
+      installedPeers["@hocuspocus/provider"].HocuspocusProvider,
+    );
+    expect(collaborationPeers.yjs.Doc).toBe(installedPeers.yjs.Doc);
+  });
+
+  it("names the install list when a peer resolves to a namespace with no editor in it", async () => {
+    // A bundler can stub a missing optional peer as a silent empty namespace
+    // rather than a throwing module. That shape must still fail with the peers
+    // named, and not as an undefined-property crash in the middle of a render.
+    const { loadDocumentEditorPeers } = await loadPeerLoaders({
+      "@tiptap/starter-kit": { default: undefined },
+    });
+
+    await expect(loadDocumentEditorPeers()).rejects.toThrow(
+      /Install @tiptap\/react and @tiptap\/starter-kit/,
+    );
+  });
+
+  it("names the install list when an extension stub carries a default it cannot configure", async () => {
+    // The commonest stub shape is a default export that is present but empty.
+    // It passes a plain "is the default defined" test, and then the factory
+    // calls .configure() on it and throws an opaque TypeError mid-render.
+    const { loadDocumentEditorPeers } = await loadPeerLoaders({
+      "@tiptap/starter-kit": { default: {} },
+    });
+
+    await expect(loadDocumentEditorPeers()).rejects.toThrow(
+      /Install @tiptap\/react and @tiptap\/starter-kit/,
+    );
+  });
+
+  it.each([
+    "@tiptap/extension-collaboration",
+    "@tiptap/extension-collaboration-caret",
+  ])("names the collaboration install list when %s is an empty default", async (specifier) => {
+    const { loadCollaborationPeers } = await loadPeerLoaders({
+      [specifier]: { default: {} },
+    });
+
+    await expect(loadCollaborationPeers()).rejects.toThrow(
+      /@hocuspocus\/provider and yjs/,
+    );
+  });
+
+  it("marks a missing peer permanent and leaves any other failure retryable", async () => {
+    // editor-lazy.ts reads this distinction to decide whether a remount may
+    // try the import again.
+    const { loadDocumentEditorPeers } = await loadPeerLoaders({
+      "@tiptap/starter-kit": { default: {} },
+    });
+
+    await expect(loadDocumentEditorPeers()).rejects.toSatisfy(isMissingEditorPeersError);
+    expect(isMissingEditorPeersError(new Error("Failed to fetch dynamically imported module"))).toBe(
+      false,
+    );
+  });
+
+  it("reports an unresolved import as a permanent missing peer and keeps the cause", async () => {
+    // The rejection a throwing stub gives must become the install list, so a
+    // consumer reads which packages to add, and must count as permanent so a
+    // remount does not retry an import that cannot start to succeed.
+    const resolutionFailure = new Error('Could not resolve "@tiptap/starter-kit"');
+    const mapped = asMissingEditorPeersError(resolutionFailure, "install the peers");
+
+    expect(isMissingEditorPeersError(mapped)).toBe(true);
+    expect(mapped).toHaveProperty("cause", resolutionFailure);
+    // The install list holds every peer the surface needs, so the message also
+    // names the one that is actually absent.
+    expect((mapped as Error).message).toBe(
+      "install the peers @tiptap/starter-kit did not resolve.",
+    );
+  });
+
+  it("names the caret package rather than the collaboration package it contains", async () => {
+    // "@tiptap/extension-collaboration" is a prefix of the caret specifier, so
+    // a naive substring match reports the wrong package.
+    const caretFailure = new Error(
+      'Could not resolve "@tiptap/extension-collaboration-caret"',
+    );
+    const mapped = asMissingEditorPeersError(caretFailure, "install the peers");
+
+    expect((mapped as Error).message).toBe(
+      "install the peers @tiptap/extension-collaboration-caret did not resolve.",
+    );
+  });
+
+  it("leaves a resolution failure that names no peer alone, so it stays retryable", async () => {
+    // An application chunk, or a dependency of a peer that did load, can fail
+    // to resolve too. Installing the editor peers would not fix that, and
+    // marking it permanent would stop a remount from trying again.
+    const unrelated = new Error("Cannot find module './app-chunk-a91f.js'");
+    const mapped = asMissingEditorPeersError(unrelated, "install the peers");
+
+    expect(mapped).toBe(unrelated);
+    expect(isMissingEditorPeersError(mapped)).toBe(false);
+  });
+
+  it("treats a @tiptap/core failure as a missing peer, though no loader imports it", async () => {
+    // The tiptap packages need @tiptap/core in turn, so a consumer that
+    // resolves it to nothing breaks exactly as one missing @tiptap/react
+    // does. Leaving it out of the list left that failure retryable.
+    const coreFailure = new Error('Could not resolve "@tiptap/core"');
+    const mapped = asMissingEditorPeersError(coreFailure, "install the peers");
+
+    expect(isMissingEditorPeersError(mapped)).toBe(true);
+    expect((mapped as Error).message).toBe(
+      "install the peers @tiptap/core did not resolve.",
+    );
+  });
+
+  it("keeps the install list alone when the failure names several peers", async () => {
+    const both = new Error(
+      'Could not resolve "@tiptap/react" or "@hocuspocus/provider"',
+    );
+    const mapped = asMissingEditorPeersError(both, "install the peers");
+
+    expect(isMissingEditorPeersError(mapped)).toBe(true);
+    expect((mapped as Error).message).toBe("install the peers");
+  });
+
+  it("leaves a transient chunk failure unchanged, so a remount can retry it", async () => {
+    const transient = new Error("Failed to fetch dynamically imported module");
+
+    expect(asMissingEditorPeersError(transient, "install the peers")).toBe(transient);
+    expect(isMissingEditorPeersError(transient)).toBe(false);
+  });
+
+  it("names the install list when a peer carries the wrong member type", async () => {
+    const { loadDocumentEditorPeers } = await loadPeerLoaders({
+      "@tiptap/react": { useEditor: undefined, EditorContent: undefined },
+    });
+
+    await expect(loadDocumentEditorPeers()).rejects.toThrow(
+      /Install @tiptap\/react and @tiptap\/starter-kit/,
+    );
+  });
+
+  it("accepts the shapes the installed peers really have", async () => {
+    // The other cases in this file describe the peers, so nothing here would
+    // notice a tiptap release that moves `configure` off the default export.
+    // Loading the real packages is what turns that into a failure here rather
+    // than in a consumer's editor.
+    vi.resetModules();
+    for (const specifier of Object.keys(installedPeers)) {
+      vi.doUnmock(specifier);
+    }
+    const { loadCollaborationPeers } = await import("./editor-peers");
+
+    const peers = await loadCollaborationPeers();
+    // Prove the substitutions are gone; against the stubs this case would
+    // pass without reading a real package at all.
+    expect(peers.starterKit.default).not.toBe(installedPeers["@tiptap/starter-kit"].default);
+    expect(typeof peers.starterKit.default.configure).toBe("function");
+    expect(typeof peers.collaboration.default.configure).toBe("function");
+    expect(typeof peers.collaborationCaret.default.configure).toBe("function");
+  });
+
+  it("keeps the local editor usable when only a collaboration peer is missing", async () => {
+    // sandbox-ui installs the tiptap packages alone, so the local markdown
+    // editor must not start to require yjs or Hocuspocus.
+    const { loadCollaborationPeers, loadDocumentEditorPeers } = await loadPeerLoaders({
+      yjs: { Doc: undefined },
+    });
+
+    await expect(loadDocumentEditorPeers()).resolves.toBeDefined();
+    await expect(loadCollaborationPeers()).rejects.toThrow(
+      /@hocuspocus\/provider and yjs/,
+    );
+  });
+});

package/src/editor/editor-peers.ts

@@ -0,0 +1,272 @@
+/**
+ * Resolves the optional peers behind the `./editor` entry.
+ *
+ * A bundler resolves an uninstalled optional peer to a stub module that
+ * carries a default export only and throws when it evaluates. One static
+ * `import { EditorContent } from "@tiptap/react"` therefore fails the build of
+ * every consumer that does not install tiptap, even when nothing renders an
+ * editor. Every value taken from an optional peer must arrive through the
+ * dynamic `import()` calls in this module, and each component is built from
+ * the loaded namespaces. Type-only imports are erased, so they stay allowed.
+ *
+ * A bundler still reads the literal specifier in a dynamic `import()`. Vite
+ * and Rollup leave an unresolved one to run time on their own; esbuild does so
+ * only when the call carries a `.catch()`. Every import below therefore
+ * attaches `rethrow`. Webpack has no such rule and needs consumer
+ * configuration, which `packages/ui/README.md` gives.
+ *
+ * Three loaders keep each surface independent of the peers it does not use. A
+ * consumer that installs only tiptap can edit markdown locally. A consumer
+ * that installs only yjs and Hocuspocus can drive its own editor from
+ * `EditorProvider`'s context. Only the collaborative editor needs all six.
+ *
+ * A missing peer and a transient chunk fetch fail differently, so they carry
+ * different types: a missing peer throws `MissingEditorPeersError`, which
+ * `editor-lazy.ts` treats as permanent, and any other rejection keeps its own
+ * error and stays retryable.
+ */
+
+import type * as Hocuspocus from "@hocuspocus/provider";
+import type * as TiptapCollaboration from "@tiptap/extension-collaboration";
+import type * as TiptapCollaborationCaret from "@tiptap/extension-collaboration-caret";
+import type * as TiptapReact from "@tiptap/react";
+import type * as TiptapStarterKit from "@tiptap/starter-kit";
+import type * as Yjs from "yjs";
+
+/** Namespaces the local markdown editor needs. */
+export interface DocumentEditorPeers {
+  react: typeof TiptapReact;
+  starterKit: typeof TiptapStarterKit;
+}
+
+/**
+ * Namespaces the collaboration transport needs. `EditorProvider` builds the
+ * document and the socket from these two alone, so it must not wait on the
+ * tiptap stack: a consumer can drive its own editor from the provider's
+ * context with nothing else installed.
+ */
+export interface EditorProviderPeers {
+  hocuspocus: typeof Hocuspocus;
+  yjs: typeof Yjs;
+}
+
+/** Namespaces the collaborative editor needs, on top of the two sets above. */
+export interface CollaborationPeers extends DocumentEditorPeers, EditorProviderPeers {
+  collaboration: typeof TiptapCollaboration;
+  collaborationCaret: typeof TiptapCollaborationCaret;
+}
+
+const DOCUMENT_PEERS_MISSING =
+  "@tangle-network/ui/editor needs its optional editor peers. " +
+  "Install @tiptap/react and @tiptap/starter-kit.";
+
+const PROVIDER_PEERS_MISSING =
+  "@tangle-network/ui/editor needs its optional collaboration transport peers. " +
+  "Install @hocuspocus/provider and yjs.";
+
+const COLLABORATION_PEERS_MISSING =
+  "@tangle-network/ui/editor needs its optional collaboration peers. " +
+  "Install @tiptap/react, @tiptap/starter-kit, @tiptap/extension-collaboration, " +
+  "@tiptap/extension-collaboration-caret, @hocuspocus/provider and yjs.";
+
+/**
+ * A peer the editor needs is absent, or resolved to a stub that carries none
+ * of the members the editor calls. The condition holds for the rest of the
+ * session, because a package does not install itself mid-run.
+ */
+export class MissingEditorPeersError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "MissingEditorPeersError";
+  }
+}
+
+/**
+ * True for the error above. The name carries the answer, so a duplicated copy
+ * of this module in a consumer's bundle still reports its own error correctly.
+ */
+export function isMissingEditorPeersError(error: unknown): boolean {
+  return error instanceof Error && error.name === "MissingEditorPeersError";
+}
+
+/** The messages a bundler or a runtime gives for a module it cannot resolve. */
+const RESOLUTION_FAILURE =
+  /could not resolve|cannot find (?:module|package)|can't resolve|failed to resolve|module not found/i;
+
+/**
+ * True when the rejection says the package is not installed. Only such an
+ * error gets the install list: a transient chunk-fetch failure that reads as
+ * "install the peers" sends the reader to the wrong fix. An error this
+ * predicate does not match keeps its own message, so it can only
+ * under-report.
+ */
+export function isMissingPeerError(error: unknown): boolean {
+  return error instanceof Error && RESOLUTION_FAILURE.test(error.message);
+}
+
+/**
+ * Hands an `import()` rejection on unchanged. esbuild reports an unresolvable
+ * literal `import()` as a build error and defers it to run time only when the
+ * call carries a `.catch()`, so every peer import attaches this handler. It
+ * changes nothing at run time.
+ */
+function rethrow(error: unknown): never {
+  throw error;
+}
+
+/**
+ * Every optional peer the `./editor` entry needs at run time. The loaders
+ * import all but `@tiptap/core`, which the tiptap packages need in turn: a
+ * consumer that resolves it to nothing breaks the same way, so a failure that
+ * names it is a missing peer too. `scripts/validate-dist.mjs` holds the same
+ * list and rejects a build where the two disagree.
+ */
+const DEFERRED_PEERS = [
+  "@tiptap/core",
+  "@tiptap/react",
+  "@tiptap/starter-kit",
+  "@tiptap/extension-collaboration",
+  "@tiptap/extension-collaboration-caret",
+  "@hocuspocus/provider",
+  "yjs",
+];
+
+/** Every deferred peer a resolution failure names. */
+function unresolvedPeersFrom(error: unknown): string[] {
+  if (!(error instanceof Error)) return [];
+  const named = DEFERRED_PEERS.filter((name) => error.message.includes(name));
+  // "@tiptap/extension-collaboration" is a prefix of the caret package, so a
+  // message about the caret names both. Drop a name another match contains.
+  return named.filter(
+    (name) => !named.some((other) => other !== name && other.includes(name)),
+  );
+}
+
+/**
+ * Turns a rejection that names an unresolved peer into the install-list error,
+ * and keeps the original as its cause. Any other rejection passes through, so
+ * a transient chunk fetch keeps its own message and stays retryable.
+ */
+export function asMissingEditorPeersError(
+  error: unknown,
+  missingMessage: string,
+): unknown {
+  if (!isMissingPeerError(error)) return error;
+  const unresolved = unresolvedPeersFrom(error);
+  // A resolution failure that names none of the peers comes from somewhere
+  // else: an application chunk, or a dependency of a peer that did load.
+  // Installing the list would not fix it, and a later attempt can still
+  // succeed, so it keeps its own error and stays retryable.
+  if (unresolved.length === 0) return error;
+  const detail =
+    unresolved.length === 1 ? ` ${unresolved[0]} did not resolve.` : "";
+  return new MissingEditorPeersError(missingMessage + detail, { cause: error });
+}
+
+async function loadPeers<T>(
+  load: () => Promise<T>,
+  missingMessage: string,
+): Promise<T> {
+  try {
+    return await load();
+  } catch (error) {
+    throw asMissingEditorPeersError(error, missingMessage);
+  }
+}
+
+/**
+ * True for a tiptap extension the editor can configure. A bundler can stub a
+ * missing optional peer as a silent namespace whose default export is an empty
+ * object, which is defined but carries no `configure`. Reading the member the
+ * factories call separates that shape from a real extension.
+ */
+function isConfigurableExtension(value: unknown): boolean {
+  return typeof (value as { configure?: unknown } | undefined)?.configure === "function";
+}
+
+/**
+ * Reads the members the editor calls, so a stub namespace fails with the
+ * install list, and not as an undefined-property crash in the middle of a
+ * render.
+ */
+function assertDocumentEditorPeers(
+  peers: DocumentEditorPeers,
+  missingMessage: string,
+): void {
+  if (
+    typeof peers.react.useEditor !== "function" ||
+    peers.react.EditorContent === undefined ||
+    !isConfigurableExtension(peers.starterKit.default)
+  ) {
+    throw new MissingEditorPeersError(missingMessage);
+  }
+}
+
+function assertEditorProviderPeers(
+  peers: EditorProviderPeers,
+  missingMessage: string,
+): void {
+  if (
+    typeof peers.hocuspocus.HocuspocusProvider !== "function" ||
+    typeof peers.yjs.Doc !== "function"
+  ) {
+    throw new MissingEditorPeersError(missingMessage);
+  }
+}
+
+function assertCollaborationPeers(peers: CollaborationPeers): void {
+  assertDocumentEditorPeers(peers, COLLABORATION_PEERS_MISSING);
+  assertEditorProviderPeers(peers, COLLABORATION_PEERS_MISSING);
+  if (
+    !isConfigurableExtension(peers.collaboration.default) ||
+    !isConfigurableExtension(peers.collaborationCaret.default)
+  ) {
+    throw new MissingEditorPeersError(COLLABORATION_PEERS_MISSING);
+  }
+}
+
+async function importDocumentEditorPeers(): Promise<DocumentEditorPeers> {
+  const [react, starterKit] = await Promise.all([
+    import("@tiptap/react").catch(rethrow),
+    import("@tiptap/starter-kit").catch(rethrow),
+  ]);
+  return { react, starterKit };
+}
+
+async function importEditorProviderPeers(): Promise<EditorProviderPeers> {
+  const [hocuspocus, yjs] = await Promise.all([
+    import("@hocuspocus/provider").catch(rethrow),
+    import("yjs").catch(rethrow),
+  ]);
+  return { hocuspocus, yjs };
+}
+
+/** Resolve the collaboration transport's peers, or throw and name them. */
+export async function loadEditorProviderPeers(): Promise<EditorProviderPeers> {
+  const peers = await loadPeers(importEditorProviderPeers, PROVIDER_PEERS_MISSING);
+  assertEditorProviderPeers(peers, PROVIDER_PEERS_MISSING);
+  return peers;
+}
+
+/** Resolve the local markdown editor's peers, or throw and name them. */
+export async function loadDocumentEditorPeers(): Promise<DocumentEditorPeers> {
+  const peers = await loadPeers(importDocumentEditorPeers, DOCUMENT_PEERS_MISSING);
+  assertDocumentEditorPeers(peers, DOCUMENT_PEERS_MISSING);
+  return peers;
+}
+
+/** Resolve the collaborative editor's peers, or throw and name them. */
+export async function loadCollaborationPeers(): Promise<CollaborationPeers> {
+  const peers = await loadPeers(async () => {
+    const [documentPeers, providerPeers, collaboration, collaborationCaret] =
+      await Promise.all([
+        importDocumentEditorPeers(),
+        importEditorProviderPeers(),
+        import("@tiptap/extension-collaboration").catch(rethrow),
+        import("@tiptap/extension-collaboration-caret").catch(rethrow),
+      ]);
+    return { ...documentPeers, ...providerPeers, collaboration, collaborationCaret };
+  }, COLLABORATION_PEERS_MISSING);
+  assertCollaborationPeers(peers);
+  return peers;
+}