@inkandswitch/patchwork-bootloader 0.3.1 → 0.3.2

package/src/site.ts

@@ -22,7 +22,6 @@ import {
   stringifyAutomergeUrl,
   type AutomergeUrl,
   type DocumentId,
-  type UrlHeads,
 } from "@automerge/vanillajs/slim";
 import { IndexedDBWorkerStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb/IndexedDBWorkerStorageAdapter";
 import * as Automerge from "@automerge/automerge/slim";
@@ -35,6 +34,7 @@ import {
 // eslint-disable-next-line
 // @ts-ignore — initSync is a wasm-bindgen runtime helper not in the .d.ts
 import { initSync as initSubductionSync } from "@automerge/automerge-subduction/slim";
+import { MemorySigner } from "@automerge/automerge-subduction/slim";
 
 declare const __SITE_NAME__: string;
 const siteName =
@@ -70,7 +70,10 @@ import setupServiceWorker, {
   getAutomergeWorker,
   lifecycleLoggingEnabled,
 } from "./setup.js";
-import type { ServiceWorkerRepoChannelListener } from "./types.js";
+import type {
+  ServiceWorkerRepoChannelListener,
+  SyncStateDocMessage,
+} from "./types.js";
 import debug from "debug";
 const log = debug("patchwork:bootloader:site");
 
@@ -87,11 +90,19 @@ declare global {
       packages: ModuleWatcher;
       plugins: typeof plugins;
       accountDocHandle: DocHandle<AccountDoc>;
+      signer?: {
+        peerId: string;
+        verifyingKey: string;
+      };
       sw: {
         connectClassicSync: (server?: string) => Promise<void>;
         subscribeToRepoChannel: (
           listener: ServiceWorkerRepoChannelListener
         ) => Promise<() => void>;
+        subscribeSyncState: (
+          documentId: string,
+          listener: (update: SyncStateDocMessage) => void
+        ) => () => void;
       };
     };
     uncache: (match: string) => Promise<void>;
@@ -196,6 +207,7 @@ export async function bootPatchworkSite(
 
   let hive: AutomergeRepoKeyhive | undefined;
   let repo: Repo;
+  let tabSignerIdentity: { peerId: string; verifyingKey: string } | undefined;
 
   // If a Repo is already on `window` — an embedding context provided one before
   // this entry ran — reuse it and its keyhive instead of standing up a fresh
@@ -240,9 +252,15 @@ export async function bootPatchworkSite(
       log("keyhive setup complete");
     } else {
       log("creating repo");
+      // Pass an explicit signer (instead of the Repo's internal default) so we
+      // can expose tab signer identity on window.patchwork for dev inspection.
+      // The tab never connects via Subduction (no endpoints/adapters), so this
+      // id never goes on the wire.
+      const tabSigner = new MemorySigner();
       repo = new Repo({
         network: [new MessageChannelNetworkAdapter(workerPort)],
         storage: new IndexedDBWorkerStorageAdapter(),
+        signer: tabSigner,
         async sharePolicy(peerId) {
           return peerId.includes("automerge-worker");
         },
@@ -250,6 +268,15 @@ export async function bootPatchworkSite(
         peerId:
           `${config.titleSuffix}-tab-${crypto.randomUUID()}` as AutomergeRepo.PeerId,
       });
+      tabSignerIdentity = {
+        peerId: tabSigner.peerId().toString(),
+        verifyingKey: (
+          tabSigner.verifyingKey() as Uint8Array<ArrayBufferLike> & {
+            toHex(): string;
+          }
+        ).toHex(),
+      };
+      console.log("[patchwork] tab subduction identity:", tabSignerIdentity);
       log("repo created");
     }
   }
@@ -315,9 +342,11 @@ export async function bootPatchworkSite(
     packages: moduleWatcher,
     plugins,
     accountDocHandle,
+    ...(tabSignerIdentity ? { signer: tabSignerIdentity } : {}),
     sw: {
       connectClassicSync: sw.connectClassicSync,
       subscribeToRepoChannel: sw.subscribeToRepoChannel,
+      subscribeSyncState: sw.subscribeSyncState,
     },
   };
   window.uncache = uncache;
@@ -503,10 +532,8 @@ function primeRootElement(
   const initialParams = new URLSearchParams(location.hash.slice(1));
   if (initialParams.has("frame")) {
     rootElement.setAttribute("tool-id", initialParams.get("frame")!);
-    const docId = initialParams.get("doc")?.replace(/^automerge:/, "");
-    const docUrl = docId
-      ? stringifyAutomergeUrl({ documentId: docId as DocumentId })
-      : accountDocHandle.url;
+    const docUrl =
+      docParamToUrl(initialParams.get("doc")) ?? accountDocHandle.url;
     rootElement.setAttribute("doc-url", docUrl);
   } else {
     rootElement.setAttribute("tool-id", accountDocHandle.doc().frameToolId);
@@ -598,6 +625,43 @@ async function uncache(match: string): Promise<void> {
   }
 }
 
+// Keys whose values are automerge URLs — we keep the `:` (and any `#`/`|`
+// heads) literal rather than percent-encoding them so links stay readable.
+const RAW_HASH_KEYS = new Set(["doc", "package"]);
+// Emit hash params in a stable order so re-serializing the same logical
+// params yields a byte-identical string (avoids spurious `hashchange`).
+const HASH_KEY_ORDER = ["doc", "package", "tool", "type", "title", "frame"];
+
+function serializeHashParams(params: URLSearchParams): string {
+  const emitted = new Set<string>();
+  const parts: string[] = [];
+  const emit = (key: string) => {
+    if (emitted.has(key)) return;
+    const value = params.get(key);
+    if (!value) return;
+    emitted.add(key);
+    parts.push(`${key}=${RAW_HASH_KEYS.has(key) ? value : encodeURIComponent(value)}`);
+  };
+  for (const key of HASH_KEY_ORDER) emit(key);
+  for (const key of params.keys()) emit(key);
+  return parts.join("&");
+}
+
+/**
+ * Coerce a `doc=` hash param to a full automerge URL. Accepts a full URL
+ * (`automerge:<id>[#heads]`) or a bare document id for backwards
+ * compatibility with older links.
+ */
+function docParamToUrl(docParam: string | null): AutomergeUrl | undefined {
+  if (!docParam) return undefined;
+  if (isValidAutomergeUrl(docParam as AutomergeUrl)) return docParam as AutomergeUrl;
+  const documentId = docParam.replace(/^automerge:/, "");
+  if (isValidDocumentId(documentId)) {
+    return stringifyAutomergeUrl({ documentId: documentId as DocumentId });
+  }
+  return undefined;
+}
+
 interface HashRoutingParams {
   rootElement: HTMLElement;
   repo: Repo;
@@ -610,10 +674,6 @@ function installHashRouting(params: HashRoutingParams): void {
   const { rootElement, repo, accountDocHandle, moduleWatcher, titleSuffix } =
     params;
 
-  rootElement.addEventListener("patchwork:no-tool", (event) => {
-    moduleWatcher.loadSuggestedImportUrl(event.detail.url);
-  });
-
   rootElement.addEventListener("patchwork:open-document", async (event) => {
     const params = new URLSearchParams(window.location.hash.slice(1));
     const { url, toolId, type, title } = event.detail as {
@@ -622,22 +682,21 @@ function installHashRouting(params: HashRoutingParams): void {
       type?: string;
       title?: string;
     };
-    const { documentId, heads } = parseAutomergeUrl(url);
-    params.set("doc", documentId);
-    if (heads) params.set("heads", heads.join("|"));
-    else params.delete("heads");
+    // `doc` is now the full automerge URL (heads, if any, live in it). The
+    // in-use package is recorded separately in `package=` when a tool mounts.
+    params.delete("heads");
+    params.set("doc", url);
     if (toolId) params.set("tool", toolId);
     else params.delete("tool");
     if (title) params.set("title", title);
     else params.delete("title");
     if (type) params.set("type", type);
     else params.delete("type");
-    window.location.hash = params.toString();
+    window.location.hash = serializeHashParams(params);
 
     try {
-      const docHandle = await repo.find<{ "@patchwork"?: { type?: string } }>(
-        stringifyAutomergeUrl({ documentId, heads })
-      );
+      const docHandle =
+        await repo.find<{ "@patchwork"?: { type?: string } }>(url);
       const doc = docHandle.doc();
       const docType = type || doc?.["@patchwork"]?.type;
       if (!docType) return;
@@ -655,6 +714,29 @@ function installHashRouting(params: HashRoutingParams): void {
     }
   });
 
+  // When a tool mounts we know the package actually rendering the top-level
+  // document, so record its (heads-pinned) importUrl in `package=`.
+  const recordInUsePackage = (event: Event) => {
+    const detail = (event as CustomEvent).detail;
+    if (!detail || !("url" in detail) || !detail.importUrl) return;
+    const params = new URLSearchParams(window.location.hash.slice(1));
+    const docUrl = docParamToUrl(params.get("doc"));
+    if (!docUrl) return;
+    // Ignore nested branch / side-by-side views: only the top-level doc's
+    // package belongs in the hash.
+    if (
+      parseAutomergeUrl(docUrl).documentId !==
+      parseAutomergeUrl(detail.url as AutomergeUrl).documentId
+    ) {
+      return;
+    }
+    if (params.get("package") === detail.importUrl) return;
+    params.set("package", detail.importUrl);
+    // Replace rather than push: recording the in-use package shouldn't add a
+    // back-button entry (and replaceState avoids a `hashchange` round-trip).
+    history.replaceState(null, "", `#${serializeHashParams(params)}`);
+  };
+
   let firstMount = true;
   const reveal = () => {
     if (!firstMount) return;
@@ -664,6 +746,7 @@ function installHashRouting(params: HashRoutingParams): void {
   };
 
   rootElement.addEventListener("patchwork:mounted", (event) => {
+    recordInUsePackage(event);
     handleHashChange();
     if (event.target !== rootElement) return;
     console.info("root element mounted");
@@ -691,39 +774,40 @@ function installHashRouting(params: HashRoutingParams): void {
 
     // Bare automerge URL in hash: /#automerge:<documentId>
     if (isValidAutomergeUrl(hash as AutomergeUrl)) {
-      const { documentId, heads } = parseAutomergeUrl(hash as AutomergeUrl);
+      const url = hash as AutomergeUrl;
       window.location.hash = "";
-      openDocument(rootElement, stringifyAutomergeUrl({ documentId, heads }));
+      openDocument(rootElement, url);
       return;
     }
 
     const params = new URLSearchParams(hash);
-    const documentId = params.get("doc")?.replace(/^automerge:/, "");
-    const heads = params.get("heads")?.split("|") as UrlHeads | undefined;
+    const docUrl = docParamToUrl(params.get("doc"));
+    const packageUrl = params.get("package");
     const toolId = params.get("tool");
     const title = params.get("title");
     const type = params.get("type");
     const frame = params.get("frame");
+
+    // Load the package that produced this document so its tool is available
+    // even when it isn't in the user's module settings.
+    if (packageUrl) {
+      void moduleWatcher.loadModules([packageUrl]);
+    }
+
     if (frame) {
-      const docUrl =
-        params.get("doc")?.replace(/^automerge:/, "") ?? accountDocHandle.url;
+      const frameDocUrl = docUrl ?? accountDocHandle.url;
       if (
         rootElement.getAttribute("tool-id") !== frame ||
-        rootElement.getAttribute("doc-url") !== docUrl
+        rootElement.getAttribute("doc-url") !== frameDocUrl
       ) {
         rootElement.setAttribute("tool-id", frame);
-        rootElement.setAttribute("doc-url", docUrl);
+        rootElement.setAttribute("doc-url", frameDocUrl);
       }
     }
-    if (isValidDocumentId(documentId)) {
+    if (docUrl) {
       rootElement.dispatchEvent(
         new CustomEvent("patchwork:open-document", {
-          detail: {
-            url: stringifyAutomergeUrl({ documentId, heads }),
-            toolId,
-            title,
-            type,
-          },
+          detail: { url: docUrl, toolId, title, type },
         })
       );
     }

package/src/types.ts

@@ -13,6 +13,83 @@ export const HANDOFF_CHANNEL = "@patchwork/handoff";
  */
 export const SYNCSTATE_CHANNEL = "@patchwork/syncstate";
 
+/**
+ * Worker → tabs: the worker's Subduction link to the sync server flipped.
+ * `serverPeerIds` are the directly-connected sync-server peer ids (their
+ * verifying keys), so a tab can tell which peer rows are *the server* and
+ * judge "synced" against them specifically.
+ */
+export interface SyncStateConnectionMessage {
+  type: "connection";
+  connected: boolean;
+  serverPeerIds: string[];
+}
+
+/**
+ * Worker → tabs: the shared worker's own Subduction identity, so a tab can
+ * tell which peer rows are "us". `peerId` is `signer.peerId().toString()` (the
+ * value that shows up as a peer id); `verifyingKey` is its hex Ed25519 key.
+ */
+export interface SyncStateWhoAmIMessage {
+  type: "whoami";
+  peerId: string;
+  verifyingKey: string;
+}
+
+// What the worker broadcasts on SYNCSTATE_CHANNEL: only the *global* signals
+// now. Per-document heads are addressed to subscribers over the control port
+// instead (see SyncStateDocMessage) rather than fanned out to every tab.
+export type SyncStateBroadcast =
+  | SyncStateConnectionMessage
+  | SyncStateWhoAmIMessage;
+
+/**
+ * Tab → worker: please replay the current global sync signals (whoami +
+ * connection) so a freshly-opened tab can orient immediately. Per-document
+ * heads are no longer replayed here — a tab subscribes to the specific docs it
+ * cares about over its control port instead (see {@link SyncSubscribeMessage}).
+ */
+export interface SyncStateRequestMessage {
+  type: "request";
+  /** @deprecated ignored — per-doc state is delivered via sync-sub now. */
+  documentId?: string;
+}
+
+// ── Per-tab sync-state subscription (over the SharedWorker control port) ──
+//
+// The broadcast SyncState* messages above are global (connection/whoami).
+// Per-document heads, by contrast, are addressed: a tab subscribes its control
+// port to just the documents it cares about and the worker pushes only those
+// docs' heads back down that port. The worker drops a port's whole
+// subscription set automatically when the port closes (the tab went away), so
+// there's no reference counting or heartbeat to leak.
+
+/** Tab → worker: start pushing me this document's heads (replays current state). */
+export interface SyncSubscribeMessage {
+  type: "sync-sub";
+  documentId: string;
+}
+
+/** Tab → worker: stop pushing me this document's heads. */
+export interface SyncUnsubscribeMessage {
+  type: "sync-unsub";
+  documentId: string;
+}
+
+/**
+ * Worker → tab (control port): a peer's heads for a subscribed document — the
+ * worker's own (keyed by its peerId) or a Subduction peer's (keyed by its
+ * verifying-key storageId). Same payload as the old broadcast remote-heads
+ * message, but delivered only to the tabs that asked for this document.
+ */
+export interface SyncStateDocMessage {
+  type: "sync-state";
+  documentId: string;
+  storageId: string;
+  heads: string[];
+  timestamp: number;
+}
+
 /**
  * The special URL to resolve, plus enough of the {@link Request} the service
  * worker is holding that the automerge worker can construct one that
@@ -121,4 +198,15 @@ export type SetupServiceWorkerResult = {
   ) => Promise<() => void>;
   /** Open a fresh repo sync port to the automerge worker (dev console). */
   getRepoChannel: () => MessagePort;
+  /**
+   * Watch one document's sync heads (this tab's own and each Subduction peer's,
+   * as the worker learns them). Calls `listener` on every update for that doc,
+   * replaying the current state on subscribe. Returns an unsubscribe function;
+   * the worker stops pushing the doc once the last local watcher drops it (and
+   * automatically if this tab goes away).
+   */
+  subscribeSyncState: (
+    documentId: string,
+    listener: (update: SyncStateDocMessage) => void
+  ) => () => void;
 };