npm - @jtfmumm/patchwork-standalone-frame - Versions diffs - 0.3.0 → 0.3.1 - Mend

@jtfmumm/patchwork-standalone-frame 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,34 +1,184 @@
 # @jtfmumm/patchwork-standalone-frame
-A reusable standalone frame for patchwork tools. Provides keyhive initialization, repo setup, doc history, access control, top bar UI, and sharing modals.
+A standalone frame for patchwork tools. Provides repo setup, doc history, top bar UI, sharing modals, and optional keyhive access control.
-## Usage
+## Quick start: standalone app from an automerge tool
+This guide walks through building a standalone web app from a patchwork tool published as an automerge FolderDoc.
+### Prerequisites
+- Node.js 18+
+- pnpm
+### 1. Create the project
+```
+mkdir my-standalone-app && cd my-standalone-app
+pnpm init
+```
+### 2. Install dependencies
+```
+pnpm add @jtfmumm/patchwork-standalone-frame \
+  @automerge/automerge @automerge/automerge-repo \
+  @automerge/automerge-repo-network-websocket \
+  @automerge/automerge-repo-storage-indexeddb \
+  solid-js
+pnpm add -D @jtfmumm/automerge-deps @jtfmumm/patchwork-standalone-vite vite
+```
+### 3. Configure automerge-deps
+Create `automerge-deps.json` to specify the tool and sync server:
+```json
+{
+  "syncServers": ["wss://your-sync-server.example.com"],
+  "dependencies": [
+    { "name": "my-tool", "url": "automerge:<tool-url>" }
+  ]
+}
+```
+### 4. Fetch the tool
+```
+npx automerge-deps install
+```
+This downloads the tool's FolderDoc from the sync server and writes it to `node_modules/my-tool/`.
+### 5. Create the entry point
+**`src/main.ts`**
+```typescript
+import { Repo } from "@automerge/automerge-repo";
+import { IndexedDBStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb";
+import { BrowserWebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket";
+import { mountStandaloneApp } from "@jtfmumm/patchwork-standalone-frame";
+import { plugins } from "my-tool";
+const repo = new Repo({
+  storage: new IndexedDBStorageAdapter(),
+  network: [new BrowserWebSocketClientAdapter("wss://your-sync-server.example.com")],
+});
+const root = document.getElementById("root");
+if (root) {
+  mountStandaloneApp(root, plugins, { legacyMode: true, repo });
+}
+```
+### 6. Create the HTML shell
+**`index.html`**
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My Tool</title>
+    <style>
+      * { margin: 0; padding: 0; }
+      html, body, #root { height: 100%; }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+### 7. Configure Vite
+**`vite.config.ts`**
 ```typescript
-import { mountStandaloneApp, type ToolRegistration } from "@jtfmumm/patchwork-standalone-frame";
+import { defineConfig } from "vite";
+import { patchworkStandalone } from "@jtfmumm/patchwork-standalone-vite";
+export default defineConfig({
+  plugins: [patchworkStandalone({ tools: ["my-tool"] })],
+});
+```
+The `tools` option lists tool packages fetched by `automerge-deps`. This enables serving of the tool's code-split chunks during development.
+### 8. Add scripts to package.json
+```json
+{
+  "scripts": {
+    "fetch-deps": "automerge-deps install",
+    "dev": "vite",
+    "build": "pnpm fetch-deps && vite build",
+    "preview": "vite preview"
+  }
+}
+```
+### 9. Run
+```
+pnpm dev
+```
+For production builds:
+```
+pnpm build
+pnpm preview
+```
+## API
+### `mountStandaloneApp(root, toolOrPlugins, config?)`
+Mounts the standalone frame into a DOM element.
+- **`root`** — the HTML element to mount into
+- **`toolOrPlugins`** — either a `ToolRegistration<D>` object or a `Plugin<D>[]` array (patchwork plugin convention)
+- **`config`** — optional `StandaloneFrameConfig`
+### ToolRegistration
+For tools that don't use the patchwork plugin convention:
+```typescript
 const myTool: ToolRegistration<MyDoc> = {
-  id: "my-tool",            // matches @patchwork.type
-  name: "My Tool",          // display name
-  defaultTitle: "Untitled", // placeholder for new docs
-  init: (doc, repo) => {
-    // Initialize a blank document
-  },
+  id: "my-tool",
+  name: "My Tool",
+  defaultTitle: "Untitled",
+  init: (doc, repo) => { /* initialize a blank document */ },
   getTitle: (doc) => doc.title || "Untitled",
   setTitle: (doc, title) => { doc.title = title; },
-  isDocReady: (doc) => !!doc?.title,
-  render: (handle, element) => {
-    // Mount your UI into `element`, return a cleanup function
-  },
+  render: (handle, element) => { /* mount UI, return cleanup function */ },
 };
-const root = document.getElementById("root");
-if (root) mountStandaloneApp(root, myTool);
+mountStandaloneApp(root, myTool);
 ```
-## Sync server
+### Plugin convention
+Tools that export a `plugins` array with `patchwork:tool` and `patchwork:datatype` entries can be passed directly:
+```typescript
+import { plugins } from "my-tool";
+mountStandaloneApp(root, plugins);
+```
+### Legacy mode
+Pass `{ legacyMode: true, repo }` to use a plain automerge repo without keyhive. You construct and configure the repo yourself. This is the recommended approach for standalone deployments.
+### Keyhive mode (default)
+When `legacyMode` is not set, the frame initializes keyhive automatically, including WASM loading, repo creation, and access control. The sync server URL is resolved in this order:
-The sync server URL is resolved in this order:
 1. `VITE_SYNC_URL` environment variable
 2. `tool.syncUrl` from the registration
 3. `ws://localhost:3030` (default)

package/dist/index.d.ts CHANGED Viewed

@@ -34,6 +34,8 @@ export interface StandaloneFrameConfig {
     legacyMode?: boolean;
     /** Pre-built repo for legacy mode. Required when legacyMode is true. */
     repo?: FrameRepo;
+    /** WebSocket sync server URL. Overrides tool.syncUrl. */
+    syncUrl?: string;
 }
 export interface PluginDescription {
     id: string;

package/dist/index.js CHANGED Viewed

@@ -85,17 +85,17 @@ const Ze = {
   "border-radius": "4px",
   cursor: "pointer",
   "font-size": "12px"
-}, ze = {
+}, Ue = {
   "font-size": "13px",
   color: "#6b7280",
   margin: "16px 0 8px"
-}, Ue = {
+}, ze = {
   border: "none",
   "border-top": "1px solid #2a323c",
   margin: "12px 0"
 };
 function et(e) {
-  const [t, l] = x(""), [g, u] = x({}), [p, k] = x(!0), [$, v] = x(void 0), [N, z] = x(!1), [oe, H] = x(null), [A, ae] = x(null), [ee, te] = x(null), [G, be] = x("");
+  const [t, l] = x(""), [g, u] = x({}), [p, k] = x(!0), [$, v] = x(void 0), [N, U] = x(!1), [oe, H] = x(null), [A, ae] = x(null), [ee, te] = x(null), [G, be] = x("");
   ie(() => {
     if (!e.isOpen) return;
     let a = !1;
@@ -105,9 +105,9 @@ function et(e) {
       H(s.docIdFromAutomergeUrl(e.docUrl));
       const C = e.hive.active.individual.id;
       ae(C ? s.uint8ArrayToHex(C.toBytes()) : null);
-      const U = e.hive.syncServer;
-      if (U) {
-        const T = s.ContactCard.fromJson(U.contactCard.toJson());
+      const z = e.hive.syncServer;
+      if (z) {
+        const T = s.ContactCard.fromJson(z.contactCard.toJson());
         T && te(s.uint8ArrayToHex(T.individualId.bytes));
       }
       const P = s.Identifier.publicId();
@@ -132,10 +132,10 @@ function et(e) {
         return;
       }
       try {
-        const U = await e.hive.accessForDoc(C, a);
-        s || v(U ? U.toString() : void 0);
-      } catch (U) {
-        s || (console.error("[ShareModal] Error checking access:", U), v(void 0));
+        const z = await e.hive.accessForDoc(C, a);
+        s || v(z ? z.toString() : void 0);
+      } catch (z) {
+        s || (console.error("[ShareModal] Error checking access:", z), v(void 0));
       }
     })(), q(() => {
       s = !0;
@@ -165,18 +165,18 @@ function et(e) {
     a.preventDefault();
     const s = t().trim();
     if (s) {
-      z(!0);
+      U(!0);
       try {
-        const C = await ye(), U = C.ContactCard.fromJson(s);
-        if (!U) throw new Error("Invalid ContactCard JSON");
+        const C = await ye(), z = C.ContactCard.fromJson(s);
+        if (!z) throw new Error("Invalid ContactCard JSON");
         const P = C.Access.tryFromString("write");
         if (!P) throw new Error("Invalid access level");
-        await e.hive.addMemberToDoc(e.docUrl, U, P), l("");
+        await e.hive.addMemberToDoc(e.docUrl, z, P), l("");
       } catch (C) {
         console.error("[ShareModal]", C);
       } finally {
         const C = await de(e.hive, e.docUrl);
-        u(C), z(!1);
+        u(C), U(!1);
       }
     }
   }, he = async (a) => {
@@ -214,7 +214,7 @@ function et(e) {
       return e.isOpen;
     },
     get children() {
-      var a = Ge(), s = a.firstChild, C = s.firstChild, U = C.firstChild, P = U.nextSibling, T = C.nextSibling, L = T.firstChild, F = L.nextSibling, j = T.nextSibling, ce = j.firstChild;
+      var a = Ge(), s = a.firstChild, C = s.firstChild, z = C.firstChild, P = z.nextSibling, T = C.nextSibling, L = T.firstChild, F = L.nextSibling, j = T.nextSibling, ce = j.firstChild;
       return a.$$click = (i) => {
         i.target === i.currentTarget && e.onClose();
       }, s.$$click = (i) => i.stopPropagation(), P.$$click = () => e.onClose(), f(F, m(_, {
@@ -254,7 +254,7 @@ function et(e) {
         get children() {
           return [(() => {
             var i = Le();
-            return D((S) => E(i, Ue, S)), i;
+            return D((S) => E(i, ze, S)), i;
           })(), (() => {
             var i = We(), S = i.firstChild, K = S.nextSibling, V = K.firstChild;
             return i.addEventListener("submit", fe), S.$$input = (M) => l(M.currentTarget.value), f(V, () => N() ? "Adding..." : "Add Member"), D((M) => {
@@ -269,7 +269,7 @@ function et(e) {
             }), D(() => S.value = t()), i;
           })(), (() => {
             var i = Le();
-            return D((S) => E(i, Ue, S)), i;
+            return D((S) => E(i, ze, S)), i;
           })()];
         }
       }), j), f(j, m(_, {
@@ -316,7 +316,7 @@ function et(e) {
       }), null), D((i) => {
         var S = Ce, K = Ze, V = {
           ...ue
-        }, M = ze, n = ze;
+        }, M = Ue, n = Ue;
         return i.e = E(a, S, i.e), i.t = E(s, K, i.t), i.a = E(P, V, i.a), i.o = E(L, M, i.o), i.i = E(ce, n, i.i), i;
       }, {
         e: void 0,
@@ -346,10 +346,10 @@ function nt(e) {
       return t.$$click = (v) => {
         v.target === v.currentTarget && e.onCancel();
       }, f(g, () => e.title), f(u, () => e.message), k.$$click = () => e.onCancel(), $.$$click = () => e.onConfirm(), f($, () => e.confirmLabel ?? "Confirm"), D((v) => {
-        var N = Ce, z = {
+        var N = Ce, U = {
           ...Se
         };
-        return v.e = E(t, N, v.e), v.t = E(l, z, v.t), v;
+        return v.e = E(t, N, v.e), v.t = E(l, U, v.t), v;
       }, {
         e: void 0,
         t: void 0
@@ -379,14 +379,14 @@ function it(e) {
       return e.isOpen;
     },
     get children() {
-      var p = rt(), k = p.firstChild, $ = k.firstChild, v = $.nextSibling, N = v.nextSibling, z = N.firstChild, oe = z.nextSibling;
+      var p = rt(), k = p.firstChild, $ = k.firstChild, v = $.nextSibling, N = v.nextSibling, U = N.firstChild, oe = U.nextSibling;
       p.$$click = (A) => {
         A.target === A.currentTarget && e.onCancel();
       }, v.$$keydown = (A) => {
         A.key === "Enter" && u();
       }, v.$$input = (A) => l(A.currentTarget.value);
       var H = g;
-      return typeof H == "function" ? Ee(H, v) : g = v, z.$$click = () => e.onCancel(), oe.$$click = () => u(), D((A) => {
+      return typeof H == "function" ? Ee(H, v) : g = v, U.$$click = () => e.onCancel(), oe.$$click = () => u(), D((A) => {
         var ae = Ce, ee = {
           ...Se
         }, te = e.defaultTitle;
@@ -403,7 +403,7 @@ xe(["click", "input", "keydown"]);
 const ot = {};
 var at = /* @__PURE__ */ w('<div style="padding:8px 10px;color:#6b7280;font-style:italic">No documents yet'), lt = /* @__PURE__ */ w('<div style="position:absolute;top:34px;left:0;background:#191e24;border:1px solid #2a323c;border-radius:4px;max-height:400px;overflow-y:auto;min-width:280px;max-width:420px;z-index:1000;box-shadow:0 4px 12px rgba(0,0,0,0.4)">'), ct = /* @__PURE__ */ w('<button style="background:none;border:1px solid #2a323c;color:#edf2f7;font-size:13px;padding:4px 10px;border-radius:4px;cursor:pointer;white-space:nowrap">Share'), st = /* @__PURE__ */ w('<button title="Copy automerge URL"style="background:none;border:1px solid #2a323c;font-size:13px;padding:4px 10px;border-radius:4px;cursor:pointer;white-space:nowrap">'), dt = /* @__PURE__ */ w('<button style="background:none;border:1px solid #2a323c;font-size:13px;padding:4px 10px;border-radius:4px;cursor:pointer;white-space:nowrap">'), ut = /* @__PURE__ */ w('<button style="background:none;border:1px solid #944;color:#c66;font-size:13px;padding:4px 10px;border-radius:4px;cursor:pointer;white-space:nowrap">Remove Doc'), ft = /* @__PURE__ */ w('<div style=display:flex;flex-direction:column;height:100vh;background:#1d232a><div style="display:flex;align-items:center;height:52px;min-height:52px;background:#191e24;color:#edf2f7;font-size:14px;font-family:system-ui, sans-serif;padding:0 12px;border-bottom:1px solid #15191e;box-sizing:border-box"><button style="background:none;border:1px solid #2a323c;color:#edf2f7;font-size:13px;padding:4px 10px;border-radius:4px;cursor:pointer;flex-shrink:0;margin-right:12px;white-space:nowrap">+ New</button><input type=text placeholder="Paste automerge:… URL"style="background:#15191e;border:1px solid #2a323c;color:#edf2f7;font-size:13px;padding:4px 10px;border-radius:4px;width:200px;min-width:80px;flex-shrink:1;margin-right:12px;outline:none"><div data-doc-switcher style=position:relative;flex:1;min-width:120px><button style="background:none;border:none;color:#edf2f7;font-size:14px;cursor:pointer;padding:4px 8px;border-radius:4px;max-width:100%;display:flex;align-items:center;gap:4px"><span style=overflow:hidden;text-overflow:ellipsis;white-space:nowrap></span><span style=flex-shrink:0>▾</span></button></div><div style=display:flex;align-items:center;flex-shrink:0;gap:8px></div></div><div style=flex:1;min-height:0;overflow:hidden>'), ht = /* @__PURE__ */ w('<div style="padding:8px 12px;cursor:pointer;border-bottom:1px solid #15191e;overflow:hidden;text-overflow:ellipsis;white-space:nowrap"> <span style=color:#6b7280;font-size:12px>'), gt = /* @__PURE__ */ w('<div style="width:24px;height:24px;border:2px solid #2a323c;border-top-color:#6b7280;border-radius:50%;animation:spin 0.8s linear infinite">'), pt = /* @__PURE__ */ w('<div style="display:flex;flex-direction:column;align-items:center;justify-content:center;gap:12px;height:100%;background:#1d232a;font-family:system-ui, sans-serif;font-size:14px">'), mt = /* @__PURE__ */ w("<div style=height:100%>");
 function yt(e) {
-  const t = e.tool, [l, g] = x(null), [u, p] = x("..."), [k, $] = x([]), [v, N] = x(!1), [z, oe] = x(null), [H, A] = x(""), [ae, ee] = x(!1), [te, G] = x(!1), [be, Q] = x(!1), [le, fe] = x(!1), [he, ge] = x(!1), [ne, pe] = x(!1), [re, a] = x(!1), [s, C] = x(null), [U, P] = x(!1);
+  const t = e.tool, [l, g] = x(null), [u, p] = x("..."), [k, $] = x([]), [v, N] = x(!1), [U, oe] = x(null), [H, A] = x(""), [ae, ee] = x(!1), [te, G] = x(!1), [be, Q] = x(!1), [le, fe] = x(!1), [he, ge] = x(!1), [ne, pe] = x(!1), [re, a] = x(!1), [s, C] = x(null), [z, P] = x(!1);
   let T, L = null, F = 0;
   function j(n) {
     L && (L(), L = null);
@@ -419,7 +419,7 @@ function yt(e) {
     n.on("change", c), L = () => n.off("change", c);
   }
   async function ce(n) {
-    const r = z();
+    const r = U();
     if (!r) return !0;
     try {
       const {
@@ -479,7 +479,7 @@ function yt(e) {
     t.init(r, T), t.setTitle && t.setTitle(r, n), r["@patchwork"] = {
       type: t.id
     };
-    const h = z();
+    const h = U();
     let c;
     h ? (c = await T.create2(r), console.log(`[${t.name}] Created document (keyhive): ${c.url}`), await h.addSyncServerPullToDoc(c.url), await h.keyhiveStorage.saveKeyhiveWithHash(h.keyhive)) : (c = T.create(r), console.log(`[${t.name}] Created document (legacy): ${c.url}`)), g(c), se(c.url), localStorage.setItem(me(t.id, H()), c.url), j(c);
   }
@@ -493,7 +493,7 @@ function yt(e) {
     K(), T.delete(r), $(Ne(t.id, H(), r));
   }
   async function M() {
-    const n = z();
+    const n = U();
     if (n)
       try {
         const r = n.active.contactCard.toJson();
@@ -521,7 +521,7 @@ function yt(e) {
         BrowserWebSocketClientAdapter: b
       }, y] = await Promise.all([import("@automerge/automerge-repo"), import("@automerge/automerge-repo-storage-indexeddb"), import("@automerge/automerge-repo-network-websocket"), import("@automerge/automerge-repo-keyhive")]);
       y.initKeyhiveWasm();
-      const J = new c(`${t.id}-keyhive`), R = ot?.VITE_SYNC_URL, W = new b(R || t.syncUrl || "ws://localhost:3030"), o = `${t.id}-${Math.random().toString(36).slice(2)}`, d = await y.initializeAutomergeRepoKeyhive({
+      const J = new c(`${t.id}-keyhive`), R = ot?.VITE_SYNC_URL, W = new b(e.config?.syncUrl || R || t.syncUrl || "ws://localhost:3030"), o = `${t.id}-${Math.random().toString(36).slice(2)}`, d = await y.initializeAutomergeRepoKeyhive({
         storage: J,
         peerIdSuffix: o,
         networkAdapter: W,
@@ -620,7 +620,7 @@ function yt(e) {
       }
     }), null), f(R, m(_, {
       get when() {
-        return Z(() => !!l())() && z();
+        return Z(() => !!l())() && U();
       },
       get children() {
         var o = ct();
@@ -639,7 +639,7 @@ function yt(e) {
       }
     }), null), f(R, m(_, {
       get when() {
-        return z();
+        return U();
       },
       get children() {
         var o = dt();
@@ -663,14 +663,14 @@ function yt(e) {
           var o = pt();
           return f(o, m(_, {
             get when() {
-              return U() || !ne();
+              return z() || !ne();
             },
             get children() {
               return gt();
             }
           }), null), f(o, (() => {
             var d = Z(() => !!re());
-            return () => d() ? "Document unavailable: you may not have access" : Z(() => !!U())() ? "Loading document..." : Z(() => !!ne())() ? "No document open" : e.config?.legacyMode ? "Initializing..." : "Initializing keyhive...";
+            return () => d() ? "Document unavailable: you may not have access" : Z(() => !!z())() ? "Loading document..." : Z(() => !!ne())() ? "No document open" : e.config?.legacyMode ? "Initializing..." : "Initializing keyhive...";
           })(), null), D((d) => X(o, "color", re() ? "#c66" : "#6b7280")), o;
         })();
       },
@@ -685,7 +685,7 @@ function yt(e) {
       }
     })), f(n, m(_, {
       get when() {
-        return Z(() => !!z())() && l();
+        return Z(() => !!U())() && l();
       },
       get children() {
         return m(et, {
@@ -696,7 +696,7 @@ function yt(e) {
             return l().url;
           },
           get hive() {
-            return z();
+            return U();
           },
           onClose: () => ee(!1)
         });

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@jtfmumm/patchwork-standalone-frame",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Reusable standalone frame for patchwork tools with keyhive, doc history, and access control",
   "type": "module",
   "main": "./dist/index.js",

package/src/frame.tsx CHANGED Viewed

@@ -257,7 +257,7 @@ export function StandaloneApp<D>(props: { tool: ToolRegistration<D>; config?: St
       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"
+        props.config?.syncUrl || envSyncUrl || tool.syncUrl || "ws://localhost:3030"
       );
       const peerIdSuffix = `${tool.id}-${Math.random().toString(36).slice(2)}`;

package/src/index.ts CHANGED Viewed

@@ -39,6 +39,8 @@ export interface StandaloneFrameConfig {
   legacyMode?: boolean;
   /** Pre-built repo for legacy mode. Required when legacyMode is true. */
   repo?: FrameRepo;
+  /** WebSocket sync server URL. Overrides tool.syncUrl. */
+  syncUrl?: string;
 }
 export interface PluginDescription {