@jtfmumm/patchwork-standalone-frame 0.4.1 → 0.4.3

package/README.md

@@ -2,25 +2,146 @@
 
 A standalone frame for patchwork tools. Provides repo setup, doc history, top bar UI, sharing modals, and optional keyhive access control.
 
-## Quick start: standalone app from an automerge tool
+## Quick start
 
-This guide walks through building a standalone web app from a patchwork tool published as an automerge FolderDoc.
+Scaffold a new project:
 
-### Prerequisites
+```
+pnpm create @jtfmumm/patchwork-standalone
+```
+
+This prompts for your tool name, automerge URL, sync server, and mode (legacy or keyhive), then generates a ready-to-run project. After scaffolding:
 
-- Node.js 18+
-- pnpm
+```
+cd my-standalone-app
+pnpm install
+pnpm build
+```
 
-### 1. Create the project
+For development:
 
 ```
-mkdir my-standalone-app && cd my-standalone-app
-pnpm init
+pnpm dev
+```
+
+## How it works
+
+The standalone frame takes a patchwork tool and wraps it in an app shell with document management. You need three packages:
+
+- **`@jtfmumm/patchwork-standalone-frame`**: the frame itself
+- **`@jtfmumm/automerge-deps`**: fetches tool modules from a sync server at build time
+- **`@jtfmumm/patchwork-standalone-vite`**: Vite plugin handling build configuration
+
+Tools are published as automerge FolderDocs. `automerge-deps install` downloads them into `node_modules/` so they work like normal dependencies.
+
+## 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`
+
+### 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);
+```
+
+### ToolRegistration
+
+For tools that don't use the plugin convention:
+
+```typescript
+const myTool: ToolRegistration<MyDoc> = {
+  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; },
+  render: (handle, element) => { /* mount UI, return cleanup function */ },
+};
+
+mountStandaloneApp(root, myTool);
+```
+
+### Legacy mode
+
+Pass `{ legacyMode: true, repo }` to use a plain automerge repo without keyhive. You construct and configure the repo yourself.
+
+```typescript
+import { Repo } from "@automerge/automerge-repo";
+import { IndexedDBStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb";
+import { WebSocketClientAdapter } 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 WebSocketClientAdapter("wss://your-sync-server.example.com")],
+});
+
+const root = document.getElementById("root");
+if (root) {
+  mountStandaloneApp(root, plugins, { legacyMode: true, repo });
+}
+```
+
+### Keyhive mode (default)
+
+When `legacyMode` is not set, the frame initializes keyhive automatically, including WASM loading, repo creation, and access control. You don't need to create a repo yourself.
+
+Keyhive mode requires one additional dependency:
+
+```
+pnpm add @automerge/automerge-repo-keyhive
+```
+
+Then your entry point is simpler, with no repo setup needed:
+
+```typescript
+import { mountStandaloneApp } from "@jtfmumm/patchwork-standalone-frame";
+import { plugins } from "my-tool";
+
+const root = document.getElementById("root");
+if (root) {
+  mountStandaloneApp(root, plugins, {
+    syncUrl: "wss://your-keyhive-sync-server.example.com",
+  });
+}
 ```
 
-### 2. Install dependencies
+### Config options
+
+| Option | Description |
+|--------|-------------|
+| `legacyMode` | Use plain automerge docs without keyhive. Default: `false` |
+| `repo` | Pre-built repo for legacy mode. Required when `legacyMode` is `true` |
+| `syncUrl` | WebSocket sync server URL for keyhive mode |
+
+The sync server URL is resolved in this order:
+
+1. `config.syncUrl`
+2. `VITE_SYNC_URL` environment variable
+3. `tool.syncUrl` from the registration
+4. `ws://localhost:3030` (default)
+
+## Manual setup
+
+If you prefer to set up a project manually instead of using the scaffolder, here are the steps:
+
+### 1. Create the project and install dependencies
 
 ```
+mkdir my-standalone-app && cd my-standalone-app
+pnpm init
+
 pnpm add @jtfmumm/patchwork-standalone-frame \
   @automerge/automerge @automerge/automerge-repo \
   @automerge/automerge-repo-network-websocket \
@@ -30,7 +151,7 @@ pnpm add @jtfmumm/patchwork-standalone-frame \
 pnpm add -D @jtfmumm/automerge-deps @jtfmumm/patchwork-standalone-vite vite
 ```
 
-### 3. Configure automerge-deps
+### 2. Configure automerge-deps
 
 Create `automerge-deps.json` to specify the tool and sync server for fetching the tool:
 
@@ -43,17 +164,15 @@ Create `automerge-deps.json` to specify the tool and sync server for fetching th
 }
 ```
 
-### 4. Fetch the tool
+### 3. 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
+### 4. Create the entry point
 
-**`src/main.ts`**
+**`src/main.ts`** (legacy mode shown; see keyhive mode above for the alternative)
 ```typescript
 import { Repo } from "@automerge/automerge-repo";
 import { IndexedDBStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb";
@@ -72,7 +191,7 @@ if (root) {
 }
 ```
 
-### 6. Create the HTML shell
+### 5. Create the HTML shell
 
 **`index.html`**
 ```html
@@ -94,7 +213,7 @@ if (root) {
 </html>
 ```
 
-### 7. Configure Vite
+### 6. Configure Vite
 
 **`vite.config.ts`**
 ```typescript
@@ -106,9 +225,7 @@ export default defineConfig({
 });
 ```
 
-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
+### 7. Add scripts to package.json
 
 ```json
 {
@@ -121,7 +238,7 @@ The `tools` option lists tool packages fetched by `automerge-deps`. This enables
 }
 ```
 
-### 9. Run
+### 8. Run
 
 ```
 pnpm dev
@@ -133,71 +250,3 @@ 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",
-  name: "My Tool",
-  defaultTitle: "Untitled",
-  init: (doc, repo) => { /* initialize a blank document */ },
-  getTitle: (doc) => doc.title || "Untitled",
-  setTitle: (doc, title) => { doc.title = title; },
-  render: (handle, element) => { /* mount UI, return cleanup function */ },
-};
-
-mountStandaloneApp(root, myTool);
-```
-
-### 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.
-
-```typescript
-import { plugins } from "my-tool";
-
-mountStandaloneApp(root, plugins, {
-  syncUrl: "wss://your-keyhive-sync-server.example.com",
-});
-```
-
-### Config options
-
-| Option | Description |
-|--------|-------------|
-| `legacyMode` | Use plain automerge docs without keyhive. Default: `false` |
-| `repo` | Pre-built repo for legacy mode. Required when `legacyMode` is `true` |
-| `syncUrl` | WebSocket sync server URL for keyhive mode |
-
-The sync server URL is resolved in this order:
-
-1. `config.syncUrl`
-2. `VITE_SYNC_URL` environment variable
-3. `tool.syncUrl` from the registration
-4. `ws://localhost:3030` (default)

package/package.json

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