@jtfmumm/patchwork-standalone-frame 0.1.0 → 0.2.0

package/dist/mount.d.ts

@@ -1,2 +1,2 @@
-import type { ToolRegistration } from "./index.ts";
-export declare function mountStandaloneApp<D>(rootElement: HTMLElement, tool: ToolRegistration<D>): void;
+import type { ToolRegistration, StandaloneFrameConfig, Plugin } from "./index.ts";
+export declare function mountStandaloneApp<D>(rootElement: HTMLElement, toolOrPlugins: ToolRegistration<D> | Plugin<D>[], config?: StandaloneFrameConfig): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jtfmumm/patchwork-standalone-frame",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Reusable standalone frame for patchwork tools with keyhive, doc history, and access control",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,6 +22,11 @@
     "@automerge/automerge-repo-storage-indexeddb": "^2.5.2-alpha.0",
     "solid-js": "^1.9.9"
   },
+  "peerDependenciesMeta": {
+    "@automerge/automerge-repo-keyhive": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@automerge/automerge-repo": "^2.5.2-alpha.0",
     "@automerge/automerge-repo-keyhive": "0.1.0-alpha.17za",

package/src/frame.tsx

@@ -1,20 +1,7 @@
 import { createSignal, Show, For, onMount, onCleanup } from "solid-js";
-import {
-  Repo,
-  type AutomergeUrl,
-  type DocHandle,
-} from "@automerge/automerge-repo";
-import { IndexedDBStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb";
-import { BrowserWebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket";
-import {
-  initializeAutomergeRepoKeyhive,
-  initKeyhiveWasm,
-  docIdFromAutomergeUrl,
-  Identifier,
-  uint8ArrayToHex,
-  type AutomergeRepoKeyhive,
-} from "@automerge/automerge-repo-keyhive";
-import type { ToolRegistration, ToolElement } from "./index.ts";
+import type { AutomergeUrl, DocHandle } from "@automerge/automerge-repo";
+import type { AutomergeRepoKeyhive } from "@automerge/automerge-repo-keyhive";
+import type { ToolRegistration, ToolElement, StandaloneFrameConfig, FrameRepo, FrameDocHandle } from "./index.ts";
 import {
   type DocHistoryEntry,
   loadHistory,
@@ -28,19 +15,16 @@ import { ShareModal } from "./share-modal.tsx";
 import { ConfirmModal } from "./confirm-modal.tsx";
 import { NewDocModal } from "./new-doc-modal.tsx";
 
-// Init keyhive WASM at module level (must happen before initializeAutomergeRepoKeyhive)
-initKeyhiveWasm();
-
 declare global {
   interface Window {
     hive?: AutomergeRepoKeyhive;
   }
 }
 
-export function StandaloneApp<D>(props: { tool: ToolRegistration<D> }) {
+export function StandaloneApp<D>(props: { tool: ToolRegistration<D>; config?: StandaloneFrameConfig }) {
   const tool = props.tool;
 
-  const [handle, setHandle] = createSignal<DocHandle<D> | null>(null);
+  const [handle, setHandle] = createSignal<FrameDocHandle<D> | null>(null);
   const [docTitle, setDocTitle] = createSignal<string>("...");
   const [history, setHistory] = createSignal<DocHistoryEntry[]>([]);
   const [dropdownOpen, setDropdownOpen] = createSignal(false);
@@ -56,11 +40,11 @@ export function StandaloneApp<D>(props: { tool: ToolRegistration<D> }) {
   const [pendingDocUrl, setPendingDocUrl] = createSignal<string | null>(null);
   const [loading, setLoading] = createSignal(false);
 
-  let repo!: Repo;
+  let repo!: FrameRepo;
   let titleCleanup: (() => void) | null = null;
   let loadGeneration = 0;
 
-  function trackTitle(h: DocHandle<D>): void {
+  function trackTitle(h: FrameDocHandle<D>): void {
     if (titleCleanup) {
       titleCleanup();
       titleCleanup = null;
@@ -87,6 +71,7 @@ export function StandaloneApp<D>(props: { tool: ToolRegistration<D> }) {
     const h = hive();
     if (!h) return true;
     try {
+      const { docIdFromAutomergeUrl, Identifier } = await import("@automerge/automerge-repo-keyhive");
       const docId = docIdFromAutomergeUrl(url as AutomergeUrl);
       const myId = h.active.individual.id;
       const publicId = Identifier.publicId();
@@ -124,23 +109,23 @@ export function StandaloneApp<D>(props: { tool: ToolRegistration<D> }) {
       }
       if (gen !== loadGeneration) return;
 
-      const isDocReady = (h: DocHandle<D>) => {
+      const isDocReady = (h: FrameDocHandle<D>) => {
         const d = h.doc() as D;
         if (!d) return false;
         return tool.isDocReady ? tool.isDocReady(d) : !!d;
       };
 
-      let docHandle = await repo.find<D>(url as AutomergeUrl);
+      let docHandle = repo.find<D>(url);
       await docHandle.whenReady();
       if (gen !== loadGeneration) return;
 
       if (!isDocReady(docHandle)) {
         console.log(`[${tool.name}] Doc incomplete, forcing re-sync for: ${url.slice(0, 30)}...`);
-        try { repo.delete(url as AutomergeUrl); } catch { /* ignore */ }
+        try { repo.delete(url); } catch { /* ignore */ }
         await new Promise((r) => setTimeout(r, 100));
         if (gen !== loadGeneration) return;
 
-        docHandle = await repo.find<D>(url as AutomergeUrl);
+        docHandle = repo.find<D>(url);
         await docHandle.whenReady();
         if (gen !== loadGeneration) return;
       }
@@ -177,21 +162,25 @@ export function StandaloneApp<D>(props: { tool: ToolRegistration<D> }) {
   }
 
   async function createNewDoc(title: string = tool.defaultTitle): Promise<void> {
-    const h = hive();
-    if (!h) return;
-
     const initialDoc = {} as Record<string, unknown>;
-    tool.init(initialDoc as D, repo);
+    tool.init(initialDoc as D, repo as unknown as Parameters<typeof tool.init>[1]);
     if (tool.setTitle) tool.setTitle(initialDoc as D, title);
     initialDoc["@patchwork"] = { type: tool.id };
-    const docHandle = await repo.create2<D>(initialDoc as D);
-    console.log(`[${tool.name}] Created document: ${docHandle.url}`);
 
-    await h.addSyncServerPullToDoc(docHandle.url);
-    await h.keyhiveStorage.saveKeyhiveWithHash(h.keyhive);
+    const h = hive();
+    let docHandle: FrameDocHandle<D>;
+    if (h) {
+      docHandle = await (repo as unknown as { create2<T>(v: T): Promise<FrameDocHandle<T>> }).create2<D>(initialDoc as D);
+      console.log(`[${tool.name}] Created document (keyhive): ${docHandle.url}`);
+      await h.addSyncServerPullToDoc(docHandle.url as AutomergeUrl);
+      await h.keyhiveStorage.saveKeyhiveWithHash(h.keyhive);
+    } else {
+      docHandle = repo.create<D>(initialDoc as D);
+      console.log(`[${tool.name}] Created document (legacy): ${docHandle.url}`);
+    }
 
     setHandle(docHandle);
-    setDocUrlInHash(docHandle.url);
+    setDocUrlInHash(docHandle.url as AutomergeUrl);
     localStorage.setItem(activeDocKey(tool.id, identityHexId()), docHandle.url);
     trackTitle(docHandle);
   }
@@ -232,67 +221,102 @@ export function StandaloneApp<D>(props: { tool: ToolRegistration<D> }) {
   }
 
   onMount(async () => {
-    const keyhiveStorage = new IndexedDBStorageAdapter(`${tool.id}-keyhive`);
-    const envSyncUrl = (import.meta as unknown as Record<string, Record<string, string>>).env?.VITE_SYNC_URL;
-    const networkAdapter = new BrowserWebSocketClientAdapter(
-      envSyncUrl || tool.syncUrl || "ws://localhost:3030"
-    );
-    const peerIdSuffix = `${tool.id}-${Math.random().toString(36).slice(2)}`;
-
-    const automergeRepoKeyhive = await initializeAutomergeRepoKeyhive({
-      storage: keyhiveStorage,
-      peerIdSuffix,
-      networkAdapter,
-      automaticArchiveIngestion: true,
-      onlyShareWithHardcodedServerPeerId: true,
-      cacheHashes: true,
-    });
-    window.hive = automergeRepoKeyhive;
-
-    repo = new Repo({
-      storage: new IndexedDBStorageAdapter(),
-      network: [automergeRepoKeyhive.networkAdapter],
-      peerId: automergeRepoKeyhive.peerId,
-      sharePolicy: async (peerId) => {
-        return peerId === automergeRepoKeyhive.syncServer?.peerId;
-      },
-      idFactory: automergeRepoKeyhive.idFactory,
-    });
-
-    automergeRepoKeyhive.linkRepo(repo);
-    setHive(automergeRepoKeyhive);
-
-    const hexId = uint8ArrayToHex(
-      automergeRepoKeyhive.active.individual.id.toBytes()
-    );
-    setIdentityHexId(hexId);
-    setHistory(loadHistory(tool.id, hexId));
-    setReady(true);
-
-    console.log(`[${tool.name}] Keyhive initialized, identity: 0x${hexId.slice(0, 12)}...`);
-
-    (automergeRepoKeyhive.networkAdapter as { on: (event: string, cb: () => void) => void }).on("ingest-remote", async () => {
-      const pending = pendingDocUrl();
-      if (pending) {
-        if (await checkAccess(pending)) {
-          console.log(`[${tool.name}] Access granted, loading: ${pending}`);
-          await loadDoc(pending);
-        }
-        return;
+    if (props.config?.legacyMode) {
+      // Legacy path: use the passed-in repo, no automerge-repo or keyhive imports
+      repo = props.config.repo!;
+
+      // Generate a stable identity hex ID for doc history via localStorage
+      const storageKey = `standalone-frame-identity-${tool.id}`;
+      let hexId = localStorage.getItem(storageKey);
+      if (!hexId) {
+        const bytes = new Uint8Array(16);
+        crypto.getRandomValues(bytes);
+        hexId = Array.from(bytes).map(b => b.toString(16).padStart(2, "0")).join("");
+        localStorage.setItem(storageKey, hexId);
       }
+      setIdentityHexId(hexId);
+      setHistory(loadHistory(tool.id, hexId));
+      setReady(true);
+
+      console.log(`[${tool.name}] Legacy mode initialized, identity: 0x${hexId.slice(0, 12)}...`);
+    } else {
+      // Keyhive path (default): dynamic import everything
+      const [
+        { Repo },
+        { IndexedDBStorageAdapter },
+        { BrowserWebSocketClientAdapter },
+        keyhive,
+      ] = await Promise.all([
+        import("@automerge/automerge-repo"),
+        import("@automerge/automerge-repo-storage-indexeddb"),
+        import("@automerge/automerge-repo-network-websocket"),
+        import("@automerge/automerge-repo-keyhive"),
+      ]);
+      keyhive.initKeyhiveWasm();
+
+      const keyhiveStorage = new IndexedDBStorageAdapter(`${tool.id}-keyhive`);
+      const envSyncUrl = (import.meta as unknown as Record<string, Record<string, string>>).env?.VITE_SYNC_URL;
+      const networkAdapter = new BrowserWebSocketClientAdapter(
+        envSyncUrl || tool.syncUrl || "ws://localhost:3030"
+      );
+      const peerIdSuffix = `${tool.id}-${Math.random().toString(36).slice(2)}`;
+
+      const automergeRepoKeyhive = await keyhive.initializeAutomergeRepoKeyhive({
+        storage: keyhiveStorage,
+        peerIdSuffix,
+        networkAdapter,
+        automaticArchiveIngestion: true,
+        onlyShareWithHardcodedServerPeerId: true,
+        cacheHashes: true,
+      });
+      window.hive = automergeRepoKeyhive;
+
+      const realRepo = new Repo({
+        storage: new IndexedDBStorageAdapter(),
+        network: [automergeRepoKeyhive.networkAdapter],
+        peerId: automergeRepoKeyhive.peerId,
+        sharePolicy: async (peerId) => {
+          return peerId === automergeRepoKeyhive.syncServer?.peerId;
+        },
+        idFactory: automergeRepoKeyhive.idFactory,
+      });
+      repo = realRepo as unknown as FrameRepo;
+
+      automergeRepoKeyhive.linkRepo(realRepo);
+      setHive(automergeRepoKeyhive);
+
+      const hexId = keyhive.uint8ArrayToHex(
+        automergeRepoKeyhive.active.individual.id.toBytes()
+      );
+      setIdentityHexId(hexId);
+      setHistory(loadHistory(tool.id, hexId));
+      setReady(true);
+
+      console.log(`[${tool.name}] Keyhive initialized, identity: 0x${hexId.slice(0, 12)}...`);
+
+      (automergeRepoKeyhive.networkAdapter as { on: (event: string, cb: () => void) => void }).on("ingest-remote", async () => {
+        const pending = pendingDocUrl();
+        if (pending) {
+          if (await checkAccess(pending)) {
+            console.log(`[${tool.name}] Access granted, loading: ${pending}`);
+            await loadDoc(pending);
+          }
+          return;
+        }
 
-      const h = handle();
-      if (h) {
-        if (!(await checkAccess(h.url))) {
-          console.log(`[${tool.name}] Access revoked for: ${h.url}`);
-          if (titleCleanup) { titleCleanup(); titleCleanup = null; }
-          setHandle(null);
-          setDocTitle("...");
-          setDocUnavailable(true);
-          setPendingDocUrl(h.url);
+        const h = handle();
+        if (h) {
+          if (!(await checkAccess(h.url))) {
+            console.log(`[${tool.name}] Access revoked for: ${h.url}`);
+            if (titleCleanup) { titleCleanup(); titleCleanup = null; }
+            setHandle(null);
+            setDocTitle("...");
+            setDocUnavailable(true);
+            setPendingDocUrl(h.url);
+          }
         }
-      }
-    });
+      });
+    }
 
     const hashUrl = getDocUrlFromHash();
     if (hashUrl) {
@@ -301,7 +325,7 @@ export function StandaloneApp<D>(props: { tool: ToolRegistration<D> }) {
       return;
     }
 
-    const existingUrl = localStorage.getItem(activeDocKey(tool.id, hexId));
+    const existingUrl = localStorage.getItem(activeDocKey(tool.id, identityHexId()));
     if (existingUrl) {
       console.log(`[${tool.name}] Found existing doc: ${existingUrl}`);
       await loadDoc(existingUrl);
@@ -604,18 +628,20 @@ export function StandaloneApp<D>(props: { tool: ToolRegistration<D> }) {
                   ? "Loading document..."
                   : ready()
                     ? "No document open"
-                    : "Initializing keyhive..."}
+                    : props.config?.legacyMode
+                      ? "Initializing..."
+                      : "Initializing keyhive..."}
             </div>
           }
         >
           {(h) => {
             const toolEl = document.createElement("div") as unknown as ToolElement;
-            toolEl.repo = repo;
+            toolEl.repo = repo as unknown as ToolElement["repo"];
             toolEl.style.height = "100%";
             return (
               <div style={{ height: "100%" }} ref={(el) => {
                 el.appendChild(toolEl);
-                tool.render(h as DocHandle<D>, toolEl);
+                tool.render(h as unknown as DocHandle<D>, toolEl);
               }} />
             );
           }}
@@ -626,7 +652,7 @@ export function StandaloneApp<D>(props: { tool: ToolRegistration<D> }) {
       <Show when={hive() && handle()}>
         <ShareModal
           isOpen={shareModalOpen()}
-          docUrl={handle()!.url}
+          docUrl={handle()!.url as AutomergeUrl}
           hive={hive()!}
           onClose={() => setShareModalOpen(false)}
         />

package/src/index.ts

@@ -18,6 +18,53 @@ export interface ToolRegistration<D = unknown> {
   render: (handle: DocHandle<D>, element: ToolElement) => (() => void);
 }
 
+/** Duck-typed doc handle — structurally compatible with automerge-repo DocHandle */
+export interface FrameDocHandle<D = unknown> {
+  url: string;
+  doc(): D | undefined;
+  whenReady(): Promise<unknown>;
+  on(event: string, cb: (...args: unknown[]) => void): void;
+  off(event: string, cb: (...args: unknown[]) => void): void;
+}
+
+/** Duck-typed repo — structurally compatible with automerge-repo Repo */
+export interface FrameRepo {
+  find<D = unknown>(url: string): FrameDocHandle<D>;
+  create<D = unknown>(initialValue: D): FrameDocHandle<D>;
+  delete(url: string): void;
+}
+
+export interface StandaloneFrameConfig {
+  /** When true, use plain automerge docs without keyhive. Default: false */
+  legacyMode?: boolean;
+  /** Pre-built repo for legacy mode. Required when legacyMode is true. */
+  repo?: FrameRepo;
+}
+
+export interface PluginDescription {
+  id: string;
+  type: string;
+  name: string;
+  icon?: string;
+}
+
+export interface ToolPlugin<D = unknown> extends PluginDescription {
+  type: "patchwork:tool";
+  supportedDatatypes: "*" | string[];
+  load: () => Promise<(handle: DocHandle<D>, element: ToolElement) => (() => void)>;
+}
+
+export interface DatatypePlugin<D = unknown> extends PluginDescription {
+  type: "patchwork:datatype";
+  load: () => Promise<{
+    init(doc: D, repo: Repo): void;
+    getTitle(doc: D): string;
+    setTitle?(doc: D, title: string): void;
+  }>;
+}
+
+export type Plugin<D = unknown> = ToolPlugin<D> | DatatypePlugin<D>;
+
 export { mountStandaloneApp } from "./mount.tsx";
 export { ShareModal } from "./share-modal.tsx";
 export { ConfirmModal } from "./confirm-modal.tsx";

package/src/mount.tsx

@@ -1,10 +1,48 @@
+import type { Repo } from "@automerge/automerge-repo";
 import { render } from "solid-js/web";
 import { StandaloneApp } from "./frame.tsx";
-import type { ToolRegistration } from "./index.ts";
+import type { ToolRegistration, StandaloneFrameConfig, Plugin, ToolPlugin, DatatypePlugin } from "./index.ts";
 
-export function mountStandaloneApp<D>(
+async function resolvePlugins<D>(plugins: Plugin<D>[]): Promise<ToolRegistration<D>> {
+  const toolPlugin = plugins.find((p): p is ToolPlugin<D> => p.type === "patchwork:tool");
+  const datatypePlugin = plugins.find((p): p is DatatypePlugin<D> => p.type === "patchwork:datatype");
+
+  if (!toolPlugin) throw new Error("No patchwork:tool plugin found in plugins array");
+  if (!datatypePlugin) throw new Error("No patchwork:datatype plugin found in plugins array");
+
+  const [renderFn, datatype] = await Promise.all([
+    toolPlugin.load(),
+    datatypePlugin.load(),
+  ]);
+
+  // Derive defaultTitle by initializing a scratch doc
+  const scratch = {} as D;
+  datatype.init(scratch, {} as Repo);
+  const defaultTitle = datatype.getTitle(scratch);
+
+  return {
+    id: toolPlugin.id,
+    name: toolPlugin.name,
+    defaultTitle,
+    init: datatype.init,
+    getTitle: datatype.getTitle,
+    setTitle: datatype.setTitle,
+    render: renderFn,
+  };
+}
+
+export async function mountStandaloneApp<D>(
   rootElement: HTMLElement,
-  tool: ToolRegistration<D>,
-): void {
-  render(() => <StandaloneApp tool={tool} />, rootElement);
+  toolOrPlugins: ToolRegistration<D> | Plugin<D>[],
+  config?: StandaloneFrameConfig,
+): Promise<void> {
+  let tool: ToolRegistration<D>;
+
+  if (Array.isArray(toolOrPlugins)) {
+    tool = await resolvePlugins(toolOrPlugins);
+  } else {
+    tool = toolOrPlugins;
+  }
+
+  render(() => <StandaloneApp tool={tool} config={config} />, rootElement);
 }