Merge pull request #1529 from garden-co/changeset-release/main

Version Packages

.github/workflows/pre-release.yml

@@ -1,7 +1,7 @@
 name: Pre-Publish tagged Pull Requests
 on:
   pull_request:
-    types: [opened, synchronize, reopened]
+    types: [opened, synchronize, reopened, labeled]
 
 jobs:
   pre-release:
@@ -99,4 +99,4 @@ jobs:
                 );
                 await logPublishInfo();
               }
-            }
+            }

CONTRIBUTING.md

@@ -36,7 +36,7 @@ We welcome all ideas! If you have suggestions, feel free to open an issue marked
 
 ### 5. Local Setup
 
-You'll need Node.js 20.x or 22.x installed (we're working on support for 23.x), and pnpm 9.x installed. If you're using nix, run `nix develop` to get a shell with the correct versions of everything installed.
+You'll need Node.js 22.x installed (we're working on support for 23.x), and pnpm 9.x installed. If you're using nix, run `nix develop` to get a shell with the correct versions of everything installed.
 
 1. **Clone the repository**:
    ```bash
@@ -54,6 +54,12 @@ You'll need Node.js 20.x or 22.x installed (we're working on support for 23.x),
    cd homepage && pnpm install
    ```
 
+4. **Go back to the project root**:
+
+   ```bash
+   cd ..
+   ```
+
 4. **Build the packages**:
 
    ```bash

biome.json

@@ -12,7 +12,9 @@
       "**/ios/**",
       "**/android/**",
       "packages/jazz-svelte/**",
-      "examples/*svelte*/**"
+      "examples/*svelte*/**",
+      "homepage/homepage/**",
+      "**/package.json"
     ]
   },
   "formatter": {
@@ -42,15 +44,6 @@
     }
   },
   "overrides": [
-    {
-      "include": ["**/package.json"],
-      "linter": {
-        "enabled": false
-      },
-      "formatter": {
-        "enabled": false
-      }
-    },
     {
       "include": ["packages/**/src/**"],
       "linter": {
@@ -61,21 +54,24 @@
       }
     },
     {
-      "include": ["packages/**/src/tests/**", "packages/**/src/test/**"],
+      "include": ["packages/cojson-storage*/**", "cojson-transport-ws/**"],
       "linter": {
+        "enabled": true,
         "rules": {
-          "correctness": {
-            "useImportExtensions": "off"
-          }
+          "recommended": true
         }
       }
     },
     {
-      "include": ["packages/cojson-storage-indexeddb/**"],
+      "include": ["packages/**/src/tests/**"],
       "linter": {
-        "enabled": true,
         "rules": {
-          "recommended": true,
+          "correctness": {
+            "useImportExtensions": "off"
+          },
+          "style": {
+            "noNonNullAssertion": "off"
+          },
           "suspicious": {
             "noExplicitAny": "info"
           }

examples/chat-rn-clerk/CHANGELOG.md

@@ -1,5 +1,57 @@
 # chat-rn-clerk
 
+## 1.0.79
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react-native@0.10.14
+  - jazz-react-native-auth-clerk@0.10.14
+  - jazz-react-native-media-images@0.10.14
+
+## 1.0.78
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-react-native@0.10.13
+  - jazz-react-native-auth-clerk@0.10.13
+  - jazz-react-native-media-images@0.10.13
+
+## 1.0.77
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react-native@0.10.12
+  - jazz-react-native-auth-clerk@0.10.12
+  - jazz-react-native-media-images@0.10.12
+
+## 1.0.76
+
+### Patch Changes
+
+- Updated dependencies [5a54e4a]
+  - jazz-react-native@0.10.11
+  - jazz-react-native-auth-clerk@0.10.11
+
+## 1.0.75
+
+### Patch Changes
+
+- Updated dependencies [3405d8f]
+  - jazz-react-native@0.10.10
+  - jazz-react-native-auth-clerk@0.10.10
+
+## 1.0.74
+
+### Patch Changes
+
+- jazz-react-native-auth-clerk@0.10.9
+
 ## 1.0.73
 
 ### Patch Changes

examples/chat-rn-clerk/app/_layout.tsx

@@ -1,5 +1,6 @@
 import "../global.css";
 import { ClerkLoaded, ClerkProvider } from "@clerk/clerk-expo";
+import { secureStore } from "@clerk/clerk-expo/secure-store";
 import { useFonts } from "expo-font";
 import { Slot } from "expo-router";
 import * as SplashScreen from "expo-splash-screen";
@@ -33,7 +34,11 @@ export default function RootLayout() {
   }
 
   return (
-    <ClerkProvider tokenCache={tokenCache} publishableKey={publishableKey}>
+    <ClerkProvider
+      tokenCache={tokenCache}
+      publishableKey={publishableKey}
+      __experimental_resourceCache={secureStore}
+    >
       <ClerkLoaded>
         <JazzAndAuth>
           <Slot />

examples/chat-rn-clerk/package.json

@@ -1,7 +1,7 @@
 {
   "name": "chat-rn-clerk",
   "main": "index.js",
-  "version": "1.0.73",
+  "version": "1.0.79",
   "scripts": {
     "build": "expo export -p ios",
     "start": "expo start",

examples/chat-rn/CHANGELOG.md

@@ -1,5 +1,43 @@
 # chat-rn
 
+## 1.0.75
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react-native@0.10.14
+
+## 1.0.74
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-react-native@0.10.13
+
+## 1.0.73
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react-native@0.10.12
+
+## 1.0.72
+
+### Patch Changes
+
+- Updated dependencies [5a54e4a]
+  - jazz-react-native@0.10.11
+
+## 1.0.71
+
+### Patch Changes
+
+- Updated dependencies [3405d8f]
+  - jazz-react-native@0.10.10
+
 ## 1.0.70
 
 ### Patch Changes

examples/chat-rn/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chat-rn",
-  "version": "1.0.70",
+  "version": "1.0.75",
   "main": "index.js",
   "scripts": {
     "build": "expo export -p ios",
@@ -35,8 +35,6 @@
     "react": "^18.3.1",
     "react-native": "~0.76.3",
     "react-native-get-random-values": "^1.11.0",
-    "react-native-nitro-modules": "0.21.0",
-    "react-native-quick-crypto": "1.0.0-beta.12",
     "react-native-safe-area-context": "4.12.0",
     "react-native-screens": "4.1.0",
     "react-native-url-polyfill": "^2.0.0",

examples/chat-rn/src/App.tsx

@@ -9,7 +9,7 @@ import * as Linking from "expo-linking";
 import React, { StrictMode, useEffect, useState } from "react";
 import HandleInviteScreen from "./invite";
 
-import { JazzProvider, RNQuickCrypto } from "jazz-react-native";
+import { JazzProvider } from "jazz-react-native";
 import { apiKey } from "./apiKey";
 import ChatScreen from "./chat";
 
@@ -50,7 +50,6 @@ function App() {
         sync={{
           peer: `wss://cloud.jazz.tools/?key=${apiKey}`,
         }}
-        CryptoProvider={RNQuickCrypto}
       >
         <NavigationContainer linking={linking} ref={navigationRef}>
           <Stack.Navigator initialRouteName={initialRoute}>

examples/chat-vue/CHANGELOG.md

@@ -1,5 +1,40 @@
 # chat-vue
 
+## 0.0.61
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-browser@0.10.14
+  - jazz-vue@0.10.14
+
+## 0.0.60
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-browser@0.10.13
+  - jazz-vue@0.10.13
+
+## 0.0.59
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-vue@0.10.12
+  - jazz-browser@0.10.12
+
+## 0.0.58
+
+### Patch Changes
+
+- Updated dependencies [834203f]
+  - jazz-browser@0.10.9
+  - jazz-vue@0.10.9
+
 ## 0.0.57
 
 ### Patch Changes

examples/chat-vue/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chat-vue",
-  "version": "0.0.57",
+  "version": "0.0.61",
   "private": true,
   "type": "module",
   "scripts": {

examples/chat/CHANGELOG.md

@@ -1,5 +1,39 @@
 # jazz-example-chat
 
+## 0.0.157
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react@0.10.14
+  - jazz-browser-media-images@0.10.14
+
+## 0.0.156
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-browser-media-images@0.10.13
+  - jazz-react@0.10.13
+
+## 0.0.155
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react@0.10.12
+  - jazz-browser-media-images@0.10.12
+
+## 0.0.154
+
+### Patch Changes
+
+- jazz-browser-media-images@0.10.9
+- jazz-react@0.10.9
+
 ## 0.0.153
 
 ### Patch Changes

examples/chat/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jazz-example-chat",
   "private": true,
-  "version": "0.0.153",
+  "version": "0.0.157",
   "type": "module",
   "scripts": {
     "dev": "vite",

examples/clerk/CHANGELOG.md

@@ -1,5 +1,39 @@
 # minimal-auth-clerk
 
+## 0.0.56
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react@0.10.14
+  - jazz-react-auth-clerk@0.10.14
+
+## 0.0.55
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-react@0.10.13
+  - jazz-react-auth-clerk@0.10.13
+
+## 0.0.54
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react@0.10.12
+  - jazz-react-auth-clerk@0.10.12
+
+## 0.0.53
+
+### Patch Changes
+
+- jazz-react@0.10.9
+- jazz-react-auth-clerk@0.10.9
+
 ## 0.0.52
 
 ### Patch Changes

examples/clerk/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clerk",
   "private": true,
-  "version": "0.0.52",
+  "version": "0.0.56",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -13,7 +13,7 @@
   "dependencies": {
     "@clerk/clerk-react": "^5.4.1",
     "jazz-react": "workspace:*",
-    "jazz-react-auth-clerk": "workspace:0.10.8",
+    "jazz-react-auth-clerk": "workspace:0.10.14",
     "jazz-tools": "workspace:*",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"

examples/file-share-svelte/CHANGELOG.md

@@ -1,5 +1,35 @@
 # file-share-svelte
 
+## 0.0.41
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-svelte@0.10.14
+
+## 0.0.40
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-svelte@0.10.13
+
+## 0.0.39
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-svelte@0.10.12
+  - jazz-tools@0.10.12
+
+## 0.0.38
+
+### Patch Changes
+
+- jazz-svelte@0.10.9
+
 ## 0.0.37
 
 ### Patch Changes

examples/file-share-svelte/package.json

@@ -1,6 +1,6 @@
 {
   "name": "file-share-svelte",
-  "version": "0.0.37",
+  "version": "0.0.41",
   "private": true,
   "type": "module",
   "scripts": {

examples/form/CHANGELOG.md

@@ -1,5 +1,39 @@
 # form
 
+## 0.0.52
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react@0.10.14
+  - jazz-browser-media-images@0.10.14
+
+## 0.0.51
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-browser-media-images@0.10.13
+  - jazz-react@0.10.13
+
+## 0.0.50
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react@0.10.12
+  - jazz-browser-media-images@0.10.12
+
+## 0.0.49
+
+### Patch Changes
+
+- jazz-browser-media-images@0.10.9
+- jazz-react@0.10.9
+
 ## 0.0.48
 
 ### Patch Changes

examples/form/package.json

@@ -1,7 +1,7 @@
 {
   "name": "form",
   "private": true,
-  "version": "0.0.48",
+  "version": "0.0.52",
   "type": "module",
   "scripts": {
     "dev": "vite",

examples/image-upload/CHANGELOG.md

@@ -1,5 +1,39 @@
 # image-upload
 
+## 0.0.54
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react@0.10.14
+  - jazz-browser-media-images@0.10.14
+
+## 0.0.53
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-browser-media-images@0.10.13
+  - jazz-react@0.10.13
+
+## 0.0.52
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react@0.10.12
+  - jazz-browser-media-images@0.10.12
+
+## 0.0.51
+
+### Patch Changes
+
+- jazz-browser-media-images@0.10.9
+- jazz-react@0.10.9
+
 ## 0.0.50
 
 ### Patch Changes

examples/image-upload/package.json

@@ -1,7 +1,7 @@
 {
   "name": "image-upload",
   "private": true,
-  "version": "0.0.50",
+  "version": "0.0.54",
   "type": "module",
   "scripts": {
     "dev": "vite",

examples/inspector/src/viewer/new-app.tsx

@@ -83,7 +83,10 @@ export default function CoJsonViewerApp() {
 
   const addAccount = (id: RawAccountID, secret: AgentSecret) => {
     const newAccount = { id, secret };
-    setAccounts([...accounts, newAccount]);
+    const accountExists = accounts.some((account) => account.id === id);
+    if (!accountExists) {
+      setAccounts([...accounts, newAccount]);
+    }
     setCurrentAccount(newAccount);
   };
 

examples/music-player/CHANGELOG.md

@@ -1,5 +1,38 @@
 # jazz-example-musicplayer
 
+## 0.0.78
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-inspector@0.10.11
+  - jazz-react@0.10.14
+
+## 0.0.77
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-inspector@0.10.10
+  - jazz-react@0.10.13
+
+## 0.0.76
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-inspector@0.10.9
+  - jazz-react@0.10.12
+
+## 0.0.75
+
+### Patch Changes
+
+- jazz-react@0.10.9
+
 ## 0.0.74
 
 ### Patch Changes

examples/music-player/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jazz-example-music-player",
   "private": true,
-  "version": "0.0.74",
+  "version": "0.0.78",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -22,8 +22,8 @@
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.0.0",
     "jazz-inspector": "workspace:*",
-    "jazz-react": "workspace:0.10.8",
-    "jazz-tools": "workspace:0.10.8",
+    "jazz-react": "workspace:0.10.14",
+    "jazz-tools": "workspace:0.10.14",
     "lucide-react": "^0.274.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",

examples/organization/CHANGELOG.md

@@ -1,5 +1,35 @@
 # organization
 
+## 0.0.50
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react@0.10.14
+
+## 0.0.49
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-react@0.10.13
+
+## 0.0.48
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react@0.10.12
+
+## 0.0.47
+
+### Patch Changes
+
+- jazz-react@0.10.9
+
 ## 0.0.46
 
 ### Patch Changes

examples/organization/package.json

@@ -1,7 +1,7 @@
 {
   "name": "organization",
   "private": true,
-  "version": "0.0.46",
+  "version": "0.0.50",
   "type": "module",
   "scripts": {
     "dev": "vite",

examples/passkey-svelte/CHANGELOG.md

@@ -1,5 +1,30 @@
 # passkey-svelte
 
+## 0.0.45
+
+### Patch Changes
+
+- jazz-svelte@0.10.14
+
+## 0.0.44
+
+### Patch Changes
+
+- jazz-svelte@0.10.13
+
+## 0.0.43
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-svelte@0.10.12
+
+## 0.0.42
+
+### Patch Changes
+
+- jazz-svelte@0.10.9
+
 ## 0.0.41
 
 ### Patch Changes

examples/passkey-svelte/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passkey-svelte",
-  "version": "0.0.41",
+  "version": "0.0.45",
   "type": "module",
   "private": true,
   "scripts": {

examples/passkey/CHANGELOG.md

@@ -1,5 +1,35 @@
 # minimal-auth-passkey
 
+## 0.0.55
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react@0.10.14
+
+## 0.0.54
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-react@0.10.13
+
+## 0.0.53
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react@0.10.12
+
+## 0.0.52
+
+### Patch Changes
+
+- jazz-react@0.10.9
+
 ## 0.0.51
 
 ### Patch Changes

examples/passkey/package.json

@@ -1,7 +1,7 @@
 {
   "name": "passkey",
   "private": true,
-  "version": "0.0.51",
+  "version": "0.0.55",
   "type": "module",
   "scripts": {
     "dev": "vite",

examples/passphrase/CHANGELOG.md

@@ -1,5 +1,35 @@
 # passphrase
 
+## 0.0.52
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react@0.10.14
+
+## 0.0.51
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-react@0.10.13
+
+## 0.0.50
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react@0.10.12
+
+## 0.0.49
+
+### Patch Changes
+
+- jazz-react@0.10.9
+
 ## 0.0.48
 
 ### Patch Changes

examples/passphrase/package.json

@@ -1,7 +1,7 @@
 {
   "name": "passphrase",
   "private": true,
-  "version": "0.0.48",
+  "version": "0.0.52",
   "type": "module",
   "scripts": {
     "dev": "vite",

examples/passphrase/src/index.css

@@ -66,3 +66,72 @@ main {
   margin: 0 auto;
   text-align: center;
 }
+
+.auth-container {
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: #f3f4f6;
+}
+
+.auth-card {
+  background-color: white;
+  padding: 2rem;
+  border-radius: 0.5rem;
+  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px
+    rgba(0, 0, 0, 0.06);
+  width: 28rem;
+}
+
+.auth-button-primary,
+.auth-button-secondary {
+  width: 100%;
+  padding: 0.5rem 1rem;
+  border-radius: 0.25rem;
+  font-weight: bold;
+  cursor: pointer;
+  margin-bottom: 1rem;
+}
+
+.auth-button-primary {
+  background-color: black;
+  color: white;
+  border: none;
+}
+
+.auth-button-secondary {
+  background-color: white;
+  color: black;
+  border: 1px solid black;
+}
+
+.auth-heading {
+  color: black;
+  font-size: 1.5rem;
+  font-weight: bold;
+  text-align: center;
+  margin-bottom: 1rem;
+}
+
+.auth-textarea {
+  width: 100%;
+  padding: 0.5rem;
+  border: 1px solid #d1d5db;
+  border-radius: 0.25rem;
+  margin-bottom: 1rem;
+  box-sizing: border-box;
+}
+
+.auth-description {
+  font-size: 0.875rem;
+  color: #4b5563;
+  text-align: center;
+  margin-bottom: 1rem;
+}
+
+.auth-button-group {
+  display: flex;
+  justify-content: space-between;
+  gap: 1rem;
+}

examples/passphrase/src/main.tsx

@@ -1,10 +1,142 @@
-import { JazzProvider, PassphraseAuthBasicUI } from "jazz-react";
-import { StrictMode } from "react";
+import { JazzProvider, usePassphraseAuth } from "jazz-react";
+import { StrictMode, useState } from "react";
 import { createRoot } from "react-dom/client";
 import App from "./App.tsx";
 import "./index.css";
 import { wordlist } from "./wordlist.ts";
 
+function PassphraseAuthBasicUI(props: {
+  appName: string;
+  wordlist: string[];
+  children?: React.ReactNode;
+}) {
+  const auth = usePassphraseAuth({
+    wordlist: props.wordlist,
+  });
+
+  const [step, setStep] = useState<"initial" | "create" | "login">("initial");
+  const [loginPassphrase, setLoginPassphrase] = useState("");
+  const [isCopied, setIsCopied] = useState(false);
+  const [currentPassphrase, setCurrentPassphrase] = useState(() =>
+    auth.generateRandomPassphrase(),
+  );
+
+  if (auth.state === "signedIn") {
+    return props.children ?? null;
+  }
+
+  const handleCreateAccount = async () => {
+    setStep("create");
+  };
+
+  const handleLogin = () => {
+    setStep("login");
+  };
+
+  const handleReroll = () => {
+    const newPassphrase = auth.generateRandomPassphrase();
+    setCurrentPassphrase(newPassphrase);
+    setIsCopied(false);
+  };
+
+  const handleBack = () => {
+    setStep("initial");
+    setLoginPassphrase("");
+  };
+
+  const handleCopy = async () => {
+    await navigator.clipboard.writeText(auth.passphrase);
+    setIsCopied(true);
+  };
+
+  const handleLoginSubmit = async () => {
+    await auth.logIn(loginPassphrase);
+    setStep("initial");
+    setLoginPassphrase("");
+  };
+
+  const handleNext = async () => {
+    await auth.registerNewAccount(currentPassphrase, "My Account");
+    setStep("initial");
+    setLoginPassphrase("");
+  };
+
+  return (
+    <div className="auth-container">
+      <div className="auth-card">
+        {step === "initial" && (
+          <div>
+            <h1 className="auth-heading">{props.appName}</h1>
+            <button
+              onClick={handleCreateAccount}
+              className="auth-button-primary"
+            >
+              Create new account
+            </button>
+            <button onClick={handleLogin} className="auth-button-secondary">
+              Log in
+            </button>
+          </div>
+        )}
+
+        {step === "create" && (
+          <>
+            <h1 className="auth-heading">Your Passphrase</h1>
+            <p className="auth-description">
+              Please copy and store this passphrase somewhere safe. You'll need
+              it to log in.
+            </p>
+            <textarea
+              readOnly
+              value={currentPassphrase}
+              className="auth-textarea"
+              rows={5}
+            />
+            <button onClick={handleCopy} className="auth-button-primary">
+              {isCopied ? "Copied!" : "Copy"}
+            </button>
+            <div className="auth-button-group">
+              <button onClick={handleBack} className="auth-button-secondary">
+                Back
+              </button>
+              <button onClick={handleReroll} className="auth-button-secondary">
+                Generate New Passphrase
+              </button>
+              <button onClick={handleNext} className="auth-button-primary">
+                Register
+              </button>
+            </div>
+          </>
+        )}
+
+        {step === "login" && (
+          <div>
+            <h1 className="auth-heading">Log In</h1>
+            <textarea
+              value={loginPassphrase}
+              onChange={(e) => setLoginPassphrase(e.target.value)}
+              placeholder="Enter your passphrase"
+              className="auth-textarea"
+              rows={5}
+            />
+            <div className="auth-button-group">
+              <button onClick={handleBack} className="auth-button-secondary">
+                Back
+              </button>
+              <button
+                onClick={handleLoginSubmit}
+                className="auth-button-primary"
+              >
+                Log In
+              </button>
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
 function JazzAndAuth({ children }: { children: React.ReactNode }) {
   return (
     <JazzProvider

examples/password-manager/CHANGELOG.md

@@ -1,5 +1,35 @@
 # jazz-password-manager
 
+## 0.0.76
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react@0.10.14
+
+## 0.0.75
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-react@0.10.13
+
+## 0.0.74
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react@0.10.12
+
+## 0.0.73
+
+### Patch Changes
+
+- jazz-react@0.10.9
+
 ## 0.0.72
 
 ### Patch Changes

examples/password-manager/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jazz-password-manager",
   "private": true,
-  "version": "0.0.72",
+  "version": "0.0.76",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -12,8 +12,8 @@
     "clean-install": "rm -rf node_modules pnpm-lock.yaml && pnpm install"
   },
   "dependencies": {
-    "jazz-react": "workspace:0.10.8",
-    "jazz-tools": "workspace:0.10.8",
+    "jazz-react": "workspace:0.10.14",
+    "jazz-tools": "workspace:0.10.14",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-hook-form": "^7.41.5",

examples/pets/CHANGELOG.md

@@ -1,5 +1,39 @@
 # jazz-example-pets
 
+## 0.0.174
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react@0.10.14
+  - jazz-browser-media-images@0.10.14
+
+## 0.0.173
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-browser-media-images@0.10.13
+  - jazz-react@0.10.13
+
+## 0.0.172
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react@0.10.12
+  - jazz-browser-media-images@0.10.12
+
+## 0.0.171
+
+### Patch Changes
+
+- jazz-browser-media-images@0.10.9
+- jazz-react@0.10.9
+
 ## 0.0.170
 
 ### Patch Changes

examples/pets/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jazz-example-pets",
   "private": true,
-  "version": "0.0.170",
+  "version": "0.0.174",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -19,9 +19,9 @@
     "@radix-ui/react-toast": "^1.1.4",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.0.0",
-    "jazz-browser-media-images": "workspace:0.10.8",
-    "jazz-react": "workspace:0.10.8",
-    "jazz-tools": "workspace:0.10.8",
+    "jazz-browser-media-images": "workspace:0.10.14",
+    "jazz-react": "workspace:0.10.14",
+    "jazz-tools": "workspace:0.10.14",
     "lucide-react": "^0.274.0",
     "qrcode": "^1.5.3",
     "react": "^18.3.1",
@@ -41,7 +41,7 @@
     "@vitejs/plugin-react-swc": "^3.3.2",
     "autoprefixer": "^10.4.20",
     "is-ci": "^3.0.1",
-    "jazz-run": "workspace:0.10.8",
+    "jazz-run": "workspace:0.10.14",
     "postcss": "^8.4.27",
     "tailwindcss": "^3.4.17",
     "typescript": "~5.6.2",

examples/reactions/CHANGELOG.md

@@ -1,5 +1,39 @@
 # reactions
 
+## 0.0.54
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react@0.10.14
+  - jazz-browser-media-images@0.10.14
+
+## 0.0.53
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-browser-media-images@0.10.13
+  - jazz-react@0.10.13
+
+## 0.0.52
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react@0.10.12
+  - jazz-browser-media-images@0.10.12
+
+## 0.0.51
+
+### Patch Changes
+
+- jazz-browser-media-images@0.10.9
+- jazz-react@0.10.9
+
 ## 0.0.50
 
 ### Patch Changes

examples/reactions/package.json

@@ -1,7 +1,7 @@
 {
   "name": "reactions",
   "private": true,
-  "version": "0.0.50",
+  "version": "0.0.54",
   "type": "module",
   "scripts": {
     "dev": "vite",

examples/todo-vue/CHANGELOG.md

@@ -1,5 +1,40 @@
 # todo-vue
 
+## 0.0.59
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-browser@0.10.14
+  - jazz-vue@0.10.14
+
+## 0.0.58
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-browser@0.10.13
+  - jazz-vue@0.10.13
+
+## 0.0.57
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-vue@0.10.12
+  - jazz-browser@0.10.12
+
+## 0.0.56
+
+### Patch Changes
+
+- Updated dependencies [834203f]
+  - jazz-browser@0.10.9
+  - jazz-vue@0.10.9
+
 ## 0.0.55
 
 ### Patch Changes

examples/todo-vue/package.json

@@ -1,6 +1,6 @@
 {
   "name": "todo-vue",
-  "version": "0.0.55",
+  "version": "0.0.59",
   "private": true,
   "type": "module",
   "scripts": {

examples/todo/CHANGELOG.md

@@ -1,5 +1,35 @@
 # jazz-example-todo
 
+## 0.0.173
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react@0.10.14
+
+## 0.0.172
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-react@0.10.13
+
+## 0.0.171
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react@0.10.12
+
+## 0.0.170
+
+### Patch Changes
+
+- jazz-react@0.10.9
+
 ## 0.0.169
 
 ### Patch Changes

examples/todo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jazz-example-todo",
   "private": true,
-  "version": "0.0.169",
+  "version": "0.0.173",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -16,8 +16,8 @@
     "@radix-ui/react-toast": "^1.1.4",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.0.0",
-    "jazz-react": "workspace:0.10.8",
-    "jazz-tools": "workspace:0.10.8",
+    "jazz-react": "workspace:0.10.14",
+    "jazz-tools": "workspace:0.10.14",
     "lucide-react": "^0.274.0",
     "qrcode": "^1.5.3",
     "react": "^18.3.1",

examples/version-history/CHANGELOG.md

@@ -1,5 +1,35 @@
 # version-history
 
+## 0.0.51
+
+### Patch Changes
+
+- Updated dependencies [75211e3]
+  - jazz-tools@0.10.14
+  - jazz-react@0.10.14
+
+## 0.0.50
+
+### Patch Changes
+
+- Updated dependencies [07feedd]
+  - jazz-tools@0.10.13
+  - jazz-react@0.10.13
+
+## 0.0.49
+
+### Patch Changes
+
+- Updated dependencies [4612e05]
+  - jazz-tools@0.10.12
+  - jazz-react@0.10.12
+
+## 0.0.48
+
+### Patch Changes
+
+- jazz-react@0.10.9
+
 ## 0.0.47
 
 ### Patch Changes

examples/version-history/package.json

@@ -1,7 +1,7 @@
 {
   "name": "version-history",
   "private": true,
-  "version": "0.0.47",
+  "version": "0.0.51",
   "type": "module",
   "scripts": {
     "dev": "vite",

homepage/homepage/app/(docs)/api-reference/page.tsx

@@ -1,8 +1,16 @@
 import { packages } from "@/lib/packages";
 import { clsx } from "clsx";
 import { Icon } from "gcmp-design-system/src/app/components/atoms/Icon";
+import type { Metadata } from "next";
 import Link from "next/link";
 
+export const metadata: Metadata = {
+  title: "API reference",
+  openGraph: {
+    title: "API reference",
+  },
+};
+
 const CardHeading = ({
   children,
   className,

homepage/homepage/app/(docs)/docs/[framework]/(others)/page.mdx

@@ -1,5 +1,12 @@
 import { CodeGroup, ContentByFramework, JazzLogo } from '@/components/forMdx'
 
+export const metadata = {
+  title: "Learn some Jazz",
+  openGraph: {
+    title: "Learn some Jazz",
+  },
+};
+
 # Learn some <span className="sr-only">Jazz</span> <JazzLogo className="h-[41px] -ml-0.5 -mt-[3px] inline" />
 
 Welcome to the Jazz documentation!

homepage/homepage/app/(docs)/docs/[framework]/[...slug]/authentication/overview.mdx

@@ -211,7 +211,7 @@ The clerk provider is not built into `jazz-react` and needs the `jazz-react-auth
 </ContentByFramework>
 
 <ContentByFramework framework="react-native">
-The clerk provider is not built into `jazz-react-native` and needs the `jazz-react-native-auth-clerk` package to be installed.
+The clerk provider is not built into `jazz-react-native` and needs the `jazz-react-native-auth-clerk` package to be installed.  Note the `__experimental_resourceCache` option.  This helps render Clerk components when offline.
 </ContentByFramework>
 
 After installing the package you can use the `JazzProviderWithClerk` component to wrap your app:
@@ -249,6 +249,7 @@ createRoot(document.getElementById("root")!).render(
 <CodeGroup>
 ```tsx
 import { JazzProviderWithClerk } from "jazz-react-native-auth-clerk";
+import { secureStore } from "@clerk/clerk-expo/secure-store";
 
 function JazzAndAuth({ children }: { children: React.ReactNode }) {
   const clerk = useClerk();
@@ -275,7 +276,11 @@ export default function RootLayout() {
   }
 
   return (
-    <ClerkProvider tokenCache={tokenCache} publishableKey={publishableKey}>
+    <ClerkProvider
+      tokenCache={tokenCache}
+      publishableKey={publishableKey}
+      __experimental_resourceCache={secureStore}
+    >
       <ClerkLoaded>
         <JazzAndAuth>
           <Slot />
@@ -380,7 +385,7 @@ export async function onAnonymousAccountDiscarded(
 ```
 </CodeGroup>
 
-To see how this works in reality we suggest you to try 
+To see how this works in reality we suggest you to try
 to upload a song in the [music player demo](https://music-demo.jazz.tools/) and then
 try to log in with an existing account.
 

homepage/homepage/app/(docs)/docs/[framework]/[...slug]/guide/react.mdx

@@ -442,11 +442,11 @@ All we have to do is create a new group to own each new issue and add "everyone"
 import { useState } from "react"; // old
 import { Issue } from "./schema"; // old
 import { IssueComponent } from "./components/Issue.tsx"; // old
-import { useCoState } from "jazz-react"; // old
+import { useAccount, useCoState } from "jazz-react";
 import { ID, Group } from "jazz-tools"
 // old
 function App() { // old
-    const { me } = useAccount(); // old
+    const { me } = useAccount();
     const [issueID, setIssueID] = useState<ID<Issue> | undefined>(// old
         (window.location.search?.replace("?issue=", "") || undefined) as ID<Issue> | undefined,// old
     ); // old
@@ -665,7 +665,7 @@ export function ProjectComponent({ projectID }: { projectID: ID<Project> }) {//
 
 The loading-depth spec `{ issues: [{}] }` means "in `Project`, load `issues` and load each item in `issues` shallowly". (Since an `Issue` doesn't have any further references, "shallowly" actually means all its properties will be available).
 
--   Now, we can get rid of a lot of coniditional accesses because we know that once `project` is loaded, `project.issues` and each `Issue` in it will be loaded as well.
+-   Now, we can get rid of a lot of conditional accesses because we know that once `project` is loaded, `project.issues` and each `Issue` in it will be loaded as well.
 -   This also results in only one rerender and visual update when everything is loaded, which is faster (especially for long lists) and gives you more control over the loading UX.
 
 {/* TODO: explain about not loaded vs not set/defined and `_refs` basics */}

homepage/homepage/app/(docs)/docs/[framework]/[...slug]/page.tsx

@@ -6,6 +6,38 @@ import { Framework, frameworks } from "@/lib/framework";
 import type { Toc } from "@stefanprobst/rehype-extract-toc";
 import { Prose } from "gcmp-design-system/src/app/components/molecules/Prose";
 
+async function getMdxSource(slugPath: string, framework: string) {
+  try {
+    return await import(`./${slugPath}.mdx`);
+  } catch (error) {
+    return await import(`./${slugPath}/${framework}.mdx`);
+  }
+}
+
+export async function generateMetadata({
+  params: { slug, framework },
+}: { params: { slug: string[]; framework: string } }) {
+  const slugPath = slug.join("/");
+  try {
+    const mdxSource = await getMdxSource(slugPath, framework);
+    const title = mdxSource.tableOfContents?.[0].value || "Documentation";
+
+    return {
+      title,
+      openGraph: {
+        title,
+      },
+    };
+  } catch (error) {
+    return {
+      title: "Documentation",
+      openGraph: {
+        title: "Documentation",
+      },
+    };
+  }
+}
+
 export default async function Page({
   params: { slug, framework },
 }: { params: { slug: string[]; framework: string } }) {
@@ -13,13 +45,7 @@ export default async function Page({
   const bodyClassName = "overflow-x-hidden lg:flex-1 py-10  max-w-3xl mx-auto";
 
   try {
-    let mdxSource;
-    try {
-      mdxSource = await import(`./${slugPath}.mdx`);
-    } catch (error) {
-      mdxSource = await import(`./${slugPath}/${framework}.mdx`);
-    }
-
+    const mdxSource = await getMdxSource(slugPath, framework);
     const { default: Content, tableOfContents } = mdxSource;
 
     // Exclude h1 from table of contents

homepage/homepage/app/(docs)/docs/[framework]/[...slug]/using-covalues/cofeeds.mdx

@@ -0,0 +1,225 @@
+export const metadata = { title: "CoFeeds" };
+
+import { CodeGroup, ComingSoon, ContentByFramework } from "@/components/forMdx";
+
+# CoFeeds
+
+CoFeeds are append-only data structures that track entries from different user sessions and accounts. Unlike other CoValues where everyone edits the same data, CoFeeds maintain separate streams for each session.
+
+Each account can have multiple sessions (different browser tabs, devices, or app instances), making CoFeeds ideal for building features like activity logs, presence indicators, and notification systems.
+
+The [Reactions example](https://github.com/garden-co/jazz/tree/main/examples/reactions) demonstrates a practical use of CoFeeds.
+
+## Creating CoFeeds
+
+CoFeeds are defined by specifying the type of items they'll contain, similar to how you define CoLists:
+
+<CodeGroup>
+```ts
+// Define a schema for feed items
+class Activity extends CoMap {
+  timestamp = co.Date;
+  action = co.literal("watering", "planting", "harvesting", "maintenance");
+  notes = co.optional.string;
+}
+
+// Define a feed of garden activities
+class ActivityFeed extends CoFeed.Of(co.ref(Activity)) {}
+
+// Create a feed instance
+const activityFeed = ActivityFeed.create([]);
+```
+</CodeGroup>
+
+Like other CoValues, you can specify [ownership](/docs/using-covalues/ownership) when creating CoFeeds.
+
+## Reading from CoFeeds
+
+Since CoFeeds are made of entries from users over multiple sessions, you can access entries in different ways - from a specific user's session or from their account as a whole.
+
+### Per-Session Access
+
+To retrieve entries from a session:
+
+<CodeGroup>
+```ts
+// Get the feed for a specific session
+const sessionFeed = activityFeed.perSession[sessionId];
+
+// Latest entry from a session
+console.log(sessionFeed.value.action); // "watering"
+```
+</CodeGroup>
+
+For convenience, you can also access the latest entry from the current session with `inCurrentSession`:
+
+<CodeGroup>
+```ts
+// Get the feed for the current session
+const currentSessionFeed = activityFeed.inCurrentSession;
+
+// Latest entry from the current session
+console.log(currentSessionFeed.value.action); // "harvesting"
+```
+</CodeGroup>
+
+### Per-Account Access
+
+To retrieve entries from a specific account you can use bracket notation with the account ID:
+
+<CodeGroup>
+```ts
+// Get the feed for a specific account
+const accountFeed = activityFeed[accountId];
+
+// Latest entry from the account
+console.log(accountFeed.value.action); // "watering"
+```
+</CodeGroup>
+
+For convenience, you can also access the latest entry from the current account with `byMe`:
+
+<CodeGroup>
+```ts
+// Get the feed for the current account
+const myLatestEntry = activityFeed.byMe;
+
+// Latest entry from the current account
+console.log(myLatestEntry.value.action); // "harvesting"
+```
+</CodeGroup>
+
+### Feed Entries
+
+#### All Entries
+
+To retrieve all entries from a CoFeed:
+
+<CodeGroup>
+```ts
+// Get the feeds for a specific account and session
+const accountFeed = activityFeed[accountId];
+const sessionFeed = activityFeed.perSession[sessionId];
+
+// Iterate over all entries from the account
+for (const entry of accountFeed.all) {
+  console.log(entry.value);
+}
+
+// Iterate over all entries from the session
+for (const entry of sessionFeed.all) {
+  console.log(entry.value);
+}
+```
+</CodeGroup>
+
+#### Latest Entry
+
+To retrieve the latest entry from a CoFeed, ie. the last update:
+
+<CodeGroup>
+```ts
+// Get the latest entry from the current account
+const latestEntry = activityFeed.byMe;
+
+console.log(`My last action was ${latestEntry.value.action}`); 
+  // "My last action was harvesting"
+
+// Get the latest entry from each account
+const latestEntriesByAccount = Object.values(activityFeed).map(entry => ({
+  accountName: entry.by?.profile?.name,
+  value: entry.value,
+}));
+```
+</CodeGroup>
+
+## Writing to CoFeeds
+
+CoFeeds are append-only; you can add new items, but not modify existing ones. This creates a chronological record of events or activities.
+
+### Adding Items
+
+<CodeGroup>
+```ts
+// Log a new activity
+activityFeed.push(Activity.create({
+  timestamp: new Date(),
+  action: "watering",
+  notes: "Extra water for new seedlings"
+}));
+```
+</CodeGroup>
+
+Each item is automatically associated with the current user's session. You don't need to specify which session the item belongs to - Jazz handles this automatically.
+
+### Understanding Session Context
+
+Each entry is automatically added to the current session's feed. When a user has multiple open sessions (like both a mobile app and web browser), each session creates its own separate entries:
+
+<CodeGroup>
+```ts
+// On mobile device:
+fromMobileFeed.push(Activity.create({
+  timestamp: new Date(),
+  action: "harvesting",
+  location: "Vegetable patch"
+}));
+
+// On web browser (same user):
+fromBrowserFeed.push(Activity.create({
+  timestamp: new Date(),
+  action: "planting",
+  location: "Flower bed"
+}));
+
+// These are separate entries in the same feed, from the same account
+
+```
+</CodeGroup>
+
+## Metadata
+
+CoFeeds support metadata, which is useful for tracking information about the feed itself. 
+
+### By
+
+The `by` property is the account that made the entry.
+
+<CodeGroup>
+```ts
+const accountFeed = activityFeed[accountId];  
+
+// Get the account that made the last entry
+console.log(accountFeed?.by);
+```
+</CodeGroup>
+
+### MadeAt
+
+The `madeAt` property is a timestamp of when the entry was added to the feed.
+
+<CodeGroup>
+```ts
+const accountFeed = activityFeed[accountId];
+
+// Get the timestamp of the last update
+console.log(accountFeed?.madeAt);
+
+// Get the timestamp of each entry
+for (const entry of accountFeed.all) {
+  console.log(entry.madeAt);
+}
+```
+</CodeGroup>
+
+## Best Practices
+
+### When to Use CoFeeds
+
+- **Use CoFeeds when**:
+  - You need to track per-user/per-session data
+  - Time-based information matters (activity logs, presence)
+
+- **Consider alternatives when**:
+  - Data needs to be collaboratively edited (use CoMaps or CoLists)
+  - You need structured relationships (use CoMaps/CoLists with references)

homepage/homepage/app/(docs)/docs/[framework]/[...slug]/using-covalues/colists.mdx

@@ -0,0 +1,192 @@
+import { CodeGroup, ContentByFramework } from "@/components/forMdx";
+
+export const metadata = { title: "CoLists" };
+
+# CoLists
+
+CoLists are ordered collections that work like JavaScript arrays. They provide indexed access, iteration methods, and length properties, making them perfect for managing sequences of items.
+
+## Creating CoLists
+
+CoLists are defined by specifying the type of items they contain:
+
+<CodeGroup>
+```ts
+class ListOfResources extends CoList.Of(co.string) {}
+
+class ListOfTasks extends CoList.Of(co.ref(Task)) {}
+```
+</CodeGroup>
+
+To instantiate a CoList:
+
+<CodeGroup>
+```ts
+// Create an empty list
+const resources = ListOfResources.create([]);
+
+// Create a list with initial items
+const tasks = ListOfTasks.create([
+  Task.create({ title: "Prepare soil beds", status: "in-progress" }),
+  Task.create({ title: "Order compost", status: "todo" })
+]);
+```
+</CodeGroup>
+
+Like other CoValues, you can specify [ownership](/docs/using-covalues/ownership) when creating CoLists.
+
+## Reading from CoLists
+
+CoLists support standard array access patterns:
+
+<CodeGroup>
+```ts
+// Access by index
+const firstTask = tasks[0];
+console.log(firstTask.title);  // "Prepare soil beds"
+
+// Get list length
+console.log(tasks.length);     // 2
+
+// Iteration
+tasks.forEach(task => {
+  console.log(task.title);
+  // "Prepare soil beds"
+  // "Order compost"
+});
+
+// Array methods
+const todoTasks = tasks.filter(task => task.status === "todo");
+console.log(todoTasks.length); // 1
+```
+</CodeGroup>
+
+## Writing to CoLists
+
+CoLists support all the standard JavaScript array mutation methods:
+
+<CodeGroup>
+```ts
+// Add items
+resources.push("Courgette");          // Add to end
+resources.unshift("Lettuce");         // Add to beginning
+
+console.log(resources);
+  // ["Lettuce", "Tomatoes", "Basil", "Peppers", "Courgette"]
+
+// Add complex items to lists of references
+tasks.push(Task.create({
+  title: "Install irrigation system", 
+  status: "todo"
+}));
+
+// Remove items
+resources.pop();                      // Remove last item
+resources.shift();                    // Remove first item
+resources.splice(1, 2);               // Remove items at index 1 and 2
+
+// Replace items
+resources[0] = "Cucumber";            // Replace first item
+
+console.log(resources);               // ["Cucumber"]
+
+// Modify items in a list of references
+tasks[0].status = "in-progress";  // Modify a property of an item
+```
+</CodeGroup>
+
+
+### Type Safety
+
+CoLists maintain type safety for their items:
+
+<CodeGroup>
+```ts
+// TypeScript knows each item's type
+resources.push("Carrots");        // ✓ Valid string
+resources.push(42);               // ✗ Type error: expected string
+
+// For lists of references, TypeScript knows the referenced type
+tasks.forEach(task => {
+  console.log(task.title);     // TypeScript knows 'task' has a 'title'
+});
+```
+</CodeGroup>
+
+### Array Methods
+
+CoLists support many standard JavaScript array methods:
+
+<CodeGroup>
+```ts
+resources.push("Tomatoes", "Basil", "Peppers");
+
+// Filter
+const springResources = resources.filter(resource => resource.includes("Tomato"));
+console.log(springResources); // ["Tomatoes"]
+
+// Map (creates a regular array, not a CoList)
+const resourceNames = resources.map(resource => resource.toUpperCase());
+console.log(resourceNames); // ["TOMATOES", "BASIL", "PEPPERS"]
+
+// Find
+const basil = resources.find(resource => resource === "Basil");
+
+// Sort (modifies the CoList in-place)
+resources.sort();
+console.log(resources); // ["Basil", "Cucumber", "Peppers", "Tomatoes"]
+```
+</CodeGroup>
+
+## Best Practices
+
+### Common Patterns
+
+#### List Rendering
+
+CoLists work well with UI rendering libraries:
+
+<CodeGroup>
+```tsx
+// React example
+function TaskList({ tasks }) {
+  return (
+    <ul>
+      {tasks.map(task => (
+        <li key={task.id}>
+          {task.title} - {task.status}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+</CodeGroup>
+
+#### Managing Relations
+
+CoLists can be used to create one-to-many relationships:
+
+<CodeGroup>
+```ts
+class Project extends CoMap {
+  name = co.string;
+  tasks = co.ref(ListOfTasks);
+}
+
+// ...
+
+const task = Task.create({ 
+  title: "Plant seedlings",
+  status: "todo",
+  project: project, // Add a reference to the project
+});
+
+// Add a task to a garden project
+project.tasks.push(task);
+
+// Access the project from the task
+console.log(task.project); // { name: "Garden Project", tasks: [task] }
+```
+</CodeGroup>
+

homepage/homepage/app/(docs)/docs/[framework]/[...slug]/using-covalues/comaps.mdx

@@ -0,0 +1,199 @@
+import { CodeGroup, ContentByFramework } from "@/components/forMdx";
+
+export const metadata = { title: "CoMaps" };
+
+# CoMaps
+
+CoMaps are key-value objects that work like JavaScript objects. You can access properties with dot notation and define typed fields that provide TypeScript safety. They're ideal for structured data that needs type validation.
+
+## Creating CoMaps
+
+CoMaps are typically defined by extending the `CoMap` class and specifying primitive fields using the `co` declarer (see [Defining schemas: CoValues](/docs/schemas/covalues) for more details on primitive fields):
+
+<CodeGroup>
+```ts
+class Project extends CoMap {
+  name = co.string;
+  startDate = co.Date;
+  status = co.literal("planning", "active", "completed");
+  coordinator = co.optional.ref(Member);
+}
+```
+</CodeGroup>
+
+You can create either struct-like CoMaps with fixed fields (as above) or record-like CoMaps for key-value pairs:
+
+<CodeGroup>
+```ts
+class Inventory extends CoMap.Record(co.number) {}
+```
+</CodeGroup>
+
+To instantiate a CoMap:
+
+<CodeGroup>
+```ts
+const project = Project.create({
+  name: "Spring Planting",
+  startDate: new Date("2025-03-15"),
+  status: "planning",
+});
+
+const inventory = Inventory.create({
+  tomatoes: 48,
+  basil: 12,
+});
+
+```
+</CodeGroup>
+
+### Ownership
+
+When creating CoMaps, you can specify ownership to control access:
+
+<CodeGroup>
+```ts
+// Create with default owner (current user)
+const privateProject = Project.create({
+  name: "My Herb Garden",
+  startDate: new Date("2025-04-01"),
+  status: "planning",
+});
+
+// Create with shared ownership
+const gardenGroup = Group.create();
+gardenGroup.addMember(memberAccount, "writer");
+
+const communityProject = Project.create(
+  {
+    name: "Community Vegetable Plot",
+    startDate: new Date("2025-03-20"),
+    status: "planning",
+  },
+  { owner: gardenGroup },
+);
+```
+</CodeGroup>
+
+## Reading from CoMaps
+
+CoMaps can be accessed using familiar JavaScript object notation:
+
+<CodeGroup>
+```ts
+console.log(project.name);      // "Spring Planting"
+console.log(project.status);    // "planning"
+```
+</CodeGroup>
+
+### Handling Optional Fields
+
+Optional fields require checks before access:
+
+<CodeGroup>
+```ts
+if (project.coordinator) {
+  console.log(project.coordinator.name);  // Safe access
+}
+```
+</CodeGroup>
+
+### Working with Record CoMaps
+
+For record-type CoMaps, you can access values using bracket notation:
+
+<CodeGroup>
+```ts
+const inventory = Inventory.create({
+  tomatoes: 48,
+  peppers: 24,
+  basil: 12
+});
+
+console.log(inventory["tomatoes"]);  // 48
+```
+</CodeGroup>
+
+## Updating CoMaps
+
+Updating CoMap properties uses standard JavaScript assignment:
+
+<CodeGroup>
+```ts
+project.name = "Spring Vegetable Garden";    // Update name
+project.startDate = new Date("2025-03-20");  // Update date
+```
+</CodeGroup>
+
+### Type Safety
+
+CoMaps are fully typed in TypeScript, giving you autocomplete and error checking:
+
+<CodeGroup>
+```ts
+project.name = "Spring Vegetable Planting";  // ✓ Valid string
+project.startDate = "2025-03-15";  // ✗ Type error: expected Date
+```
+</CodeGroup>
+
+
+### Deleting Properties
+
+You can delete properties from CoMaps:
+
+<CodeGroup>
+```ts
+delete inventory["basil"];  // Remove a key-value pair
+
+// For optional fields in struct-like CoMaps
+project.coordinator = null;  // Remove the reference
+```
+</CodeGroup>
+
+## Best Practices
+
+### Structuring Data
+
+- Use struct-like CoMaps for entities with fixed, known properties
+- Use record-like CoMaps for dynamic key-value collections
+- Group related properties into nested CoMaps for better organization
+
+### Common Patterns
+
+#### Using Computed Properties
+
+CoMaps support computed properties and methods:
+
+<CodeGroup>
+```ts
+class ComputedProject extends CoMap {
+  name = co.string;
+  startDate = co.Date;
+  endDate = co.optional.Date;
+
+  get isActive() {
+    const now = new Date();
+    return now >= this.startDate && (!this.endDate || now <= this.endDate);
+  }
+
+  formatDuration(format: "short" | "full") {
+    const start = this.startDate.toLocaleDateString();
+    if (!this.endDate) {
+      return format === "full"
+        ? `Started on ${start}, ongoing`
+        : `From ${start}`;
+    }
+
+    const end = this.endDate.toLocaleDateString();
+    return format === "full"
+      ? `From ${start} to ${end}`
+      : `${(this.endDate.getTime() - this.startDate.getTime()) / 86400000} days`;
+  }
+}
+
+// ...
+
+console.log(computedProject.isActive); // false
+console.log(computedProject.formatDuration("short")); // "3 days"
+```
+</CodeGroup>

homepage/homepage/app/(docs)/docs/[framework]/[...slug]/using-covalues/creation.mdx

@@ -0,0 +1,107 @@
+import { CodeGroup, ComingSoon, ContentByFramework } from "@/components/forMdx";
+
+export const metadata = { title: "Creation & ownership" };
+
+# Creation & Ownership
+
+CoValues are collaborative by nature - anything you create can be shared and synced with others. Who gets to read or change each CoValue is controlled by its owner - either an individual `Account` or a shared `Group`. This foundation of ownership is what enables Jazz applications to support real-time collaboration while maintaining proper access control. Understanding how to create and manage ownership of CoValues is essential for building effectively with Jazz.
+
+## Creating CoValues
+
+Every CoValue starts with a [schema](/docs/schemas/covalues#start-your-app-with-a-schema). From there you can create CoValues with the `create` method. Creating CoValues is straightforward - you define the structure in your schema and then instantiate instances with initial values. These newly created CoValues automatically sync across devices and users who have access to them. 
+
+Here's a simple example:
+
+<CodeGroup>
+```ts
+class Task extends CoMap {
+  title = co.string;
+  description = co.string;
+  status = co.literal("todo", "in-progress", "completed");
+}
+
+// Create a new task
+const task = Task.create({
+  title: "Plant spring vegetables",
+  description: "Plant peas, carrots, and lettuce",
+  status: "todo",
+});
+```
+</CodeGroup>
+
+When you create a CoValue, you provide its initial data and optionally specify who owns it. The data must match the schema you defined - TypeScript will help ensure you get this right.
+
+For more examples of creating different types of CoValues:
+
+<CodeGroup>
+```ts
+// Creating a CoFeed for activity notifications
+class ActivityNotification extends CoMap {
+  message = co.string;
+  type = co.literal("info", "warning", "success");
+  timestamp = co.Date;
+}
+
+class ActivityFeed extends CoFeed.Of(co.ref(ActivityNotification)) {}
+
+const feed = ActivityFeed.create();
+
+// Adding an item to the feed
+feed.addItem(ActivityNotification.create({
+  message: "New task created",
+  type: "info",
+  timestamp: new Date()
+}));
+```
+</CodeGroup>
+
+## Ownership & Access Control
+
+Every CoValue needs an owner to control who can access it. An owner can be an individual `Account`, but it's usually a `Group` since that lets you share with multiple people. The ownership model in Jazz provides fine-grained control over who can read, write, or administer your collaborative data. This system makes it easy to implement common patterns like shared workspaces, personal data, or public resources.
+
+### Groups & Roles
+
+Groups have members with different roles that control what they can do. These roles provide a permission system that's both simple to understand and powerful enough for complex collaboration scenarios. By assigning appropriate roles, you can control exactly who can view, edit, or manage access to your data.
+
+<CodeGroup>
+```ts
+// Create a group
+const gardenTeam = Group.create();
+
+// Add garden members with different roles
+gardenTeam.addMember(coordinator, "admin");     // Garden coordinator manages everything
+gardenTeam.addMember(gardener, "writer");       // Gardeners can update tasks
+gardenTeam.addMember(visitor, "reader");        // Visitors can view progress
+
+// Create a list of tasks with the same owner
+const taskList = ListOfTasks.create([]);
+
+// Create a garden project with nested tasks, all with the same ownership
+const springProject = Project.create({
+  name: "Spring Planting",
+  description: "Preparing the community garden for spring vegetables",
+  tasks: taskList
+});
+
+// Add tasks to the list
+taskList.push(Task.create({
+  title: "Start tomato seedlings",
+  description: "Plant Roma and Cherry varieties in seed trays",
+  status: "todo"
+});
+
+taskList.push(Task.create({
+  title: "Prepare herb garden",
+  description: "Clear old growth and add fresh compost",
+  status: "todo"
+});
+```
+</CodeGroup>
+
+Each role has specific permissions:
+- `admin`: Full control including managing members
+- `writer`: Can modify content
+- `reader`: Can only read content
+- `writerOnly`: Can only write to the CoValue, not read it
+
+For more information on groups and roles, see the [Groups](/docs/groups/intro) documentation.

homepage/homepage/app/(docs)/docs/[framework]/[...slug]/using-covalues/metadata.mdx

@@ -0,0 +1,269 @@
+import { CodeGroup } from "@/components/forMdx";
+
+export const metadata = { title: "Metadata & time-travel" };
+
+# Metadata & time-travel
+
+One of Jazz's most powerful features is that every CoValue automatically tracks its complete edit history. This means you can see who changed what and when, examine the state of your data at any point in time, and build features like audit logs, activity feeds, and undo/redo functionality. This page explores how to access and work with the rich metadata that comes with every CoValue.
+
+## Understanding Edit History
+
+Every CoValue in Jazz maintains a full history of all changes made to it. This edit history is accessible through two main APIs:
+
+`CoValue._edits` provides a structured, field-by-field view of a CoValue's edit history. It organizes edits by property name and makes them easily accessible. For each field:
+- `_edits.fieldName` gives you the most recent edit
+- `_edits.fieldName.all` provides all historical edits as an array
+- `_edits.fieldName.madeAt` gives you the timestamp of the last edit
+- Each edit contains the value, who made the change, and when it happened
+
+`CoValue._raw` gives you access to the internal state and lower-level operations on a CoValue. As this is an internal API, it should be used with caution. If you find yourself using `_raw`, consider letting us know so we can consider adding a public API for your use case.
+
+## Working with Edit History Metadata
+
+CoValues track who made each change and when. Every edit has metadata attached to it, including the author, timestamp, value, and transaction ID. This metadata enables you to build powerful audit and history features without having to implement your own tracking system.
+
+<CodeGroup>
+```ts
+class Task extends CoMap {
+  title = co.string;
+  description = co.string;
+  status = co.literal("todo", "in-progress", "completed");
+  priority = co.literal("low", "medium", "high");
+  subtasks = co.optional.ref(ListOfTasks);
+}
+
+class ListOfTasks extends CoList.Of(co.ref(Task)) {}
+
+const task = Task.create({
+  title: "Plant spring vegetables",
+  description: "Plant peas, carrots, and lettuce in the south garden bed",
+  status: "todo",
+  priority: "medium",
+});
+
+// Change the status
+task.status = "in-progress";
+
+// Get the latest edit for a field
+console.log("Latest edit:", task._edits.status);
+// { value: "in-progress", by: Account, madeAt: Date, ... }
+
+// Get when a field was last edited (timestamp)
+const lastEditTime = task._edits.status.madeAt;
+console.log(`Status was last changed at: ${lastEditTime?.toLocaleString()}`);
+
+// Get the full edit history for a field
+for (const edit of task._edits.status.all) {
+  console.log({
+    author: edit.by,        // Account that made the change
+    timestamp: edit.madeAt, // When the change happened
+    value: edit.value,      // Value of the change
+  });
+}
+```
+</CodeGroup>
+
+### Common Patterns
+
+With knowledge of the edit history, you can build all sorts of useful features that enhance your application's user experience and administrative capabilities. Here are some common patterns that leverage CoValue metadata.
+
+#### Audit Log
+
+Getting all the changes to a CoValue in order allows you to build an audit log. This is especially useful for tracking important changes in collaborative environments or for compliance purposes:
+
+<CodeGroup>
+```ts
+
+function getAuditLog(task: Task) {
+  const changes = [];
+
+  for (const field of Object.keys(task)) {
+    // Check if the field has edits to avoid accessing non-existent properties
+    if (task._edits[field as keyof typeof task._edits]) {
+      for (const edit of task._edits[field as keyof typeof task._edits].all) {
+        changes.push({
+          field,
+          ...edit,
+          timestamp: edit.madeAt,
+          at: edit.madeAt,
+          by: edit.by,
+        });
+      }
+    }
+  }
+
+  // Sort by timestamp
+  return changes.sort((a, b) => b.at.getTime() - a.at.getTime());
+}
+
+// Example usage
+const auditLog = getAuditLog(task);
+auditLog.forEach((entry) => {
+  console.log(
+    `${entry.timestamp} - ${entry.field} changed to "${entry.value}" by ${entry.by?.id}`,
+  );
+});
+```
+</CodeGroup>
+
+#### Activity Feeds
+
+Activity feeds are a great way to see recent changes to a CoValue, helping users understand what's happening in a collaborative workspace. They can show who did what and when, creating transparency in team environments:
+
+<CodeGroup>
+```ts
+function getRecentActivity(project: Project) {
+  const activity = [];
+  const hourAgo = new Date(Date.now() - 3600000);
+  
+  for (const field of Object.keys(project)) {
+    // Skip if the field doesn't have edits
+    if (!project._edits[field as keyof typeof project._edits]) continue;
+    
+    for (const edit of project._edits[field as keyof typeof project._edits].all) {
+      if (edit.madeAt > hourAgo) {
+        activity.push({
+          field,
+          value: edit.value,
+          by: edit.by,
+          at: edit.madeAt
+        });
+      } 
+    }
+  }
+  
+  return activity.sort((a, b) => b.at.getTime() - a.at.getTime());
+}
+
+// Example usage
+const recentActivity = getRecentActivity(gardenProject);
+console.log("Recent Garden Activity:");
+recentActivity.forEach(activity => {
+  console.log(`${activity.at.toLocaleString()} - ${activity.field} updated by ${activity.by?.id}`);
+});
+```
+</CodeGroup>
+
+## Edit History & Time Travel
+
+CoValues track their entire history of changes, creating a timeline you can explore. You can see who changed what and when, or even view past states of the data. This capability enables powerful debugging tools and user-facing features like history browsing and restoration of previous versions:
+
+<CodeGroup> 
+```ts
+class Task extends CoMap {
+  title = co.string;
+  description = co.string;
+  status = co.literal("todo", "in-progress", "completed");
+  priority = co.literal("low", "medium", "high");
+}
+
+// Create a new task
+const task = Task.create({
+  title: "Plant spring vegetables",
+  description: "Plant peas, carrots, and lettuce in the south garden bed",
+  status: "todo",
+  priority: "medium",
+});
+
+// Make some changes
+task.status = "in-progress";
+task.priority = "high";
+
+// See all edits for a field
+for (const edit of task._edits.status.all) {
+  console.log(
+    `${edit.madeAt.toISOString()}: Status changed to "${edit.value}" by ${edit.by?.id}`,
+  );
+}
+
+// Get the initial value
+const initialStatus = task._edits.status.all[0]?.value;
+console.log(`Original status: ${initialStatus}`);
+
+// Get a specific edit by index
+const previousEdit = task._edits.status.all[1]; // Second edit
+console.log(`Previous status: ${previousEdit?.value}`);
+
+// Check who made the most recent change
+const latestEdit = task._edits.status;
+console.log(`Latest change made by: ${latestEdit?.by?.id}`);
+```
+</CodeGroup>
+
+## Time Travel
+
+The ability to view a CoValue as it existed at any point in time is one of Jazz's most powerful features. Looking into the past can help you understand how things changed - perfect for audit logs, debugging, or showing user activity. You can reconstruct the exact state of any CoValue at any moment in its history:
+
+<CodeGroup>
+```ts
+class Project extends CoMap {
+  name = co.string;
+  status = co.literal("planning", "active", "completed");
+  lastUpdate = co.Date;
+}
+
+// See when a project was started
+function findStatusChange(project: Project, targetStatus: string) {
+  // Get all the edits for the status field
+  const statusEdits = project._edits.status.all;
+  
+  for (const edit of statusEdits) {
+    if (edit.value === targetStatus) {
+      console.log({
+        changeTime: edit.madeAt,
+        lastUpdate: project.lastUpdate,
+        changedBy: edit.by,
+      });
+    }
+  }
+}
+
+// Example usage
+findStatusChange(gardenProject, "active");
+```
+</CodeGroup>
+
+### Common Use Cases
+
+The time travel capabilities of CoValues enable several practical use cases that would otherwise require complex custom implementations. Here are some examples of how you can use time travel in your applications:
+
+<CodeGroup>
+```ts
+// Track task progress over time
+function getTaskStatusHistory(task: Task, days: number = 7) {
+  const statusHistory = [];
+  const dayInMs = 86400000;
+  
+  // Check every day for the past week
+  for (let day = 0; day < days; day++) {
+    const timePoint = new Date(Date.now() - day * dayInMs);
+    // Using the internal _raw API to get state at a specific point in time
+    const state = task._raw.atTime(timePoint);
+    statusHistory.push({
+      date: timePoint.toLocaleDateString(),
+      status: state.status,
+      priority: state.priority
+    });
+  }
+  
+  return statusHistory;
+}
+
+// Example usage
+const history = getTaskStatusHistory(plantingTask);
+history.forEach(entry => {
+  console.log(`${entry.date}: Status was "${entry.status}" with ${entry.priority} priority`);
+});
+```
+</CodeGroup>
+
+### Best Practices
+
+- Check field existence before accessing edits (`if (task._edits.fieldName)`)
+- Access the most recent edit directly with `_edits.fieldName` instead of using any `.latest` property
+- Cache historical queries if you're displaying them in UI
+- Be specific about time ranges you care about
+- Remember that accessing history requires loading the CoValue
+- Consider using timestamps from your data rather than scanning all edits
+
+Time travel is great for understanding how you got here, but keep queries focused on the range of time that matters to your use case.

homepage/homepage/app/(docs)/docs/[framework]/[...slug]/using-covalues/reading.mdx

@@ -0,0 +1,272 @@
+import { CodeGroup, ComingSoon, ContentByFramework } from "@/components/forMdx";
+
+export const metadata = { title: "Reading from CoValues" };
+
+# Reading from CoValues
+
+Jazz lets you access your collaborative data with familiar JavaScript patterns while providing TypeScript type safety. Once you have a CoValue, you can read its values, traverse references, and iterate through collections using the same syntax you'd use with regular objects and arrays. This page covers how to read from different types of CoValues and handle loading states effectively.
+
+<CodeGroup>
+```ts
+class Project extends CoMap {
+  name = co.string;
+  tasks = co.ref(ListOfTasks);
+  lead = co.optional.ref(TeamMember);
+  status = co.literal("planning", "active", "completed");
+}
+
+// Reading basic fields
+console.log(project.name);           // "Spring Garden Planning"
+console.log(project.status);         // "active"
+
+// Reading from lists
+for (const task of project.tasks) {
+  console.log(task.title);           // "Plant tomato seedlings"
+}
+
+// Checking if an optional field exists
+if (project.lead) {
+  console.log(project.lead.name);    // "Maria Chen"
+}
+```
+</CodeGroup>
+
+## Different Types of CoValues
+
+Jazz provides several CoValue types to represent different kinds of data. Each type has its own access patterns, but they all maintain the familiar JavaScript syntax you already know.
+
+### CoMaps
+`CoMap`s work like JavaScript objects, providing named properties you can access with dot notation. These are the most common CoValue type and form the foundation of most Jazz data models:
+
+<CodeGroup> 
+```ts
+class TeamMember extends CoMap {
+  name = co.string;
+  role = co.string;
+  active = co.boolean;
+}
+
+console.log(member.name);          // "Maria Chen"
+console.log(member.role);          // "Garden Coordinator"
+console.log(member.active);        // true
+```
+</CodeGroup>
+
+### CoLists
+`CoList`s work like JavaScript arrays, supporting indexed access, iteration methods, and length properties. They're perfect for ordered collections of items where the order matters:
+
+<CodeGroup>
+```ts
+class ListOfTasks extends CoList.Of(co.ref(Task)) {}
+
+// Access items by index
+console.log(tasks[0].title);      // "Plant tomato seedlings"
+
+// Use array methods
+tasks.forEach(task => {
+  console.log(task.title);        // "Plant tomato seedlings"
+});
+
+// Get list length
+console.log(tasks.length);       // 3
+```
+</CodeGroup>
+
+### CoFeeds
+`CoFeed`s provide a specialized way to track data from different sessions (tabs, devices, app instances). They're ideal for activity logs, presence indicators, or other session-specific streams of information. Each account can have multiple sessions, and each session maintains its own append-only log.
+
+## Type Safety with CoValues
+
+CoValues are fully typed in TypeScript, giving you the same autocomplete and error checking you'd expect from regular objects. This type safety helps catch errors at compile time rather than runtime, making your application more robust. Here's how the type system works with CoValues:
+
+<CodeGroup>
+```ts
+class Project extends CoMap {
+  name = co.string;
+  memberCount = co.number;
+  priority = co.literal("low", "medium", "high");
+  lead = co.optional.ref(TeamMember);
+  tasks = co.ref(ListOfTasks);
+}
+
+// TypeScript knows exactly what fields exist
+const project = await Project.load(gardenProjectId);
+
+project.name = "Community Garden"; // ✓ string
+project.memberCount = "few";       // ✗ Type error: expected number
+project.priority = "urgent";       // ✗ Type error: must be low/medium/high
+
+// Optional fields are handled safely
+if (project.lead) {
+  console.log(project.lead.name);  // Type safe
+}
+
+// Lists with specific item types
+project.tasks.forEach(task => {
+  // TypeScript knows each task's structure
+  console.log(`${task.title}: ${task.status}`); // "Plant herbs: in-progress"
+});
+```
+</CodeGroup>
+
+## Loading States
+
+When you load a CoValue, it might not be immediately available due to network latency or data size. Jazz provides patterns to handle these loading states gracefully, and TypeScript helps ensure you check for availability before accessing properties:
+
+<CodeGroup>
+```ts
+const project = await Project.load(gardenProjectId);
+
+if (!project) {
+  return "Data still loading";
+}
+```
+</CodeGroup>
+
+<ContentByFramework framework="react">
+And in React, `useCoState` provides a similar pattern to allow you to wait for a CoValue to be loaded before accessing it:
+<CodeGroup>
+```tsx
+// Type shows this might be `undefined` while loading
+const project = useCoState(Project, gardenProjectId, { 
+  tasks: [{}] 
+});
+
+if (!project) {
+  return <div>Loading project data...</div>;
+}
+
+// TypeScript now knows project exists and has tasks loaded
+return <div>{project.tasks.length}</div>;
+```
+</CodeGroup>
+</ContentByFramework>
+
+### Accessing Nested CoValues
+
+Nested CoValues need special handling for loading and access. Since each reference might need to be loaded separately, you need patterns to manage these dependencies and handle loading states appropriately throughout your object graph.
+
+<CodeGroup>
+```ts
+class Project extends CoMap {
+  name = co.string;
+  tasks = co.ref(ListOfTasks);
+  resources = co.optional.ref(ResourceList);
+}
+
+class Task extends CoMap {
+  title = co.string;
+  status = co.literal("todo", "in-progress", "completed");
+  subtasks = co.ref(ListOfSubtasks);
+}
+```
+</CodeGroup>
+
+### Loading
+
+Loading nested data efficiently is important for performance. Jazz provides depth specifications to control exactly how much of your object graph is loaded, from shallow loading of just the top-level object to deep loading of complex nested structures:
+
+<CodeGroup>
+```ts
+// Basic load - tasks won't be loaded yet
+const project = await Project.load(gardenProjectId);
+
+// Load with nested data
+const projectWithTasks = await Project.load(gardenProjectId, { tasks: {} });
+
+// Deep load pattern
+const fullyLoaded = await Project.load(gardenProjectId, {
+  tasks: { 
+    subtasks: {}
+  }
+});
+```
+</CodeGroup>
+
+More details on loading and subscribing to CoValues can be found in  [Subscribing](/docs/using-covalues/subscribing-and-deep-loading).
+
+### Handling Loading States
+
+Unloaded references return `undefined`. This means you need to check for undefined values before trying to access properties of nested CoValues.
+
+For general JavaScript/TypeScript usage, here's a pattern that works across any context:
+
+<CodeGroup>
+```ts
+// Generic pattern for handling nested data
+function processTaskData(project) {
+  // Check if project and its tasks are loaded
+  if (!project || !project.tasks) {
+    return "Data still loading";
+  }
+
+  // Safe to process tasks
+  const completedTasks = project.tasks.filter(task => 
+    task && task.status === "completed"
+  );
+  
+  // Check for subtasks before accessing them
+  const subtaskCount = completedTasks.reduce((count, task) => {
+    if (!(task && task.subtasks)) return count
+    return count + task.subtasks.length;
+  }, 0);
+  
+  return {
+    completedCount: completedTasks.length,
+    subtaskCount: subtaskCount
+  };
+}
+```
+</CodeGroup>
+
+<ContentByFramework framework="react">
+Handle these loading states in your components:
+
+<CodeGroup>
+```tsx
+// React pattern for handling nested data
+function TaskList({ project }: { project: Project }) {
+  if (!project.tasks) {
+    return <div>Loading tasks...</div>;
+  }
+
+  return (
+    <div>
+      {project.tasks.map(task => {
+        // Handle potentially missing nested data
+        if (!task.subtasks) {
+          return <div key={task.id}>Loading subtasks...</div>;
+        }
+
+        return (
+          <div key={task.id}>
+            {task.title}: {task.subtasks.length} subtasks
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+```
+</CodeGroup>
+</ContentByFramework>
+
+Note: We're working on making these patterns more explicit and robust. We'll provide clearer loading states and better error handling patterns. For now, be defensive with your checks for `undefined`.
+
+<CodeGroup>
+```ts
+// Current safest pattern for deep access
+function getSubtasks(project: Project, taskTitle: string) {
+  const task = project.tasks?.find(t => t.title === taskTitle);
+  const subtasks = task?.subtasks;
+  
+  if (!subtasks) {
+    return null; // Could mean loading or error
+  }
+
+  return subtasks.map(st => st.title);
+}
+```
+</CodeGroup>
+
+Stay tuned for updates to this API - we're working on making these patterns more robust and explicit.

homepage/homepage/app/(docs)/docs/[framework]/[...slug]/using-covalues/subscription-and-loading.mdx

@@ -0,0 +1,340 @@
+import { CodeGroup, ContentByFramework } from "@/components/forMdx";
+
+export const metadata = { title: "Subscriptions & Deep Loading" };
+
+# Subscriptions & Deep Loading
+
+When working with collaborative applications, you need to know when data changes and ensure you have all the necessary related data. Jazz provides powerful subscription and deep loading capabilities that make it easy to keep your UI in sync with the underlying data and efficiently load complex object graphs.
+
+## Understanding Subscriptions
+
+Subscriptions in Jazz allow you to react to changes in CoValues. When a CoValue changes, all subscribers are notified with the updated value. This is essential for building reactive UIs that stay in sync with collaborative data.
+
+<CodeGroup>
+```ts
+class Task extends CoMap {
+  title = co.string;
+  description = co.string;
+  status = co.literal("todo", "in-progress", "completed");
+  assignedTo = co.optional.string;
+}
+
+// ...
+
+// Subscribe to a Task by ID
+const unsubscribe = Task.subscribe(taskId, { /* loading depth */ }, (updatedTask) => {
+  console.log("Task updated:", updatedTask.title);
+  console.log("New status:", updatedTask.status);
+});
+
+// Later, when you're done:
+unsubscribe();
+```
+</CodeGroup>
+
+### Static vs. Instance Subscriptions
+
+There are two main ways to subscribe to CoValues:
+
+1. **Static Subscription** - When you have an ID but don't have the CoValue loaded yet:
+
+<CodeGroup>
+```ts
+// Subscribe by ID (static method)
+const unsubscribe = Task.subscribe(taskId, { /* loading depth */ }, (task) => {
+  if (task) {
+    console.log("Task loaded/updated:", task.title);
+  }
+});
+```
+</CodeGroup>
+
+2. **Instance Subscription** - When you already have a CoValue instance:
+
+<CodeGroup>
+```ts
+// Subscribe to an instance (instance method)
+const task = Task.create({
+  status: "todo",
+  title: "Cut the grass",
+});
+if (task) {
+  const unsubscribe = task.subscribe({ /* loading depth */ }, (updatedTask) => {
+    console.log("Task updated:", updatedTask.title);
+  });
+}
+```
+</CodeGroup>
+
+## Deep Loading
+
+When working with related CoValues (like tasks in a project), you often need to load not just the top-level object but also its nested references. Jazz provides a flexible mechanism for specifying exactly how much of the object graph to load.
+
+### Loading Depth Specifications
+
+Loading depth specifications let you declare exactly which references to load and how deep to go:
+
+<CodeGroup>
+```ts
+class Project extends CoMap {
+  name = co.string;
+  tasks = co.ref(ListOfTasks);
+  owner = co.ref(TeamMember);
+}
+
+class Task extends CoMap {
+  title = co.string; 
+  subtasks = co.ref(ListOfSubtasks);
+  assignee = co.optional.ref(TeamMember);
+}
+
+// Load just the project, not its tasks
+const project = await Project.load(projectId, {});
+
+// Load the project and its tasks (but not subtasks)
+const projectWithTasks = await Project.load(projectId, { 
+  tasks: {}
+});
+
+// Load the project, its tasks, and their subtasks
+const projectDeep = await Project.load(projectId, {
+  tasks: {
+    subtasks: {}
+  }
+});
+
+// Load the project, its tasks, and task assignees
+const projectWithAssignees = await Project.load(projectId, {
+  tasks: {
+    assignee: {}
+  }
+});
+
+// Complex loading pattern: load project, tasks with their subtasks, and the project owner
+const fullyLoaded = await Project.load(projectId, {
+  tasks: {
+    subtasks: {}
+  },
+  owner: {}
+});
+```
+</CodeGroup>
+
+The depth specification object mirrors the structure of your data model, making it intuitive to express which parts of the graph you want to load.
+
+### Array Notation for Lists
+
+For lists, you can use array notation to specify how to load the items:
+
+<CodeGroup>
+```ts
+// Load project with all tasks but load each task shallowly
+const project = await Project.load(projectId, {
+  tasks: [{}]
+});
+
+// Load project with tasks and load subtasks for each task
+const project = await Project.load(projectId, {
+  tasks: [{
+    subtasks: [{}]
+  }]
+});
+```
+</CodeGroup>
+
+## Framework Integration
+
+<ContentByFramework framework="react">
+### React Integration with useCoState
+
+In React applications, the `useCoState` hook provides a convenient way to subscribe to CoValues and handle loading states:
+
+<CodeGroup>
+```tsx
+function GardenPlanner({ projectId }: { projectId: ID<Project> }) {
+  // Subscribe to a project and its tasks
+  const project = useCoState(Project, projectId, {
+    tasks: [{}]
+  });
+
+  // Handle loading state
+  if (!project) {
+    return <div>Loading garden project...</div>;
+  }
+
+  return (
+    <div>
+      <h1>{project.name}</h1>
+      <TaskList tasks={project.tasks} />
+    </div>
+  );
+}
+
+function TaskList({ tasks }: { tasks: Task[] }) {
+  return (
+    <ul>
+      {tasks.map(task => (
+        <li key={task.id}>
+          <span>{task.title}</span>
+          <span>{task.status}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+</CodeGroup>
+
+The `useCoState` hook handles subscribing when the component mounts and unsubscribing when it unmounts, making it easy to keep your UI in sync with the underlying data.
+</ContentByFramework>
+
+<ContentByFramework framework="vue">
+### Vue Integration
+
+In Vue applications, you can use the `useCoState` composable to subscribe to CoValues:
+
+<CodeGroup>
+```vue
+<script setup>
+import { useCoState } from 'jazz-vue';
+
+const props = defineProps({
+  projectId: String
+});
+
+// Subscribe to a project and its tasks
+const project = useCoState(Project, props.projectId, {
+  tasks: [{}]
+});
+</script>
+
+<template>
+  <div v-if="project">
+    <h1>{{ project.name }}</h1>
+    <ul>
+      <li v-for="task in project.tasks" :key="task.id">
+        {{ task.title }} - {{ task.status }}
+      </li>
+    </ul>
+  </div>
+  <div v-else>
+    Loading garden project...
+  </div>
+</template>
+```
+</CodeGroup>
+</ContentByFramework>
+
+<ContentByFramework framework="svelte">
+### Svelte Integration
+
+In Svelte applications, you can use the `useCoState` function to subscribe to CoValues:
+
+<CodeGroup>
+```svelte
+<script>
+  import { useCoState } from 'jazz-svelte';
+  
+  export let projectId;
+  
+  // Subscribe to a project and its tasks
+  const project = useCoState(Project, projectId, {
+    tasks: [{}]
+  });
+</script>
+
+{#if $project}
+  <h1>{$project.name}</h1>
+  <ul>
+    {#each $project.tasks as task (task.id)}
+      <li>{task.title} - {task.status}</li>
+    {/each}
+  </ul>
+{:else}
+  <div>Loading garden project...</div>
+{/if}
+```
+</CodeGroup>
+</ContentByFramework>
+
+## Ensuring Data is Loaded
+
+Sometimes you need to make sure data is loaded before proceeding with an operation. The `ensureLoaded` method lets you guarantee that a CoValue and its referenced data are loaded to a specific depth:
+
+<CodeGroup>
+```ts
+async function completeAllTasks(projectId: ID<Project>) {
+  // Ensure the project and its tasks are loaded
+  const project = await Project.load(projectId, {});
+  if (!project) return;
+  
+  const loadedProject = await project.ensureLoaded({
+    tasks: [{}]
+  });
+  
+  // Now we can safely access and modify tasks
+  loadedProject.tasks.forEach(task => {
+    task.status = "completed";
+  });
+}
+```
+</CodeGroup>
+
+## Performance Considerations
+
+Loading depth is directly related to performance. Loading too much data can slow down your application, while loading too little can lead to "undefined" references. Here are some guidelines:
+
+- **Load only what you need** for the current view or operation
+- **Preload data** that will be needed soon to improve perceived performance
+- Use **caching** to avoid reloading data that hasn't changed
+
+{/* TODO: Add a note about supporting pagination */}
+
+<CodeGroup>
+```ts
+// Bad: Loading everything deeply
+const project = await Project.load(projectId, {
+  tasks: [{ 
+    subtasks: [{ 
+      comments: [{}] 
+    }]
+  }],
+  members: [{}],
+  resources: [{}]
+});
+
+// Better: Loading only what's needed for the current view
+const project = await Project.load(projectId, {
+  tasks: [{}]  // Just load the tasks shallowly
+});
+
+// Later, when a task is selected:
+const task = await Task.load(selectedTaskId, {
+  subtasks: [{}]  // Now load its subtasks
+});
+```
+</CodeGroup>
+
+## Using a Loading Cache
+
+By default, Jazz maintains a cache of loaded CoValues to avoid unnecessary network requests. This means that if you've already loaded a CoValue, subsequent load requests will use the cached version unless you explicitly request a refresh.
+
+<CodeGroup>
+```ts
+// First load: fetches from network or local storage
+const project = await Project.load(projectId, {});
+
+// Later loads: uses cached version if available
+const sameProject = await Project.load(projectId, {});
+```
+</CodeGroup>
+
+## Best Practices
+
+1. **Be explicit about loading depths**: Always specify exactly what you need
+2. **Clean up subscriptions**: Always store and call the unsubscribe function when you're done
+3. **Handle loading states**: Check for undefined/null before accessing properties
+4. **Use framework integrations**: They handle subscription lifecycle automatically
+5. **Balance depth and performance**: Load only what you need for the current view
+
+By effectively using subscriptions and deep loading, you can build responsive, collaborative applications that handle complex data relationships while maintaining good performance.

homepage/homepage/app/(docs)/docs/[framework]/[...slug]/using-covalues/writing.mdx

@@ -0,0 +1,175 @@
+export const metadata = { title: "Writing & deleting CoValues" };
+import { CodeGroup } from "@/components/forMdx";
+
+# Writing & deleting CoValues
+
+Collaborative applications need ways to update and remove data. Jazz makes this simple by treating CoValues like regular JavaScript objects while handling all the complexity of syncing changes in the background. This page covers how to modify CoValues, work with collections, handle concurrent edits, and properly remove data when needed.
+
+## Writing to CoValues
+
+Once you have a CoValue, modifying it is straightforward. You can update fields like regular JavaScript properties. Changes are applied locally first for immediate feedback, then synchronized to other users with access to the same CoValues. This approach provides a natural programming model while handling all the distributed systems complexity behind the scenes.
+
+<CodeGroup>
+```ts
+class Task extends CoMap {
+  title = co.string;
+  status = co.literal("todo", "in-progress", "completed");
+  assignee = co.optional.string;
+}
+
+//...
+
+// Update fields
+task.status = "in-progress";             // Direct assignment
+task.assignee = "Alex";                  // Optional field
+```
+</CodeGroup>
+
+### Working with Lists
+
+CoLists support familiar array operations, making it easy to work with collections of data. You can add, remove, and modify items using the standard JavaScript array methods, while Jazz handles the collaborative aspects automatically. These operations work correctly even when multiple users are making changes simultaneously.
+
+<CodeGroup>
+```ts
+class Project extends CoMap {
+  name = co.string;
+  tasks = co.ref(ListOfTasks);
+}
+
+//...
+
+// Add items
+project.tasks.push(Task.create({
+  title: "Build raised beds",
+  status: "todo"
+}));
+
+// Remove items
+project.tasks.splice(2, 1);  // Remove third task
+
+// Update items
+project.tasks[0].status = "in-progress";
+
+// Bulk updates
+project.tasks.forEach(task => {
+  if (task.status === "todo") {
+    task.status = "in-progress";
+  }
+});
+```
+</CodeGroup>
+
+Changes sync automatically to everyone with access. Any edits you make are immediately visible in your local view and propagate to other users as they sync.
+
+## Concurrent Edits
+
+CoValues use [CRDTs](/docs/schemas/covalues#defining-schemas-covalues) to handle concurrent edits smoothly. In most cases, you don't need to think about conflicts - Jazz handles them automatically. This conflict resolution happens transparently, allowing multiple users to make changes simultaneously without disruption or data loss.
+
+<CodeGroup>
+```ts
+class Dashboard extends CoMap {
+  activeProjects = co.number;
+  status = co.literal("active", "maintenance");
+  notifications = co.ref(ListOfNotifications);
+}
+
+//...
+
+// Multiple users can edit simultaneously
+// Last-write-wins for simple fields
+dashboard.status = "maintenance";     // Local change is immediate
+dashboard.activeProjects = 5;         // Syncs automatically
+
+// Lists handle concurrent edits too
+dashboard.notifications.push(Notification.create({
+  timestamp: new Date(),
+  message: "System update scheduled"
+}));
+```
+</CodeGroup>
+
+## Deleting CoValues
+
+There are a few ways to delete CoValues, from simple field removal to full cleanup. Jazz provides flexible options for removing data depending on your needs. You can remove references while keeping the underlying data, remove items from lists, or completely delete CoValues when they're no longer needed.
+
+<CodeGroup>
+```ts
+class Project extends CoMap {
+  tasks = co.ref(ListOfTasks);
+  resources = co.optional.ref(ListOfResources);
+}
+
+//...
+
+// Remove a reference
+project.resources = null;  // Removes the reference but resources still exist
+
+// Remove from a list
+project.tasks.splice(2, 1);  // Removes third team member from list
+```
+</CodeGroup>
+
+### Best Practices
+
+- Load everything you plan to delete
+- Check permissions before attempting deletes
+- Consider soft deletes for recoverable data
+
+## Removing Data in CoValues
+
+You can delete fields from any `CoMap` to remove specific properties while keeping the CoValue itself. This is useful when you need to clear certain data without affecting the rest of your object structure. The deletion operations are also synchronized to all users with access.
+
+<CodeGroup>
+```ts
+class Project extends CoMap {
+  name = co.string;
+  team = co.ref(ListOfMembers);
+  budget = co.optional.ref(Budget);
+}
+
+//...
+
+// Delete fields from a regular CoMap
+delete project.budget;  // Removes the budget reference
+
+// Delete from a record-type CoMap
+class ProjectTags extends CoMap.Record(co.string) {}
+
+const projectTags = ProjectTags.create({
+  "priority-high": "High priority tasks",
+});
+
+delete projectTags["priority-high"]; // Removes specific tag
+
+```
+</CodeGroup>
+
+For `CoList`s, use array methods:
+
+<CodeGroup>
+```ts
+// Remove from lists using splice
+project.team.splice(2, 1);  // Removes third team member
+```
+</CodeGroup>
+
+### Restoring Data
+
+For data you might want to restore later, consider using status fields instead of permanent deletion. This "soft delete" pattern is common in applications where users might need to recover previously removed items. By using a boolean field to mark items as archived or deleted, you maintain the ability to restore them later.
+
+<CodeGroup>
+```ts
+class Task extends CoMap {
+  title = co.string;
+  archived = co.boolean;
+}
+
+// Mark as archived
+task.archived = true;
+
+// Restore later
+task.archived = false; // Task is back in the active list!
+```
+</CodeGroup>
+
+Removed data remains in the edit history. If you need to handle sensitive information, plan your data model accordingly.

homepage/homepage/app/(others)/cloud/page.tsx

@@ -1,25 +1,27 @@
 import { Pricing } from "@/components/Pricing";
 import { LatencyMap } from "@/components/cloud/latencyMap";
 import { GridCard } from "gcmp-design-system/src/app/components/atoms/GridCard";
-import {
-  H2,
-  H3,
-  H4,
-} from "gcmp-design-system/src/app/components/atoms/Headings";
-import { LI } from "gcmp-design-system/src/app/components/atoms/ListItem";
+import { H2, H3 } from "gcmp-design-system/src/app/components/atoms/Headings";
 import { P } from "gcmp-design-system/src/app/components/atoms/Paragraph";
 import { GappedGrid } from "gcmp-design-system/src/app/components/molecules/GappedGrid";
 import { HeroHeader } from "gcmp-design-system/src/app/components/molecules/HeroHeader";
-import { UL } from "gcmp-design-system/src/app/components/molecules/List";
 import { Prose } from "gcmp-design-system/src/app/components/molecules/Prose";
 import { SectionHeader } from "gcmp-design-system/src/app/components/molecules/SectionHeader";
+import type { Metadata } from "next";
 import CloudPlusBackup from "./cloudPlusBackup.mdx";
 import CloudPlusDIY from "./cloudPlusDIY.mdx";
 import CompletelyDIY from "./completelyDIY.mdx";
 
-export const metadata = {
-  title: "Jazz Cloud",
-  description: "Serverless sync & storage for Jazz apps.",
+const title = "Jazz Cloud";
+const description = "Serverless sync & storage for Jazz apps.";
+
+export const metadata: Metadata = {
+  title,
+  description,
+  openGraph: {
+    title,
+    description,
+  },
 };
 
 export default function Cloud() {

homepage/homepage/app/(others)/examples/page.tsx

@@ -11,6 +11,20 @@ import { H2 } from "gcmp-design-system/src/app/components/atoms/Headings";
 import { Icon } from "gcmp-design-system/src/app/components/atoms/Icon";
 import { GappedGrid } from "gcmp-design-system/src/app/components/molecules/GappedGrid";
 import { HeroHeader } from "gcmp-design-system/src/app/components/molecules/HeroHeader";
+import type { Metadata } from "next";
+
+const title = "Examples";
+const description =
+  "Find an example app with code most similar to what you want to build.";
+
+export const metadata: Metadata = {
+  title,
+  description,
+  openGraph: {
+    title,
+    description,
+  },
+};
 
 const MockButton = ({ children }: { children: React.ReactNode }) => (
   <p className="bg-blue-100 text-blue-800 py-1 px-3 rounded-full font-medium  text-xs inline-flex items-center justify-center">

homepage/homepage/app/(others)/showcase/page.tsx

@@ -1,11 +1,19 @@
 import { products } from "@/lib/showcase";
 import { HeroHeader } from "gcmp-design-system/src/app/components/molecules/HeroHeader";
+import type { Metadata } from "next";
 import Image from "next/image";
 import Link from "next/link";
 
-export const metadata = {
-  title: "Built with Jazz",
-  description: "Great apps by smart people.",
+const title = "Built with Jazz";
+const description = "Great apps by smart people.";
+
+export const metadata: Metadata = {
+  title,
+  description,
+  openGraph: {
+    title,
+    description,
+  },
 };
 
 export default function Page() {

homepage/homepage/app/(others)/status/page.tsx

@@ -1,8 +1,18 @@
 import { clsx } from "clsx";
 import { HeroHeader } from "gcmp-design-system/src/app/components/molecules/HeroHeader";
+import type { Metadata } from "next";
 import dynamic from "next/dynamic";
 import { Fragment } from "react";
 
+const title = "Status";
+
+export const metadata: Metadata = {
+  title,
+  openGraph: {
+    title,
+  },
+};
+
 const LatencyChart = dynamic(() => import("@/components/LatencyChart"), {
   ssr: false,
 });
@@ -133,11 +143,6 @@ const query = async () => {
   return byRegion;
 };
 
-export const metadata = {
-  title: "Status",
-  description: "Great apps by smart people.",
-};
-
 export default async function Page() {
   const byRegion = await query();
 

homepage/homepage/lib/docNavigationItems.js

@@ -111,28 +111,43 @@ export const docNavigationItems = [
     name: "Using CoValues",
     items: [
       {
-        name: "Creation & ownership",
-        href: "/docs/using-covalues/creation",
+        name: "CoMaps",
+        href: "/docs/using-covalues/comaps",
+        done: 80,
+      },
+      {
+        name: "CoLists",
+        href: "/docs/using-covalues/colists",
+        done: 80,
+      },
+      {
+        name: "CoFeeds",
+        href: "/docs/using-covalues/cofeeds",
+        done: 80,
+      },
+      {
+        name: "FileStreams",
+        href: "/docs/using-covalues/filestreams",
         done: 0,
       },
       {
-        name: "Reading",
-        href: "/docs/using-covalues/reading",
+        name: "SchemaUnions",
+        href: "/docs/using-covalues/schemaunions",
         done: 0,
       },
       {
-        name: "Subscribing & deep loading",
-        href: "/docs/using-covalues/subscription-and-loading",
+        name: "Loading & subscribing",
+        href: "/docs/using-covalues/loading-and-subscribing",
         done: 0,
       },
       {
-        name: "Writing & deleting",
-        href: "/docs/using-covalues/writing",
+        name: "History & time travel",
+        href: "/docs/using-covalues/history-and-time-travel",
         done: 0,
       },
       {
-        name: "Metadata & time-travel",
-        href: "/docs/using-covalues/metadata",
+        name: "Access control",
+        href: "/docs/using-covalues/access-control",
         done: 0,
       },
     ],

homepage/homepage/next.config.mjs

@@ -37,7 +37,7 @@ const config = {
 function highlightPlugin() {
   return async function transformer(tree) {
     const highlighter = await getHighlighter({
-      langs: ["typescript", "bash", "tsx", "json", "svelte"],
+      langs: ["typescript", "bash", "tsx", "json", "svelte", "vue"],
       theme: "css-variables", // use css variables in shiki.css
     });
 

packages/cojson-storage-rn-sqlite/src/client.ts

@@ -1,7 +1,7 @@
-import { type DB as DatabaseT } from "@op-engineering/op-sqlite";
-import {
+import type { DB as DatabaseT } from "@op-engineering/op-sqlite";
+import type {
   CojsonInternalTypes,
-  type OutgoingSyncQueue,
+  OutgoingSyncQueue,
   RawCoID,
   SessionID,
 } from "cojson";
@@ -29,14 +29,25 @@ export class SQLiteClient implements DBClientInterface {
 
     if (!rows || rows.length === 0) return;
 
-    const coValueRow = rows[0] as any & { rowID: number };
+    type DbCoValueRow = {
+      id: string;
+      header: string;
+      rowID: number;
+      [key: string]: unknown;
+    };
+
+    const coValueRow = rows[0] as DbCoValueRow;
     try {
       const parsedHeader =
-        coValueRow?.header &&
-        (JSON.parse(coValueRow.header) as CojsonInternalTypes.CoValueHeader);
+        coValueRow?.header && coValueRow.header.trim() !== ""
+          ? (JSON.parse(coValueRow.header) as CojsonInternalTypes.CoValueHeader)
+          : undefined;
+
+      if (!parsedHeader) return undefined;
 
       return {
         ...coValueRow,
+        id: coValueId,
         header: parsedHeader,
       };
     } catch (e) {
@@ -76,10 +87,13 @@ export class SQLiteClient implements DBClientInterface {
     if (!rows || rows.length === 0) return [];
 
     try {
-      return rows.map((row: any) => ({
-        ...row,
-        tx: JSON.parse(row.tx) as CojsonInternalTypes.Transaction,
-      }));
+      return rows.map((row) => {
+        const rowData = row as { ses: number; idx: number; tx: string };
+        return {
+          ...rowData,
+          tx: JSON.parse(rowData.tx) as CojsonInternalTypes.Transaction,
+        };
+      });
     } catch (e) {
       console.warn("Invalid JSON in transaction", e);
       return [];
@@ -126,7 +140,7 @@ export class SQLiteClient implements DBClientInterface {
         sessionUpdate.sessionID,
         sessionUpdate.lastIdx,
         sessionUpdate.lastSignature,
-        sessionUpdate.bytesSinceLastSignature!,
+        sessionUpdate.bytesSinceLastSignature ?? 0,
       ],
     );
     return rows[0]?.rowID as number;

packages/cojson-storage-rn-sqlite/src/sqlite-react-native.ts

@@ -113,7 +113,7 @@ export class SQLiteReactNative {
       );
 
       await db.execute(
-        `CREATE INDEX IF NOT EXISTS sessionsByCoValue ON sessions (coValue);`,
+        "CREATE INDEX IF NOT EXISTS sessionsByCoValue ON sessions (coValue);",
       );
 
       await db.execute(
@@ -125,7 +125,7 @@ export class SQLiteReactNative {
       );
 
       await db.execute(
-        `CREATE INDEX IF NOT EXISTS coValuesByID ON coValues (id);`,
+        "CREATE INDEX IF NOT EXISTS coValuesByID ON coValues (id);",
       );
 
       await db.execute("PRAGMA user_version = 1");
@@ -142,7 +142,7 @@ export class SQLiteReactNative {
       );
 
       await db.execute(
-        `ALTER TABLE sessions ADD COLUMN bytesSinceLastSignature INTEGER;`,
+        "ALTER TABLE sessions ADD COLUMN bytesSinceLastSignature INTEGER;",
       );
 
       await db.execute("PRAGMA user_version = 3");

packages/cojson-storage-sqlite/src/sqliteClient.ts

@@ -1,14 +1,11 @@
-import { Database as DatabaseT } from "better-sqlite3";
+import type { Database as DatabaseT } from "better-sqlite3";
 import {
-  CojsonInternalTypes,
-  OutgoingSyncQueue,
-  SessionID,
+  type CojsonInternalTypes,
+  type OutgoingSyncQueue,
+  type SessionID,
   logger,
 } from "cojson";
-import RawCoID = CojsonInternalTypes.RawCoID;
-import Signature = CojsonInternalTypes.Signature;
-import Transaction = CojsonInternalTypes.Transaction;
-import {
+import type {
   DBClientInterface,
   SessionRow,
   SignatureAfterRow,
@@ -17,6 +14,10 @@ import {
   TransactionRow,
 } from "cojson-storage";
 
+type RawCoID = CojsonInternalTypes.RawCoID;
+type Signature = CojsonInternalTypes.Signature;
+type Transaction = CojsonInternalTypes.Transaction;
+
 export type RawCoValueRow = {
   id: CojsonInternalTypes.RawCoID;
   header: string;
@@ -43,7 +44,7 @@ export class SQLiteClient implements DBClientInterface {
 
   getCoValue(coValueId: RawCoID): StoredCoValueRow | undefined {
     const coValueRow = this.db
-      .prepare(`SELECT * FROM coValues WHERE id = ?`)
+      .prepare("SELECT * FROM coValues WHERE id = ?")
       .get(coValueId) as RawCoValueRow & { rowID: number };
 
     if (!coValueRow) return;
@@ -58,7 +59,7 @@ export class SQLiteClient implements DBClientInterface {
       };
     } catch (e) {
       const headerValue = coValueRow?.header ?? "";
-      logger.warn("Invalid JSON in header: " + headerValue, {
+      logger.warn(`Invalid JSON in header: ${headerValue}`, {
         id: coValueId,
       });
       return;
@@ -67,7 +68,7 @@ export class SQLiteClient implements DBClientInterface {
 
   getCoValueSessions(coValueRowId: number): StoredSessionRow[] {
     return this.db
-      .prepare<number>(`SELECT * FROM sessions WHERE coValue = ?`)
+      .prepare<number>("SELECT * FROM sessions WHERE coValue = ?")
       .all(coValueRowId) as StoredSessionRow[];
   }
 
@@ -77,7 +78,7 @@ export class SQLiteClient implements DBClientInterface {
   ): StoredSessionRow | undefined {
     return this.db
       .prepare<[number, string]>(
-        `SELECT * FROM sessions WHERE coValue = ? AND sessionID = ?`,
+        "SELECT * FROM sessions WHERE coValue = ? AND sessionID = ?",
       )
       .get(coValueRowId, sessionID) as StoredSessionRow | undefined;
   }
@@ -88,7 +89,7 @@ export class SQLiteClient implements DBClientInterface {
   ): TransactionRow[] {
     const txs = this.db
       .prepare<[number, number]>(
-        `SELECT * FROM transactions WHERE ses = ? AND idx >= ?`,
+        "SELECT * FROM transactions WHERE ses = ? AND idx >= ?",
       )
       .all(sessionRowId, firstNewTxIdx) as RawTransactionRow[];
 
@@ -109,7 +110,7 @@ export class SQLiteClient implements DBClientInterface {
   ): SignatureAfterRow[] {
     return this.db
       .prepare<[number, number]>(
-        `SELECT * FROM signatureAfter WHERE ses = ? AND idx >= ?`,
+        "SELECT * FROM signatureAfter WHERE ses = ? AND idx >= ?",
       )
       .all(sessionRowId, firstNewTxIdx) as SignatureAfterRow[];
   }
@@ -117,7 +118,7 @@ export class SQLiteClient implements DBClientInterface {
   addCoValue(msg: CojsonInternalTypes.NewContentMessage): number {
     return this.db
       .prepare<[CojsonInternalTypes.RawCoID, string]>(
-        `INSERT INTO coValues (id, header) VALUES (?, ?)`,
+        "INSERT INTO coValues (id, header) VALUES (?, ?)",
       )
       .run(msg.id, JSON.stringify(msg.header)).lastInsertRowid as number;
   }
@@ -153,7 +154,7 @@ export class SQLiteClient implements DBClientInterface {
   ) {
     this.db
       .prepare<[number, number, string]>(
-        `INSERT INTO transactions (ses, idx, tx) VALUES (?, ?, ?)`,
+        "INSERT INTO transactions (ses, idx, tx) VALUES (?, ?, ?)",
       )
       .run(sessionRowID, nextIdx, JSON.stringify(newTransaction));
   }
@@ -165,12 +166,13 @@ export class SQLiteClient implements DBClientInterface {
   }: { sessionRowID: number; idx: number; signature: Signature }) {
     this.db
       .prepare<[number, number, string]>(
-        `INSERT INTO signatureAfter (ses, idx, signature) VALUES (?, ?, ?)`,
+        "INSERT INTO signatureAfter (ses, idx, signature) VALUES (?, ?, ?)",
       )
       .run(sessionRowID, idx, signature);
   }
 
   transaction(operationsCallback: () => unknown) {
     this.db.transaction(operationsCallback)();
+    return undefined;
   }
 }

packages/cojson-storage-sqlite/src/sqliteNode.ts

@@ -1,12 +1,12 @@
-import Database, { Database as DatabaseT } from "better-sqlite3";
+import Database, { type Database as DatabaseT } from "better-sqlite3";
 import {
-  IncomingSyncStream,
-  OutgoingSyncQueue,
-  Peer,
+  type IncomingSyncStream,
+  type OutgoingSyncQueue,
+  type Peer,
   cojsonInternals,
   logger,
 } from "cojson";
-import { SyncManager, TransactionRow } from "cojson-storage";
+import { SyncManager, type TransactionRow } from "cojson-storage";
 import { SQLiteClient } from "./sqliteClient.js";
 
 export class SQLiteNode {
@@ -46,7 +46,7 @@ export class SQLiteNode {
               msg,
               (k, v) =>
                 k === "changes" || k === "encryptedChanges"
-                  ? v.slice(0, 20) + "..."
+                  ? `${v.slice(0, 20)}...`
                   : v,
             )}`,
           );
@@ -117,7 +117,7 @@ export class SQLiteNode {
       ).run();
 
       db.prepare(
-        `CREATE INDEX IF NOT EXISTS sessionsByCoValue ON sessions (coValue);`,
+        "CREATE INDEX IF NOT EXISTS sessionsByCoValue ON sessions (coValue);",
       ).run();
 
       db.prepare(
@@ -129,7 +129,7 @@ export class SQLiteNode {
       ).run();
 
       db.prepare(
-        `CREATE INDEX IF NOT EXISTS coValuesByID ON coValues (id);`,
+        "CREATE INDEX IF NOT EXISTS coValuesByID ON coValues (id);",
       ).run();
 
       db.pragma("user_version = 1");
@@ -138,17 +138,17 @@ export class SQLiteNode {
     if (oldVersion <= 1) {
       // fix embarrassing off-by-one error for transaction indices
       const txs = db
-        .prepare(`SELECT * FROM transactions`)
+        .prepare("SELECT * FROM transactions")
         .all() as TransactionRow[];
 
       for (const tx of txs) {
-        db.prepare(`DELETE FROM transactions WHERE ses = ? AND idx = ?`).run(
+        db.prepare("DELETE FROM transactions WHERE ses = ? AND idx = ?").run(
           tx.ses,
           tx.idx,
         );
         tx.idx -= 1;
         db.prepare(
-          `INSERT INTO transactions (ses, idx, tx) VALUES (?, ?, ?)`,
+          "INSERT INTO transactions (ses, idx, tx) VALUES (?, ?, ?)",
         ).run(tx.ses, tx.idx, tx.tx);
       }
 
@@ -166,7 +166,7 @@ export class SQLiteNode {
       ).run();
 
       db.prepare(
-        `ALTER TABLE sessions ADD COLUMN bytesSinceLastSignature INTEGER;`,
+        "ALTER TABLE sessions ADD COLUMN bytesSinceLastSignature INTEGER;",
       ).run();
 
       db.pragma("user_version = 3");

packages/cojson-storage/src/syncManager.ts

@@ -1,15 +1,15 @@
 import {
   CojsonInternalTypes,
   MAX_RECOMMENDED_TX_SIZE,
-  OutgoingSyncQueue,
-  SessionID,
-  SyncMessage,
+  type OutgoingSyncQueue,
+  type SessionID,
+  type SyncMessage,
   cojsonInternals,
   emptyKnownState,
   logger,
 } from "cojson";
 import { collectNewTxs, getDependedOnCoValues } from "./syncUtils.js";
-import { DBClientInterface, StoredSessionRow } from "./types.js";
+import type { DBClientInterface, StoredSessionRow } from "./types.js";
 import NewContentMessage = CojsonInternalTypes.NewContentMessage;
 import KnownStateMessage = CojsonInternalTypes.KnownStateMessage;
 import RawCoID = CojsonInternalTypes.RawCoID;
@@ -82,12 +82,15 @@ export class SyncManager {
 
     // reverse it to send the top level id the last in the order
     const collectedMessages = Object.values(outputMessages).reverse();
-    collectedMessages.forEach(({ knownMessage, contentMessages }) => {
+    for (const { knownMessage, contentMessages } of collectedMessages) {
       this.sendStateMessage(knownMessage);
 
-      contentMessages?.length &&
-        contentMessages.forEach((msg) => this.sendStateMessage(msg));
-    });
+      if (contentMessages?.length) {
+        for (const msg of contentMessages) {
+          this.sendStateMessage(msg);
+        }
+      }
+    }
   }
 
   private async collectCoValueData(
@@ -106,7 +109,9 @@ export class SyncManager {
         action: "known",
         ...emptyKnownState(peerKnownState.id),
       };
-      asDependencyOf && (emptyKnownMessage.asDependencyOf = asDependencyOf);
+      if (asDependencyOf) {
+        emptyKnownMessage.asDependencyOf = asDependencyOf;
+      }
       messageMap[peerKnownState.id] = { knownMessage: emptyKnownMessage };
       return messageMap;
     }
@@ -153,7 +158,9 @@ export class SyncManager {
       action: "known",
       ...newCoValueKnownState,
     };
-    asDependencyOf && (knownMessage.asDependencyOf = asDependencyOf);
+    if (asDependencyOf) {
+      knownMessage.asDependencyOf = asDependencyOf;
+    }
     messageMap[newCoValueKnownState.id] = {
       knownMessage: knownMessage,
       contentMessages: newContentMessages,
@@ -272,11 +279,13 @@ export class SyncManager {
 
     const nextIdx = sessionRow?.lastIdx || 0;
 
+    if (!msg.new[sessionID]) throw new Error("Session ID not found");
+
     const sessionUpdate = {
       coValue: storedCoValueRowID,
       sessionID,
       lastIdx: newLastIdx,
-      lastSignature: msg.new[sessionID]!.lastSignature,
+      lastSignature: msg.new[sessionID].lastSignature,
       bytesSinceLastSignature: newBytesSinceLastSignature,
     };
 
@@ -289,7 +298,7 @@ export class SyncManager {
       await this.dbClient.addSignatureAfter({
         sessionRowID,
         idx: newLastIdx - 1,
-        signature: msg.new[sessionID]!.lastSignature,
+        signature: msg.new[sessionID].lastSignature,
       });
     }
 
@@ -306,7 +315,11 @@ export class SyncManager {
 
   handleDone(_msg: CojsonInternalTypes.DoneMessage) {}
 
-  async sendStateMessage(msg: any): Promise<unknown> {
+  async sendStateMessage(
+    msg:
+      | CojsonInternalTypes.KnownStateMessage
+      | CojsonInternalTypes.NewContentMessage,
+  ): Promise<unknown> {
     return this.toLocalNode
       .push(msg)
       .catch((e) =>

packages/cojson-storage/src/syncUtils.ts

@@ -1,11 +1,15 @@
 import {
-  CojsonInternalTypes,
-  JsonValue,
-  SessionID,
-  Stringified,
+  type CojsonInternalTypes,
+  type JsonValue,
+  type SessionID,
+  type Stringified,
   cojsonInternals,
 } from "cojson";
-import { StoredCoValueRow, StoredSessionRow, TransactionRow } from "./types.js";
+import type {
+  StoredCoValueRow,
+  StoredSessionRow,
+  TransactionRow,
+} from "./types.js";
 
 export function collectNewTxs({
   newTxsInSession,
@@ -19,19 +23,17 @@ export function collectNewTxs({
   firstNewTxIdx: number;
 }) {
   for (const tx of newTxsInSession) {
-    let sessionEntry =
-      newContentMessages[newContentMessages.length - 1]!.new[
-        sessionRow.sessionID
-      ];
+    const lastMessage = newContentMessages[newContentMessages.length - 1];
+    if (!lastMessage) return;
+
+    let sessionEntry = lastMessage.new[sessionRow.sessionID];
     if (!sessionEntry) {
       sessionEntry = {
         after: firstNewTxIdx,
         lastSignature: "WILL_BE_REPLACED" as CojsonInternalTypes.Signature,
         newTransactions: [],
       };
-      newContentMessages[newContentMessages.length - 1]!.new[
-        sessionRow.sessionID
-      ] = sessionEntry;
+      lastMessage.new[sessionRow.sessionID] = sessionEntry;
     }
 
     sessionEntry.newTransactions.push(tx.tx);

packages/cojson-storage/src/tests/syncManager.test.ts

@@ -1,5 +1,5 @@
 import {
-  Mocked,
+  type Mocked,
   afterEach,
   beforeEach,
   describe,
@@ -8,7 +8,7 @@ import {
   vi,
 } from "vitest";
 
-import {
+import type {
   CojsonInternalTypes,
   OutgoingSyncQueue,
   SessionID,
@@ -16,11 +16,12 @@ import {
 } from "cojson";
 import { SyncManager } from "../syncManager.js";
 import { getDependedOnCoValues } from "../syncUtils.js";
-import { DBClientInterface } from "../types.js";
+import type { DBClientInterface } from "../types.js";
 import { fixtures } from "./fixtureMessages.js";
-import RawCoID = CojsonInternalTypes.RawCoID;
-import NewContentMessage = CojsonInternalTypes.NewContentMessage;
 
+type RawCoID = CojsonInternalTypes.RawCoID;
+type NewContentMessage = CojsonInternalTypes.NewContentMessage;
+type Transaction = CojsonInternalTypes.Transaction;
 vi.mock("../syncUtils");
 
 const coValueIdToLoad = "co_zKwG8NyfZ8GXqcjDHY4NS3SbU2m";
@@ -40,7 +41,7 @@ const incomingContentMessage = fixtures[coValueIdToLoad].getContent({
 
 describe("DB sync manager", () => {
   let syncManager: SyncManager;
-  let queue: OutgoingSyncQueue = {} as unknown as OutgoingSyncQueue;
+  const queue: OutgoingSyncQueue = {} as unknown as OutgoingSyncQueue;
 
   const DBClient = vi.fn();
   DBClient.prototype.getCoValue = vi.fn();
@@ -154,11 +155,11 @@ describe("DB sync manager", () => {
         header: true,
         id: coValueIdToLoad,
         sessions: sessionsData.reduce(
-          (acc, sessionRow) => ({
-            ...acc,
-            [sessionRow.sessionID]: sessionRow.lastIdx,
-          }),
-          {},
+          (acc, sessionRow) => {
+            acc[sessionRow.sessionID] = sessionRow.lastIdx;
+            return acc;
+          },
+          {} as Record<string, number>,
         ),
       });
 
@@ -167,15 +168,22 @@ describe("DB sync manager", () => {
         header: coValueHeader,
         id: coValueIdToLoad,
         new: sessionsData.reduce(
-          (acc, sessionRow) => ({
-            ...acc,
-            [sessionRow.sessionID]: {
+          (acc, sessionRow) => {
+            acc[sessionRow.sessionID] = {
               after: expect.any(Number),
               lastSignature: expect.any(String),
               newTransactions: expect.any(Array),
-            },
-          }),
-          {},
+            };
+            return acc;
+          },
+          {} as Record<
+            string,
+            {
+              after: number;
+              lastSignature: string;
+              newTransactions: Transaction[];
+            }
+          >,
         ),
         priority: 0,
       });

packages/cojson-storage/src/types.ts

@@ -1,7 +1,8 @@
-import { CojsonInternalTypes, SessionID } from "cojson";
-import RawCoID = CojsonInternalTypes.RawCoID;
-import Transaction = CojsonInternalTypes.Transaction;
-import Signature = CojsonInternalTypes.Signature;
+import type { CojsonInternalTypes, SessionID } from "cojson";
+
+type RawCoID = CojsonInternalTypes.RawCoID;
+type Transaction = CojsonInternalTypes.Transaction;
+type Signature = CojsonInternalTypes.Signature;
 
 export type CoValueRow = {
   id: CojsonInternalTypes.RawCoID;
@@ -72,7 +73,7 @@ export interface DBClientInterface {
     sessionRowID: number,
     idx: number,
     newTransaction: Transaction,
-  ): Promise<number> | void | unknown;
+  ): Promise<number> | undefined | unknown;
 
   addSignatureAfter({
     sessionRowID,
@@ -82,7 +83,7 @@ export interface DBClientInterface {
     sessionRowID: number;
     idx: number;
     signature: Signature;
-  }): Promise<number> | void | unknown;
+  }): Promise<number> | undefined | unknown;
 
-  transaction(callback: () => unknown): Promise<unknown> | void;
+  transaction(callback: () => unknown): Promise<unknown> | undefined;
 }

packages/cojson-transport-ws/src/BatchedOutgoingMessages.ts

@@ -1,10 +1,10 @@
-import { SyncMessage } from "cojson";
+import type { SyncMessage } from "cojson";
 import { addMessageToBacklog } from "./serialization.js";
 
 export const MAX_OUTGOING_MESSAGES_CHUNK_BYTES = 25_000;
 
 export class BatchedOutgoingMessages {
-  private backlog: string = "";
+  private backlog = "";
   private timeout: ReturnType<typeof setTimeout> | null = null;
 
   constructor(private send: (messages: string) => void) {}

packages/cojson-transport-ws/src/WebSocketPeerWithReconnection.ts

@@ -1,4 +1,4 @@
-import { Peer, logger } from "cojson";
+import { type Peer, logger } from "cojson";
 import { createWebSocketPeer } from "./createWebSocketPeer.js";
 
 export class WebSocketPeerWithReconnection {
@@ -61,7 +61,7 @@ export class WebSocketPeerWithReconnection {
       const timeout = this.reconnectionTimeout * this.reconnectionAttempts;
 
       logger.debug(
-        "Websocket disconnected, trying to reconnect in " + timeout + "ms",
+        `Websocket disconnected, trying to reconnect in ${timeout}ms`,
       );
 
       await this.waitForOnline(timeout);

packages/cojson-transport-ws/src/createWebSocketPeer.ts

@@ -1,14 +1,14 @@
 import {
-  DisconnectedError,
-  Peer,
-  PingTimeoutError,
-  SyncMessage,
+  type DisconnectedError,
+  type Peer,
+  type PingTimeoutError,
+  type SyncMessage,
   cojsonInternals,
   logger,
 } from "cojson";
 import { BatchedOutgoingMessages } from "./BatchedOutgoingMessages.js";
 import { deserializeMessages, getErrorMessage } from "./serialization.js";
-import { AnyWebSocket } from "./types.js";
+import type { AnyWebSocket } from "./types.js";
 
 export const BUFFER_LIMIT = 100_000;
 export const BUFFER_LIMIT_POLLING_INTERVAL = 10;
@@ -52,7 +52,7 @@ function waitForWebSocketOpen(websocket: AnyWebSocket) {
     if (websocket.readyState === 1) {
       resolve();
     } else {
-      websocket.addEventListener("open", resolve, { once: true });
+      websocket.addEventListener("open", () => resolve(), { once: true });
     }
   });
 }
@@ -144,6 +144,8 @@ export function createWebSocketPeer({
   }
 
   websocket.addEventListener("close", handleClose);
+  // TODO (#1537): Remove this any once the WebSocket error event type is fixed
+  // biome-ignore lint/suspicious/noExplicitAny: WebSocket error event type
   websocket.addEventListener("error" as any, (err) => {
     if (err.message) {
       logger.warn(err.message);
@@ -174,7 +176,7 @@ export function createWebSocketPeer({
 
     if (!result.ok) {
       logger.warn(
-        "Error while deserializing messages: " + getErrorMessage(result.error),
+        `Error while deserializing messages: ${getErrorMessage(result.error)}`,
       );
       return;
     }
@@ -227,7 +229,7 @@ export function createWebSocketPeer({
             },
             { once: true },
           );
-        } else if (websocket.readyState == 1) {
+        } else if (websocket.readyState === 1) {
           websocket.close();
         }
       },

packages/cojson-transport-ws/src/serialization.ts

@@ -1,5 +1,5 @@
-import { SyncMessage, logger } from "cojson";
-import { PingMsg } from "./types.js";
+import { type SyncMessage, logger } from "cojson";
+import type { PingMsg } from "./types.js";
 
 export function getErrorMessage(error: unknown) {
   return error instanceof Error ? error.message : "Unknown error";
@@ -28,7 +28,7 @@ export function deserializeMessages(messages: unknown) {
         | PingMsg[],
     } as const;
   } catch (e) {
-    logger.error("Error while deserializing messages: " + getErrorMessage(e));
+    logger.error(`Error while deserializing messages: ${getErrorMessage(e)}`);
     return {
       ok: false,
       error: e,

packages/cojson-transport-ws/src/tests/BatchedOutgoingMessages.test.ts

@@ -1,5 +1,5 @@
-import { SyncMessage } from "cojson";
-import { CojsonInternalTypes } from "cojson";
+import type { SyncMessage } from "cojson";
+import type { CojsonInternalTypes } from "cojson";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import {
   BatchedOutgoingMessages,

packages/cojson-transport-ws/src/tests/createWebSocketPeer.test.ts

@@ -1,14 +1,14 @@
-import { SyncMessage } from "cojson";
+import type { SyncMessage } from "cojson";
 import type { Channel } from "queueueue";
-import { Mocked, describe, expect, test, vi } from "vitest";
+import { type Mocked, describe, expect, test, vi } from "vitest";
 import { MAX_OUTGOING_MESSAGES_CHUNK_BYTES } from "../BatchedOutgoingMessages.js";
 import {
   BUFFER_LIMIT,
   BUFFER_LIMIT_POLLING_INTERVAL,
-  CreateWebSocketPeerOpts,
+  type CreateWebSocketPeerOpts,
   createWebSocketPeer,
 } from "../createWebSocketPeer.js";
-import { AnyWebSocket } from "../types.js";
+import type { AnyWebSocket } from "../types.js";
 
 function setup(opts: Partial<CreateWebSocketPeerOpts> = {}) {
   const listeners = new Map<string, (event: MessageEvent) => void>();
@@ -472,6 +472,7 @@ describe("createWebSocketPeer", () => {
   });
 });
 
+// biome-ignore lint/suspicious/noConfusingVoidType: Test helper
 function waitFor(callback: () => boolean | void) {
   return new Promise<void>((resolve, reject) => {
     const checkPassed = () => {

packages/cojson-transport-ws/src/tests/syncServer.ts

@@ -1,7 +1,7 @@
-import { createServer } from "http";
+import { createServer } from "node:http";
 import { ControlledAgent, LocalNode } from "cojson";
 import { WasmCrypto } from "cojson/crypto/WasmCrypto";
-import { WebSocket, WebSocketServer } from "ws";
+import { type WebSocket, WebSocketServer } from "ws";
 import { createWebSocketPeer } from "../createWebSocketPeer";
 
 export const startSyncServer = async (port?: number) => {
@@ -75,16 +75,18 @@ export const startSyncServer = async (port?: number) => {
 
   server.listen(port ?? 0);
 
-  port = (server.address() as { port: number }).port;
-  const syncServer = `ws://localhost:${port}`;
+  const actualPort = (server.address() as { port: number }).port;
+  const syncServer = `ws://localhost:${actualPort}`;
 
   return {
     close: () => {
-      connections.forEach((ws) => ws.close());
+      for (const ws of connections) {
+        ws.close();
+      }
       server.close();
     },
     syncServer,
-    port,
+    port: actualPort,
     localNode,
   };
 };

packages/cojson-transport-ws/src/tests/utils.ts

@@ -1,3 +1,4 @@
+// biome-ignore lint/suspicious/noConfusingVoidType: Test helper
 export function waitFor(callback: () => boolean | void) {
   return new Promise<void>((resolve, reject) => {
     const checkPassed = () => {

packages/cojson-transport-ws/src/types.ts

@@ -1,7 +1,7 @@
 export interface WebsocketEvents {
   close: { code: number; reason: string };
   message: { data: unknown };
-  open: void;
+  open: unknown;
 }
 
 export interface PingMsg {

packages/cojson/src/coValueCore.ts

@@ -184,9 +184,7 @@ export class CoValueCore {
       this.header.meta?.type === "account"
         ? (this.node.currentSessionID.replace(
             this.node.account.id,
-            this.node.account
-              .currentAgentID()
-              ._unsafeUnwrap({ withStackTrace: true }),
+            this.node.account.currentAgentID(),
           ) as SessionID)
         : this.node.currentSessionID;
 
@@ -455,9 +453,7 @@ export class CoValueCore {
       this.header.meta?.type === "account"
         ? (this.node.currentSessionID.replace(
             this.node.account.id,
-            this.node.account
-              .currentAgentID()
-              ._unsafeUnwrap({ withStackTrace: true }),
+            this.node.account.currentAgentID(),
           ) as SessionID)
         : this.node.currentSessionID;
 
@@ -639,9 +635,7 @@ export class CoValueCore {
       // Try to find key revelation for us
       const lookupAccountOrAgentID =
         this.header.meta?.type === "account"
-          ? this.node.account
-              .currentAgentID()
-              ._unsafeUnwrap({ withStackTrace: true })
+          ? this.node.account.currentAgentID()
           : this.node.account.id;
 
       const lastReadyKeyEdit = content.lastEditAt(

packages/cojson/src/coValues/account.ts

@@ -1,4 +1,3 @@
-import { Result, ok } from "neverthrow";
 import { CoID, RawCoValue } from "../coValue.js";
 import {
   CoValueCore,
@@ -47,10 +46,11 @@ export class RawAccount<
 > extends RawGroup<Meta> {
   _cachedCurrentAgentID: AgentID | undefined;
 
-  currentAgentID(): Result<AgentID, InvalidAccountAgentIDError> {
+  currentAgentID(): AgentID {
     if (this._cachedCurrentAgentID) {
-      return ok(this._cachedCurrentAgentID);
+      return this._cachedCurrentAgentID;
     }
+
     const agents = this.keys()
       .filter((k): k is AgentID => k.startsWith("sealer_"))
       .sort(
@@ -65,7 +65,7 @@ export class RawAccount<
 
     this._cachedCurrentAgentID = agents[0];
 
-    return ok(agents[0]!);
+    return agents[0]!;
   }
 
   createInvite(_: AccountRole): InviteSecret {
@@ -77,10 +77,10 @@ export interface ControlledAccountOrAgent {
   id: RawAccountID | AgentID;
   agentSecret: AgentSecret;
 
-  currentAgentID: () => Result<AgentID, InvalidAccountAgentIDError>;
-  currentSignerID: () => Result<SignerID, InvalidAccountAgentIDError>;
+  currentAgentID: () => AgentID;
+  currentSignerID: () => SignerID;
   currentSignerSecret: () => SignerSecret;
-  currentSealerID: () => Result<SealerID, InvalidAccountAgentIDError>;
+  currentSealerID: () => SealerID;
   currentSealerSecret: () => SealerSecret;
 }
 
@@ -116,17 +116,17 @@ export class RawControlledAccount<Meta extends AccountMeta = AccountMeta>
     return this.core.node.acceptInvite(groupOrOwnedValueID, inviteSecret);
   }
 
-  currentAgentID(): Result<AgentID, InvalidAccountAgentIDError> {
+  currentAgentID(): AgentID {
     if (this._cachedCurrentAgentID) {
-      return ok(this._cachedCurrentAgentID);
+      return this._cachedCurrentAgentID;
     }
     const agentID = this.crypto.getAgentID(this.agentSecret);
     this._cachedCurrentAgentID = agentID;
-    return ok(agentID);
+    return agentID;
   }
 
   currentSignerID() {
-    return this.currentAgentID().map((id) => this.crypto.getAgentSignerID(id));
+    return this.crypto.getAgentSignerID(this.currentAgentID());
   }
 
   currentSignerSecret(): SignerSecret {
@@ -134,7 +134,7 @@ export class RawControlledAccount<Meta extends AccountMeta = AccountMeta>
   }
 
   currentSealerID() {
-    return this.currentAgentID().map((id) => this.crypto.getAgentSealerID(id));
+    return this.crypto.getAgentSealerID(this.currentAgentID());
   }
 
   currentSealerSecret(): SealerSecret {
@@ -153,11 +153,11 @@ export class ControlledAgent implements ControlledAccountOrAgent {
   }
 
   currentAgentID() {
-    return ok(this.crypto.getAgentID(this.agentSecret));
+    return this.crypto.getAgentID(this.agentSecret);
   }
 
   currentSignerID() {
-    return this.currentAgentID().map((id) => this.crypto.getAgentSignerID(id));
+    return this.crypto.getAgentSignerID(this.currentAgentID());
   }
 
   currentSignerSecret(): SignerSecret {
@@ -165,7 +165,7 @@ export class ControlledAgent implements ControlledAccountOrAgent {
   }
 
   currentSealerID() {
-    return this.currentAgentID().map((id) => this.crypto.getAgentSealerID(id));
+    return this.crypto.getAgentSealerID(this.currentAgentID());
   }
 
   currentSealerSecret(): SealerSecret {

packages/cojson/src/coValues/group.ts

@@ -251,9 +251,7 @@ export class RawGroup<
 
     const memberKey = typeof account === "string" ? account : account.id;
     const agent =
-      typeof account === "string"
-        ? account
-        : account.currentAgentID()._unsafeUnwrap({ withStackTrace: true });
+      typeof account === "string" ? account : account.currentAgentID();
 
     /**
      * WriteOnly members can only see their own changes.

packages/cojson/src/localNode.ts

@@ -530,7 +530,7 @@ export class LocalNode {
       } satisfies UnexpectedlyNotAccountError);
     }
 
-    return (coValue.getCurrentContent() as RawAccount).currentAgentID();
+    return ok((coValue.getCurrentContent() as RawAccount).currentAgentID());
   }
 
   resolveAccountAgentAsync(
@@ -573,7 +573,7 @@ export class LocalNode {
         } satisfies UnexpectedlyNotAccountError);
       }
 
-      return (coValue.getCurrentContent() as RawAccount).currentAgentID();
+      return ok((coValue.getCurrentContent() as RawAccount).currentAgentID());
     });
   }
 
@@ -601,9 +601,7 @@ export class LocalNode {
       this.crypto.seal({
         message: readKey.secret,
         from: this.account.currentSealerSecret(),
-        to: this.account
-          .currentSealerID()
-          ._unsafeUnwrap({ withStackTrace: true }),
+        to: this.account.currentSealerID(),
         nOnceMaterial: {
           in: groupCoValue.id,
           tx: groupCoValue.nextTransactionID(),

packages/cojson/src/permissions.ts

@@ -476,16 +476,7 @@ function agentInAccountOrMemberInGroup(
   groupAtTime: RawGroup,
 ): RawAccountID | AgentID | undefined {
   if (transactor === groupAtTime.id && groupAtTime instanceof RawAccount) {
-    return groupAtTime.currentAgentID().match(
-      (agentID) => agentID,
-      (e) => {
-        logger.error(
-          "Error while determining current agent ID in valid transactions",
-          e,
-        );
-        return undefined;
-      },
-    );
+    return groupAtTime.currentAgentID();
   }
   return transactor;
 }

packages/cojson/src/tests/coValueCore.test.ts

@@ -155,7 +155,7 @@ test("New transactions in a group correctly update owned values, including subsc
 
   map.subscribe(listener);
 
-  expect(listener.mock.calls[0][0].get("hello")).toBe("world");
+  expect(listener.mock.calls[0]?.[0].get("hello")).toBe("world");
 
   const resignationThatWeJustLearnedAbout = {
     privacy: "trusting",
@@ -192,7 +192,7 @@ test("New transactions in a group correctly update owned values, including subsc
   expect(manuallyAdddedTxSuccess).toBe(true);
 
   expect(listener.mock.calls.length).toBe(2);
-  expect(listener.mock.calls[1][0].get("hello")).toBe(undefined);
+  expect(listener.mock.calls[1]?.[0].get("hello")).toBe(undefined);
 
   expect(map.core.getValidSortedTransactions().length).toBe(0);
 });

packages/cojson/src/tests/permissions.test.ts

@@ -358,7 +358,7 @@ test("Admins can set group read key and then use it to create and read private t
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -412,7 +412,7 @@ test("Admins can set group read key and then writers can use it to create and re
   const revelation1 = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -424,7 +424,7 @@ test("Admins can set group read key and then writers can use it to create and re
   const revelation2 = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: writer.currentSealerID()._unsafeUnwrap(),
+    to: writer.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -491,7 +491,7 @@ test("Admins can set group read key and then use it to create private transactio
   const revelation1 = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -503,7 +503,7 @@ test("Admins can set group read key and then use it to create private transactio
   const revelation2 = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: reader.currentSealerID()._unsafeUnwrap(),
+    to: reader.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -578,7 +578,7 @@ test("Admins can set group read key and then use it to create private transactio
   const revelation1 = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -590,7 +590,7 @@ test("Admins can set group read key and then use it to create private transactio
   const revelation2 = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: reader1.currentSealerID()._unsafeUnwrap(),
+    to: reader1.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -629,7 +629,7 @@ test("Admins can set group read key and then use it to create private transactio
   const revelation3 = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: reader2.currentSealerID()._unsafeUnwrap(),
+    to: reader2.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -694,7 +694,7 @@ test("Admins can set group read key, make a private transaction in an owned obje
   const revelation1 = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -724,7 +724,7 @@ test("Admins can set group read key, make a private transaction in an owned obje
   const revelation2 = Crypto.seal({
     message: readKey2,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -777,7 +777,7 @@ test("Admins can set group read key, make a private transaction in an owned obje
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -804,7 +804,7 @@ test("Admins can set group read key, make a private transaction in an owned obje
   const revelation2 = Crypto.seal({
     message: readKey2,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -816,7 +816,7 @@ test("Admins can set group read key, make a private transaction in an owned obje
   const revelation3 = Crypto.seal({
     message: readKey2,
     from: admin.currentSealerSecret(),
-    to: reader.currentSealerID()._unsafeUnwrap(),
+    to: reader.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -912,7 +912,7 @@ test("Admins can set group read rey, make a private transaction in an owned obje
   const revelation1 = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -924,7 +924,7 @@ test("Admins can set group read rey, make a private transaction in an owned obje
   const revelation2 = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: reader.currentSealerID()._unsafeUnwrap(),
+    to: reader.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -936,7 +936,7 @@ test("Admins can set group read rey, make a private transaction in an owned obje
   const revelation3 = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: reader2.currentSealerID()._unsafeUnwrap(),
+    to: reader2.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -982,7 +982,7 @@ test("Admins can set group read rey, make a private transaction in an owned obje
   const newRevelation1 = Crypto.seal({
     message: readKey2,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -994,7 +994,7 @@ test("Admins can set group read rey, make a private transaction in an owned obje
   const newRevelation2 = Crypto.seal({
     message: readKey2,
     from: admin.currentSealerSecret(),
-    to: reader2.currentSealerID()._unsafeUnwrap(),
+    to: reader2.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -1119,7 +1119,7 @@ test("Admins can create an adminInvite, which can add an admin", () => {
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -1229,7 +1229,7 @@ test("Admins can create a writerInvite, which can add a writer", () => {
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -1332,7 +1332,7 @@ test("Admins can create a readerInvite, which can add a reader", () => {
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -1425,7 +1425,7 @@ test("WriterInvites can not invite admins", () => {
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -1479,7 +1479,7 @@ test("ReaderInvites can not invite admins", () => {
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -1533,7 +1533,7 @@ test("ReaderInvites can not invite writers", () => {
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -1587,7 +1587,7 @@ test("WriteOnlyInvites can not invite writers", () => {
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -1641,7 +1641,7 @@ test("WriteOnlyInvites can not invite admins", () => {
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -1695,7 +1695,7 @@ test("WriteOnlyInvites can invite writeOnly", () => {
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -1749,7 +1749,7 @@ test("WriteOnlyInvites can set writeKeys", () => {
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -1800,7 +1800,7 @@ test("Invites can't override key revelations", () => {
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -1855,7 +1855,7 @@ test("WriteOnlyInvites can't override writeKeys", () => {
   const revelation = Crypto.seal({
     message: readKey,
     from: admin.currentSealerSecret(),
-    to: admin.currentSealerID()._unsafeUnwrap(),
+    to: admin.currentSealerID(),
     nOnceMaterial: {
       in: groupCore.id,
       tx: groupCore.nextTransactionID(),
@@ -1929,7 +1929,7 @@ test("Can give read permission to 'everyone'", () => {
     childObject
       .testWithDifferentAccount(
         newAccount,
-        Crypto.newRandomSessionID(newAccount.currentAgentID()._unsafeUnwrap()),
+        Crypto.newRandomSessionID(newAccount.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -1955,7 +1955,7 @@ test("Can give read permissions to 'everyone' (high-level)", async () => {
     childObject.core
       .testWithDifferentAccount(
         new ControlledAgent(Crypto.newRandomAgentSecret(), Crypto),
-        Crypto.newRandomSessionID(newAccount.currentAgentID()._unsafeUnwrap()),
+        Crypto.newRandomSessionID(newAccount.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -1993,7 +1993,7 @@ test("Can give write permission to 'everyone'", async () => {
     childObject
       .testWithDifferentAccount(
         newAccount,
-        Crypto.newRandomSessionID(newAccount.currentAgentID()._unsafeUnwrap()),
+        Crypto.newRandomSessionID(newAccount.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -2025,7 +2025,7 @@ test("Can give write permissions to 'everyone' (high-level)", async () => {
     childObject.core
       .testWithDifferentAccount(
         newAccount,
-        Crypto.newRandomSessionID(newAccount.currentAgentID()._unsafeUnwrap()),
+        Crypto.newRandomSessionID(newAccount.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -2087,7 +2087,7 @@ test("Writers, readers and invitees can not set parent extensions", () => {
     group.core
       .testWithDifferentAccount(
         adminInvite,
-        Crypto.newRandomSessionID(adminInvite.currentAgentID()._unsafeUnwrap()),
+        Crypto.newRandomSessionID(adminInvite.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -2099,9 +2099,7 @@ test("Writers, readers and invitees can not set parent extensions", () => {
     group.core
       .testWithDifferentAccount(
         writerInvite,
-        Crypto.newRandomSessionID(
-          writerInvite.currentAgentID()._unsafeUnwrap(),
-        ),
+        Crypto.newRandomSessionID(writerInvite.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -2113,9 +2111,7 @@ test("Writers, readers and invitees can not set parent extensions", () => {
     group.core
       .testWithDifferentAccount(
         readerInvite,
-        Crypto.newRandomSessionID(
-          readerInvite.currentAgentID()._unsafeUnwrap(),
-        ),
+        Crypto.newRandomSessionID(readerInvite.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -2209,7 +2205,7 @@ test("Invitees can not set child extensions", () => {
     group.core
       .testWithDifferentAccount(
         adminInvite,
-        Crypto.newRandomSessionID(adminInvite.currentAgentID()._unsafeUnwrap()),
+        Crypto.newRandomSessionID(adminInvite.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -2221,9 +2217,7 @@ test("Invitees can not set child extensions", () => {
     group.core
       .testWithDifferentAccount(
         writerInvite,
-        Crypto.newRandomSessionID(
-          writerInvite.currentAgentID()._unsafeUnwrap(),
-        ),
+        Crypto.newRandomSessionID(writerInvite.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -2235,9 +2229,7 @@ test("Invitees can not set child extensions", () => {
     group.core
       .testWithDifferentAccount(
         readerInvite,
-        Crypto.newRandomSessionID(
-          readerInvite.currentAgentID()._unsafeUnwrap(),
-        ),
+        Crypto.newRandomSessionID(readerInvite.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -2422,7 +2414,7 @@ test("Writers, readers and invites can't reveal parent read keys to child groups
     group.core
       .testWithDifferentAccount(
         adminInvite,
-        Crypto.newRandomSessionID(adminInvite.currentAgentID()._unsafeUnwrap()),
+        Crypto.newRandomSessionID(adminInvite.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -2440,9 +2432,7 @@ test("Writers, readers and invites can't reveal parent read keys to child groups
     group.core
       .testWithDifferentAccount(
         writerInvite,
-        Crypto.newRandomSessionID(
-          writerInvite.currentAgentID()._unsafeUnwrap(),
-        ),
+        Crypto.newRandomSessionID(writerInvite.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -2460,9 +2450,7 @@ test("Writers, readers and invites can't reveal parent read keys to child groups
     group.core
       .testWithDifferentAccount(
         readerInvite,
-        Crypto.newRandomSessionID(
-          readerInvite.currentAgentID()._unsafeUnwrap(),
-        ),
+        Crypto.newRandomSessionID(readerInvite.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -2941,7 +2929,7 @@ test("Can revoke read permission from 'everyone'", async () => {
     childObject.core
       .testWithDifferentAccount(
         newAccount,
-        Crypto.newRandomSessionID(newAccount.currentAgentID()._unsafeUnwrap()),
+        Crypto.newRandomSessionID(newAccount.currentAgentID()),
       )
       .getCurrentContent(),
   );
@@ -2963,7 +2951,7 @@ test("Can revoke read permission from 'everyone'", async () => {
     childObject.core
       .testWithDifferentAccount(
         newAccount2,
-        Crypto.newRandomSessionID(newAccount2.currentAgentID()._unsafeUnwrap()),
+        Crypto.newRandomSessionID(newAccount2.currentAgentID()),
       )
       .getCurrentContent(),
   );

packages/cojson/tsconfig.json

@@ -12,5 +12,5 @@
     "esModuleInterop": true
   },
   "include": ["./src/**/*.ts"],
-  "exclude": ["./node_modules", "./src/tests"]
+  "exclude": ["./node_modules"]
 }

packages/create-jazz-app/CHANGELOG.md

@@ -1,5 +1,17 @@
 # create-jazz-app
 
+## 0.1.13
+
+### Patch Changes
+
+- b063ccc: Added Cursor docs to create-jazz-app
+
+## 0.1.12
+
+### Patch Changes
+
+- e2e0af3: Handle workspace devDependencies of cloned apps when using create-jazz-app
+
 ## 0.1.11
 
 ### Patch Changes

packages/create-jazz-app/package.json

@@ -5,7 +5,7 @@
   "types": "src/index.ts",
   "type": "module",
   "license": "MIT",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "bin": {
     "create-jazz-app": "./dist/index.js"
   },

packages/create-jazz-app/src/index.ts

@@ -136,19 +136,30 @@ async function scaffoldProject({
     const packageJsonPath = `${projectName}/package.json`;
     const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
 
-    // Replace workspace: dependencies with latest
-    if (packageJson.dependencies) {
-      const latestVersions = await getLatestPackageVersions(
-        packageJson.dependencies,
-      );
+    // Helper function to update workspace dependencies
+    async function updateWorkspaceDependencies(
+      dependencyType: "dependencies" | "devDependencies",
+    ) {
+      if (packageJson[dependencyType]) {
+        const latestVersions = await getLatestPackageVersions(
+          packageJson[dependencyType],
+        );
 
-      Object.entries(packageJson.dependencies).forEach(([pkg, version]) => {
-        if (typeof version === "string" && version.includes("workspace:")) {
-          packageJson.dependencies[pkg] = latestVersions[pkg];
-        }
-      });
+        Object.entries(packageJson[dependencyType]).forEach(
+          ([pkg, version]) => {
+            if (typeof version === "string" && version.includes("workspace:")) {
+              packageJson[dependencyType][pkg] = latestVersions[pkg];
+            }
+          },
+        );
+      }
     }
 
+    await Promise.all([
+      updateWorkspaceDependencies("dependencies"),
+      updateWorkspaceDependencies("devDependencies"),
+    ]);
+
     packageJson.name = projectName;
     fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
     depsSpinner.succeed(chalk.green("Dependencies updated"));
@@ -238,6 +249,56 @@ module.exports = withNativeWind(config, { input: "./src/global.css" });
     }
   }
 
+  // Step 5: Clone cursor-docs
+  const docsSpinner = ora({
+    text: chalk.blue(`Adding .cursor directory...`),
+    spinner: "dots",
+  }).start();
+
+  try {
+    // Create a temporary directory for cursor-docs
+    const tempDocsDir = `${projectName}-cursor-docs-temp`;
+    const emitter = degit("garden-co/jazz/packages/cursor-docs", {
+      cache: false,
+      force: true,
+      verbose: true,
+    });
+
+    // Clone cursor-docs to temp directory
+    await emitter.clone(tempDocsDir);
+
+    // Copy only the .cursor directory to project root
+    const cursorDirSource = `${tempDocsDir}/.cursor`;
+    const cursorDirTarget = `${projectName}/.cursor`;
+
+    if (fs.existsSync(cursorDirSource)) {
+      fs.cpSync(cursorDirSource, cursorDirTarget, { recursive: true });
+      docsSpinner.succeed(chalk.green(".cursor directory added successfully"));
+    } else {
+      docsSpinner.fail(chalk.red(".cursor directory not found in cursor-docs"));
+    }
+
+    // Clean up temp directory
+    fs.rmSync(tempDocsDir, { recursive: true, force: true });
+  } catch (error) {
+    docsSpinner.fail(chalk.red("Failed to add .cursor directory"));
+    throw error;
+  }
+
+  // Step 6: Git init
+  const gitSpinner = ora({
+    text: chalk.blue("Initializing git repository..."),
+    spinner: "dots",
+  }).start();
+
+  try {
+    execSync(`cd "${projectName}" && git init`, { stdio: "pipe" });
+    gitSpinner.succeed(chalk.green("Git repository initialized"));
+  } catch (error) {
+    gitSpinner.fail(chalk.red("Failed to initialize git repository"));
+    throw error;
+  }
+
   // Final success message
   console.log("\n" + chalk.green.bold("✨ Project setup completed! ✨\n"));
   console.log(chalk.cyan("To get started:"));

packages/cursor-docs/.cursor/docs/1_jazz_docs.md

@@ -0,0 +1,946 @@
+---
+
+## **CoMap Overview**
+**CoMap** is a collaborative object mapping system from `jazz-tools`, mapping string keys to values.
+
+### **1. Basic Definition**
+```typescript
+import { CoMap, co } from "jazz-tools";
+class Person extends CoMap {
+  name = co.string;
+  age = co.number;
+  isActive = co.boolean;
+}
+```
+
+### **2. Field Types**
+- **Basic:** `co.string`, `co.number`, `co.boolean`
+- **Optional:** `co.optional.string`, `co.optional.number`
+- **Literals (Enums):** `co.literal("draft", "published", "archived")`
+- **Dates:** `co.Date`
+- **Custom Encoded:**
+```typescript
+customField = co.encoded({
+  encode: (v: string) => v.toUpperCase(),
+  decode: (v: unknown) => String(v).toLowerCase()
+});
+```
+
+### **3. References to Other CoMaps**
+```typescript
+class Comment extends CoMap {
+  text = co.string;
+  createdAt = co.Date;
+}
+class Post extends CoMap {
+  title = co.string;
+  content = co.string;
+  mainComment = co.ref(Comment);
+  pinnedComment = co.optional.ref(Comment);
+}
+```
+
+### **4. Lists with CoList**
+```typescript
+import { CoList, CoMap, co } from "jazz-tools";
+class Task extends CoMap {
+  title = co.string;
+  completed = co.boolean;
+}
+class TaskList extends CoList.Of(co.ref(Task)) {}
+class Project extends CoMap {
+  name = co.string;
+  tasks = co.ref(TaskList);
+}
+```
+
+### **5. Validation & Custom Methods**
+```typescript
+class DraftPost extends CoMap {
+  title = co.optional.string;
+  content = co.optional.string;
+  validate() {
+    const errors: string[] = [];
+    if (!this.title) errors.push("Title is required");
+    if (!this.content) errors.push("Content is required");
+    return { errors };
+  }
+  get summary() { return this.content?.slice(0, 100) + "..."; }
+}
+```
+
+### **Real-World Examples**
+- **Chat Schema**
+```typescript
+class Message extends CoMap { text = co.string; image = co.optional.ref(ImageDefinition); }
+class Chat extends CoList.Of(co.ref(Message)) {}
+```
+- **Organization Schema**
+```typescript
+class Project extends CoMap { name = co.string; }
+class ListOfProjects extends CoList.Of(co.ref(Project)) {}
+class Organization extends CoMap {
+  name = co.string;
+  projects = co.ref(ListOfProjects);
+}
+```
+- **Issue Tracking**
+```typescript
+class Issue extends CoMap {
+  title = co.string;
+  description = co.string;
+  estimate = co.number;
+  status? = co.literal("backlog", "in progress", "done");
+}
+class ListOfIssues extends CoList.Of(co.ref(Issue)) {}
+class Project extends CoMap {
+  name = co.string;
+  issues = co.ref(ListOfIssues);
+}
+```
+
+### **Testing Example**
+```typescript
+class TestMap extends CoMap {
+  color = co.string;
+  _height = co.number;
+  birthday = co.Date;
+  name? = co.string;
+  nullable = co.optional.encoded<string | undefined>({
+    encode: (v: string | undefined) => v || null,
+    decode: (v: unknown) => (v as string) || undefined,
+  });
+  optionalDate = co.optional.encoded(Encoders.Date);
+  get roughColor() { return this.color + "ish"; }
+}
+```
+
+### **Key Takeaways**
+- Extend **CoMap** for schemas.
+- Use `co.ref()` for references, `co.optional` for optional fields.
+- Use `CoList.Of()` for collections.
+- Fields auto-sync across clients.
+- Add computed properties & validation methods.
+
+---
+
+## **CoList Overview**
+**CoList** is a collaborative array in `jazz-tools`.
+
+### **1. Basic Definition**
+```typescript
+import { CoList, co } from "jazz-tools";
+class ColorList extends CoList.Of(co.string) {}
+class NumberList extends CoList.Of(co.number) {}
+class BooleanList extends CoList.Of(co.boolean) {}
+```
+
+### **2. Lists of CoMaps**
+```typescript
+import { CoList, CoMap, co } from "jazz-tools";
+class Task extends CoMap { title = co.string; completed = co.boolean; }
+class ListOfTasks extends CoList.Of(co.ref(Task)) {}
+```
+
+### **3. CoList Operations**
+```typescript
+const taskList = ListOfTasks.create([], { owner: me });
+taskList.push(Task.create({ title: "New task", completed: false }, { owner: me }));
+const firstTask = taskList[0];
+taskList.filter(task => !task.completed);
+taskList.splice(1, 1);
+```
+
+### **4. Nested Lists**
+```typescript
+class Comment extends CoMap { text = co.string; createdAt = co.Date; }
+class ListOfComments extends CoList.Of(co.ref(Comment)) {}
+class Post extends CoMap {
+  title = co.string;
+  content = co.string;
+  comments = co.ref(ListOfComments);
+}
+class ListOfPosts extends CoList.Of(co.ref(Post)) {}
+```
+
+### **Real-World Examples**
+- **Chat Schema**
+```typescript
+class Message extends CoMap { text = co.string; image = co.optional.ref(ImageDefinition); }
+class Chat extends CoList.Of(co.ref(Message)) {}
+```
+- **Todo App Schema**
+```typescript
+class Task extends CoMap { done = co.boolean; text = co.string; }
+class ListOfTasks extends CoList.Of(co.ref(Task)) {}
+```
+- **Organization Schema**
+```typescript
+class Project extends CoMap { name = co.string; }
+class ListOfProjects extends CoList.Of(co.ref(Project)) {}
+class Organization extends CoMap {
+  name = co.string;
+  projects = co.ref(ListOfProjects);
+}
+```
+
+### **5. Advanced Features**
+```typescript
+class TaskList extends CoList.Of(co.ref(Task)) {
+  getCompletedTasks() { return this.filter(task => task.completed); }
+  getPendingTasks() { return this.filter(task => !task.completed); }
+}
+```
+
+### **Key Takeaways**
+- `CoList.Of()` for list definitions.
+- `co.ref()` for CoMap references.
+- Acts like arrays with real-time sync.
+- Supports custom methods & nested lists.
+
+---
+
+## **CoFeed Overview**
+**CoFeed** is an append-only event stream, ideal for time-ordered data.
+
+### **1. Basic Definition**
+```typescript
+import { CoFeed, co } from "jazz-tools";
+class ActivityFeed extends CoFeed.Of(co.string) {}
+class MetricsFeed extends CoFeed.Of(co.number) {}
+```
+
+### **2. Feeds with Complex Types**
+```typescript
+interface LogEvent {
+  timestamp: number;
+  level: "info" | "warn" | "error";
+  message: string;
+}
+class LogFeed extends CoFeed.Of(co.json<LogEvent>()) {}
+```
+
+### **3. Pet Reactions Example**
+```typescript
+export const ReactionTypes = ["aww","love","haha","wow","tiny","chonkers"] as const;
+export class PetReactions extends CoFeed.Of(co.json<ReactionType>()) {}
+```
+
+### **4. Working with CoFeeds**
+```typescript
+const reactions = PetReactions.create({ owner: me });
+reactions.post("love");
+reactions.subscribe(feedId, me, {}, (feed) => console.log(feed.latest()));
+```
+
+### **5. Common Use Cases**
+- **Activity Streams**
+```typescript
+class ActivityStream extends CoFeed.Of(co.json<{ type:"comment"|"like"|"share";userId:string;timestamp:number;}>) {}
+```
+- **Chat Messages**
+```typescript
+class ChatFeed extends CoFeed.Of(co.json<{ type:"message"|"join"|"leave";userId:string; content?:string;timestamp:number;}>) {}
+```
+- **Audit Logs**
+```typescript
+class AuditLog extends CoFeed.Of(co.json<{ action:string; user:string; details:Record<string,unknown>;timestamp:number;}>) {}
+```
+
+### **6. Differences: CoFeed vs. CoList**
+| Feature  | CoFeed (append-only) | CoList (mutable) |
+|----------|----------------------|------------------|
+| Order    | Time-ordered        | Arbitrary        |
+| Use Case | Logs, streams       | Collections      |
+
+### **Key Takeaways**
+- **CoFeed**: event logs, activity streams, append-only.
+- **CoList**: modifiable lists.
+- Real-time updates, easy to subscribe.
+
+---
+
+## **SchemaUnion Overview**
+**SchemaUnion** handles runtime-discriminated union types of `CoMap` instances.
+
+### **1. Basic Definition**
+```typescript
+import { SchemaUnion, CoMap, co } from "jazz-tools";
+class BaseShape extends CoMap { type = co.string; }
+class Circle extends BaseShape { type = co.literal("circle"); radius = co.number; }
+class Rectangle extends BaseShape { type = co.literal("rectangle"); width = co.number; height = co.number; }
+const Shape = SchemaUnion.Of<BaseShape>((raw) => {
+  switch (raw.get("type")) {
+    case "circle": return Circle;
+    case "rectangle": return Rectangle;
+    default: throw new Error("Unknown shape");
+  }
+});
+```
+
+### **2. Nested Discriminators**
+```typescript
+class BaseButton extends CoMap { type = co.literal("button"); variant = co.string; }
+class PrimaryButton extends BaseButton { variant = co.literal("primary"); label = co.string; size = co.literal("small","medium","large"); }
+class SecondaryButton extends BaseButton { variant = co.literal("secondary"); label = co.string; outline = co.boolean; }
+const Button = SchemaUnion.Of<BaseButton>((raw) => {
+  switch (raw.get("variant")) {
+    case "primary": return PrimaryButton;
+    case "secondary": return SecondaryButton;
+    default: throw new Error("Unknown variant");
+  }
+});
+```
+
+### **3. Using SchemaUnion with CoLists**
+```typescript
+class BaseWidget extends CoMap { type = co.string; }
+class ButtonWidget extends BaseWidget { type = co.literal("button"); label = co.string; }
+class SliderWidget extends BaseWidget { type = co.literal("slider"); min = co.number; max = co.number; }
+const Widget = SchemaUnion.Of<BaseWidget>((raw) => {
+  switch (raw.get("type")) {
+    case "button": return ButtonWidget;
+    case "slider": return SliderWidget;
+    default: throw new Error("Unknown widget");
+  }
+});
+class WidgetList extends CoList.Of(co.ref(Widget)) {}
+```
+
+### **4. Working with SchemaUnion Instances**
+```typescript
+const button = ButtonWidget.create({ type:"button", label:"Click me" }, { owner: me });
+const widget = await loadCoValue(Widget, widgetId, me, {});
+if (widget instanceof ButtonWidget) console.log(widget.label);
+if (widget instanceof SliderWidget) console.log(widget.min, widget.max);
+```
+
+### **5. Validation Example**
+```typescript
+class BaseFormField extends CoMap {
+  type = co.string;
+  label = co.string;
+  required = co.boolean;
+}
+class TextField extends BaseFormField {
+  type = co.literal("text");
+  minLength = co.optional.number;
+  maxLength = co.optional.number;
+  validate(value: string){/* ... */}
+}
+class NumberField extends BaseFormField {
+  type = co.literal("number");
+  min = co.optional.number;
+  max = co.optional.number;
+  validate(value: number){/* ... */}
+}
+const FormField = SchemaUnion.Of<BaseFormField>((raw) => {
+  switch (raw.get("type")) {
+    case "text": return TextField;
+    case "number": return NumberField;
+    default: throw new Error("Unknown type");
+  }
+});
+```
+
+### **Key Takeaways**
+- **SchemaUnion** = polymorphic CoMaps.
+- Use `co.literal()` for discriminators.
+- `instanceof` for type-narrowing.
+- Great for complex forms & dynamic components.
+
+---
+
+## **Groups, Accounts, Owners, Roles & Permissions in Jazz**
+
+### **1. Ownership & Groups**
+Every `CoValue` has an owner (an `Account` or `Group`):
+```typescript
+import { Account, Group, CoMap, co } from "jazz-tools";
+const privateDoc = Document.create({ title:"Private" }, { owner: me });
+const group = Group.create({ owner: me });
+const sharedDoc = Document.create({ title:"Shared" }, { owner: group });
+```
+
+### **2. Roles & Permissions**
+Built-in roles: `"admin"`, `"writer"`, `"reader"`, `"readerInvite"`, `"writerInvite"`.
+```typescript
+group.addMember(bob, "writer");
+group.addMember(alice, "reader");
+group.addMember("everyone","reader");
+```
+
+### **3. Organizations & Memberships**
+```typescript
+import { Account, CoMap, CoList, Group, co } from "jazz-tools";
+class Project extends CoMap { name = co.string; description = co.string; }
+class Organization extends CoMap {
+  name = co.string;
+  projects = co.ref(CoList.Of(co.ref(Project)));
+  static create(name: string, owner: Account) {
+    const group = Group.create({ owner });
+    return super.create({ name, projects: CoList.Of(co.ref(Project)).create([], { owner: group }) }, { owner: group });
+  }
+  addMember(account: Account, role: "admin"|"writer"|"reader") {
+    this._owner.castAs(Group).addMember(account, role);
+  }
+}
+```
+
+### **4. Account Root & Migration Pattern**
+```typescript
+class TodoAccountRoot extends CoMap {
+  projects = co.ref(ListOfProjects);
+}
+export class UserProfile extends Profile { someProperty = co.string; }
+class TodoAccount extends Account {
+  root = co.ref(TodoAccountRoot);
+  profile = co.ref(UserProfile);
+  migrate() {
+    if (!this._refs.root) {
+      this.root = TodoAccountRoot.create({ projects: ListOfProjects.create([], { owner: this }) }, { owner: this });
+    }
+  }
+}
+```
+
+### **5. Public Sharing Example**
+```typescript
+class SharedFile extends CoMap {
+  name = co.string;
+  file = co.ref(FileStream);
+  createdAt = co.Date;
+  size = co.number;
+}
+class FileShareAccountRoot extends CoMap {
+  type = co.string;
+  sharedFiles = co.ref(ListOfSharedFiles);
+  publicGroup = co.ref(Group);
+}
+export class UserProfile extends Profile { someProperty = co.string; }
+class FileShareAccount extends Account {
+  root = co.ref(FileShareAccountRoot);
+  profile = co.ref(UserProfile);
+  async migrate() {
+    await this._refs.root?.load();
+    if (!this.root || this.root.type !== "file-share-account") {
+      const publicGroup = Group.create({ owner: this });
+      publicGroup.addMember("everyone","reader");
+      this.root = FileShareAccountRoot.create({
+        type:"file-share-account",
+        sharedFiles: ListOfSharedFiles.create([], { owner: publicGroup }),
+        publicGroup
+      }, { owner: this });
+    }
+  }
+}
+```
+
+### **6. Group Extensions**
+```typescript
+const parentGroup = Group.create({ owner: me });
+parentGroup.addMember(bob, "reader");
+const childGroup = Group.create({ owner: me });
+childGroup.extend(parentGroup);
+const doc = Document.create({ title:"Inherited Access" }, { owner: childGroup });
+```
+
+### **7. Checking Permissions**
+```typescript
+const group = document._owner.castAs(Group);
+const myRole = group.myRole();
+const hasWriteAccess = myRole === "admin" || myRole === "writer";
+```
+
+### **8. Invitation Pattern**
+```typescript
+class TeamInvite extends CoMap {
+  email = co.string;
+  role = co.literal("admin","writer","reader");
+  accepted = co.boolean;
+}
+class Team extends CoMap {
+  invites = co.ref(CoList.Of(co.ref(TeamInvite)));
+  async inviteMember(email: string, role: "admin"|"writer"|"reader") {
+    const group = this._owner.castAs(Group);
+    const invite = TeamInvite.create({ email, role, accepted:false }, { owner: group });
+    this.invites.push(invite);
+    group.addMember(email, (role+"Invite") as const);
+  }
+  acceptInvite(account: Account) {
+    const group = this._owner.castAs(Group);
+    const invite = this.invites.find(i => i.email === account.email);
+    if (invite) {
+      invite.accepted = true;
+      group.addMember(account, invite.role);
+    }
+  }
+}
+```
+
+### **Key Takeaways**
+- Every `CoValue` has an owner (Account or Group).
+- Groups enable sharing/role-based access (`"admin"`, `"writer"`, `"reader"`, etc.).
+- Groups can inherit permissions.
+- Use account roots for private per-user data.
+- Public sharing via `"everyone"` role.
+- Invites allow controlled membership.
+
+---
+
+## **Inbox Pattern in Jazz**
+Enables message exchange between accounts using `CoMap`, `CoList`, `Group`.
+
+### **1. Basic Inbox Setup**
+```typescript
+import { CoMap, co, Group } from "jazz-tools";
+class Message extends CoMap {
+  text = co.string;
+  createdAt = co.Date;
+  read = co.boolean;
+}
+class ChatInbox extends CoMap {
+  messages = co.ref(CoList.Of(co.ref(Message)));
+  lastReadAt = co.Date;
+}
+```
+
+### **2. Sending Messages**
+```typescript
+async function sendMessage(sender: Account, receiverId: ID<Account>, text: string) {
+  const message = Message.create(
+    { text, createdAt:new Date(), read:false },
+    { owner: Group.create({ owner: sender }) }
+  );
+  const inboxSender = await InboxSender.load(receiverId, sender);
+  inboxSender.sendMessage(message);
+}
+```
+
+### **3. Receiving Messages**
+```typescript
+async function setupInbox(receiver: Account) {
+  const inbox = await Inbox.load(receiver);
+  return inbox.subscribe(Message,(message,senderId)=>console.log("New:",message.text));
+}
+```
+
+### **4. Chat Application Example**
+```typescript
+class ChatMessage extends CoMap { text = co.string; createdAt=co.Date; read=co.boolean; }
+class ChatThread extends CoMap {
+  participants = co.json<string[]>();
+  messages = co.ref(CoList.Of(co.ref(ChatMessage)));
+  lastReadAt = co.optional.Date;
+}
+class ChatRoot extends CoMap {
+  threads = co.ref(CoList.Of(co.ref(ChatThread)));
+  inbox = co.ref(Inbox);
+}
+export class UserProfile extends Profile { someProperty=co.string; }
+class ChatAccount extends Account {
+  root = co.ref(ChatRoot);
+  profile = co.ref(UserProfile);
+  async migrate() {
+    if(!this._refs.root) {
+      const group = Group.create({ owner:this });
+      this.root = ChatRoot.create({
+        threads: CoList.Of(co.ref(ChatThread)).create([], { owner: group }),
+        inbox: await Inbox.create(this)
+      },{ owner:this });
+    }
+  }
+  async sendMessage(to: ID<Account>, text:string) {
+    const message = ChatMessage.create({ text, createdAt:new Date(), read:false },
+      { owner: Group.create({ owner:this }) });
+    const inboxSender=await InboxSender.load(to,this);
+    inboxSender.sendMessage(message);
+  }
+  async setupInboxListener() {
+    const inbox = await Inbox.load(this);
+    return inbox.subscribe(ChatMessage, async (message, senderId) => {
+      const thread = await this.findOrCreateThread(senderId);
+      thread.messages.push(message);
+    });
+  }
+}
+```
+
+### **5. Testing the Inbox Pattern**
+```typescript
+describe("Inbox", () => {
+  it("should allow message exchange", async () => {
+    const { clientAccount:sender, serverAccount:receiver } = await setupTwoNodes();
+    const receiverInbox = await Inbox.load(receiver);
+    const message = Message.create({ text:"Hello" },{ owner:Group.create({ owner:sender }) });
+    const inboxSender = await InboxSender.load(receiver.id, sender);
+    inboxSender.sendMessage(message);
+    const receivedMessages: Message[] = [];
+    let senderAccountID: unknown;
+    const unsubscribe = receiverInbox.subscribe(Message, (msg, id) => {
+      senderAccountID=id; receivedMessages.push(msg);
+    });
+    await waitFor(() => receivedMessages.length===1);
+    expect(receivedMessages[0]?.text).toBe("Hello");
+    expect(senderAccountID).toBe(sender.id);
+    unsubscribe();
+  });
+});
+```
+
+### **6. Message Status Tracking**
+```typescript
+class MessageStatus extends CoMap {
+  messageId = co.string;
+  delivered = co.boolean;
+  read = co.boolean;
+  readAt = co.optional.Date;
+}
+class EnhancedMessage extends CoMap {
+  text = co.string;
+  createdAt = co.Date;
+  status = co.ref(MessageStatus);
+}
+async function sendMessageWithStatus(sender: Account, receiverId: ID<Account>, text:string) {
+  const group = Group.create({ owner:sender });
+  const status = MessageStatus.create({ messageId:crypto.randomUUID(), delivered:false, read:false }, { owner:group });
+  const message = EnhancedMessage.create({ text, createdAt:new Date(), status }, { owner:group });
+  const inboxSender = await InboxSender.load(receiverId,sender);
+  inboxSender.sendMessage(message);
+  return message;
+}
+```
+
+### **Key Takeaways**
+- Messages owned by a `Group` from the sender.
+- Use `InboxSender.load()` to send, `Inbox.load()` to receive.
+- Subscribe for real-time updates.
+- Append status tracking as needed.
+
+---
+
+## **Invite Pattern in Jazz**
+Sharing access to `CoValues` with other users via invites.
+
+### **1. Creating & Handling Invites**
+```typescript
+import { CoMap, Group, co, createInviteLink } from "jazz-tools";
+class Project extends CoMap { name = co.string; members = co.ref(CoList.Of(co.ref(Member))); }
+const group = Group.create({ owner: me });
+const project = Project.create({ name:"New Project", members:CoList.Of(co.ref(Member)).create([],{owner:group}) }, { owner:group });
+const readerInvite = createInviteLink(project,"reader");
+const writerInvite = createInviteLink(project,"writer");
+const adminInvite = createInviteLink(project,"admin");
+```
+
+### **2. Accepting Invites in UI**
+```typescript
+import { useAcceptInvite } from "jazz-react";
+useAcceptInvite({
+  invitedObjectSchema:Project,
+  onAccept:(projectId)=>navigate(`/projects/${projectId}`)
+});
+```
+
+### **3. Organization Example**
+```typescript
+class Organization extends CoMap {
+  name = co.string;
+  projects = co.ref(ListOfProjects);
+  createInvite(role:"reader"|"writer"|"admin"){ return createInviteLink(this,role); }
+}
+useAcceptInvite({
+  invitedObjectSchema:Organization,
+  onAccept:async(orgId)=>{/* ... */}
+});
+```
+
+### **4. Value Hints in Invites**
+```typescript
+class Team extends CoMap {
+  name = co.string;
+  generateInvite(role:"reader"|"writer"|"admin"){ return createInviteLink(this, role, window.location.origin, "team"); }
+}
+useAcceptInvite({
+  invitedObjectSchema:Team,
+  forValueHint:"team",
+  onAccept:(teamId)=>navigate(`/teams/${teamId}`)
+});
+```
+
+### **5. Testing Invites**
+```typescript
+describe("Invite Links", () => {
+  test("generate and parse invites", async () => {
+    const inviteLink = createInviteLink(group, "writer","https://example.com","myGroup");
+    const parsed = parseInviteLink(inviteLink);
+    expect(parsed?.valueID).toBe(group.id);
+    expect(parsed?.valueHint).toBe("myGroup");
+  });
+  test("accept invite", async () => {
+    const newAccount = await createJazzTestAccount();
+    const inviteLink = createInviteLink(group, "writer");
+    const result = await consumeInviteLink({ inviteURL: inviteLink, as:newAccount, invitedObjectSchema:Group });
+    expect(result?.valueID).toBe(group.id);
+  });
+});
+```
+
+### **6. File Sharing with Invites**
+```typescript
+class SharedFile extends CoMap {
+  name = co.string;
+  sharedWith = co.ref(CoList.Of(co.ref(SharedWith)));
+}
+class SharedWith extends CoMap {
+  email = co.string;
+  role = co.literal("reader","writer");
+  acceptedAt = co.optional.Date;
+}
+class FileShareAccount extends Account {
+  async shareFile(file:SharedFile, email:string, role:"reader"|"writer") {
+    const inviteLink = createInviteLink(file,role);
+    file.sharedWith.push(SharedWith.create({ email, role, acceptedAt:null },{ owner:file._owner }));
+    await sendInviteEmail(email, inviteLink);
+  }
+}
+useAcceptInvite({
+  invitedObjectSchema:SharedFile,
+  onAccept:async(fileId)=>{
+    const file = await SharedFile.load(fileId,{});
+    const shareRecord = file.sharedWith.find(s=>s.email===currentUser.email);
+    if(shareRecord) shareRecord.acceptedAt=new Date();
+    navigate(`/files/${fileId}`);
+  }
+});
+```
+
+### **Key Takeaways**
+- Use Groups for shared ownership.
+- `createInviteLink()` generates invites.
+- `useAcceptInvite()` handles acceptance.
+- Value hints (`forValueHint`) differentiate invite types.
+
+---
+
+## **CoValue Types & Patterns in Jazz**
+
+### **1. CoMap**
+- Use for structured data with named fields.
+- Example:
+```typescript
+class UserProfile extends CoMap {
+  name = co.string;
+  email = co.string;
+  avatar = co.ref(FileStream);
+  preferences = co.json<{ theme:string; notifications:boolean }>();
+}
+class TagColors extends CoMap.Record(co.string) {}
+```
+
+### **2. CoList**
+- Use for ordered, real-time collaborative arrays.
+```typescript
+class TodoList extends CoList.Of(co.ref(TodoItem)) {}
+class StringList extends CoList.Of(co.string) {}
+```
+
+### **3. CoFeed**
+- Use for append-only event/log data.
+```typescript
+class UserActivity extends CoFeed.Of(co.json<{ type:string; timestamp:number; text?:string }>) {}
+```
+
+### **4. SchemaUnion**
+- Use for polymorphic objects with a runtime discriminator.
+```typescript
+class BaseWidget extends CoMap { type=co.string; }
+class ButtonWidget extends BaseWidget { type=co.literal("button"); label=co.string; }
+const Widget=SchemaUnion.Of<BaseWidget>(raw=>raw.get("type")==="button"?ButtonWidget:null);
+```
+
+### **5. Groups & Permissions**
+- Owner can be an Account or Group.
+- Roles: `"admin"|"writer"|"reader"|"readerInvite"|"writerInvite"`.
+```typescript
+const group=Group.create({owner:me});
+group.addMember("everyone","reader");
+```
+
+### **6. Accounts**
+- Per-user data storage with migrations.
+```typescript
+class JazzAccount extends Account {
+  root=co.ref(JazzAccountRoot);
+  profile=co.ref(UserProfile);
+  async migrate(){/*...*/}
+}
+```
+
+### **7. Migrations**
+- Update/initialize user data on account creation/login.
+
+### **8. Invites**
+- Role-based sharing through invite links.
+
+### **Common Patterns**
+- **Account Root Pattern**: store user’s top-level data.
+- **Shared Document Pattern**: CoMap for doc, CoList for collaborators, CoFeed for history.
+- **Draft Pattern**: CoMap with partial fields, validation.
+- **Public Sharing**: set `Group.addMember("everyone","reader")`.
+
+---
+
+## **Examples**
+
+1. **User Profile Storage (CoMap)**
+**JSON**:
+```json
+{
+  "name":"John Doe","email":"john@example.com",
+  "avatar":{"url":"...","size":"..."},
+  "preferences":{"theme":"dark","notifications":true}
+}
+```
+**Jazz**:
+```typescript
+class UserProfile extends CoMap {
+  name = co.string;
+  email = co.string;
+  avatar = co.ref(FileStream);
+  preferences = co.json<{theme:string;notifications:boolean}>();
+}
+```
+
+2. **To-Do List (CoList)**
+**JSON**:
+```json
+{"tasks":[{"id":1,"title":"Buy groceries","completed":false},{"id":2,"title":"Call mom","completed":true}]}
+```
+**Jazz**:
+```typescript
+class TodoItem extends CoMap { title=co.string; completed=co.boolean; }
+class TodoList extends CoList.Of(co.ref(TodoItem)) {}
+```
+
+3. **Activity Feed (CoFeed)**
+**JSON**:
+```json
+{"activities":[{"type":"login","timestamp":1700000000},{"type":"logout","timestamp":1700000500},{"type":"comment","timestamp":1700001000,"text":"Great post!"}]}
+```
+**Jazz**:
+```typescript
+class UserActivity extends CoFeed.Of(co.json<{type:string;timestamp:number;text?:string}>()) {}
+```
+
+4. **Polymorphic Widgets (SchemaUnion)**
+**JSON**:
+```json
+{"widgets":[{"type":"button","label":"Click Me"},{"type":"slider","min":0,"max":100}]}
+```
+**Jazz**:
+```typescript
+class BaseWidget extends CoMap { type=co.string; }
+class ButtonWidget extends BaseWidget { type=co.literal("button"); label=co.string; }
+class SliderWidget extends BaseWidget { type=co.literal("slider"); min=co.number; max=co.number; }
+const Widget=SchemaUnion.Of<BaseWidget>((raw)=>{...});
+```
+
+5. **Access Control via Groups**
+**JSON**:
+```json
+{"group":{"owner":"user123","members":[{"id":"user456","role":"admin"},{"id":"user789","role":"writer"}]}}
+```
+**Jazz**:
+```typescript
+const group=Group.create({owner:user123});
+group.addMember(user456,"admin");
+group.addMember(user789,"writer");
+```
+
+6. **User Account with Root Data (Accounts)**
+**JSON**:
+```json
+{"user":{"profile":{"name":"Jane Doe"},"documents":[{"title":"My Notes","content":"This is a note."}],"activities":[{"type":"login"}]}}
+```
+**Jazz**:
+```typescript
+class AppAccountRoot extends CoMap {
+  profile=co.ref(UserProfile);
+  documents=co.ref(CoList.Of(co.ref(Document)));
+  activities=co.ref(UserActivity);
+}
+class AppAccount extends Account {
+  root=co.ref(AppAccountRoot);
+  profile=co.ref(UserProfile);
+}
+```
+
+7. **Document Collaboration**
+**JSON**:
+```json
+{
+  "document":{
+    "title":"Project Plan","content":"Detailed...","collaborators":[{"id":"user1","role":"editor"},{"id":"user2","role":"viewer"}],
+    "history":[{"user":"user1","timestamp":1700000000,"change":"Edited content"}]
+  }
+}
+```
+**Jazz**:
+```typescript
+class Document extends CoMap {
+  title=co.string;content=co.string;
+  collaborators=co.ref(CoList.Of(co.ref(UserProfile)));
+  history=co.ref(CoFeed.Of(co.json<{user:string;timestamp:number;change:string}>()));
+}
+```
+
+8. **Draft System**
+**JSON**:
+```json
+{"draft":{"name":"New Project","tasks":[],"valid":false,"errors":["Project name required"]}}
+```
+**Jazz**:
+```typescript
+class DraftProject extends CoMap {
+  name=co.optional.string;
+  tasks=co.ref(CoList.Of(co.ref(TodoItem)));
+  validate(){/*...*/}
+}
+```
+
+9. **Public File Sharing**
+**JSON**:
+```json
+{"file":{"name":"Presentation.pdf","size":2048,"uploadedAt":1700000000,"sharedWith":["everyone"]}}
+```
+**Jazz**:
+```typescript
+class SharedFile extends CoMap {
+  name=co.string;
+  file=co.ref(FileStream);
+  uploadedAt=co.Date;
+}
+const publicGroup=Group.create({owner:me});
+publicGroup.addMember("everyone","reader");
+```
+
+10. **Invite System**
+**JSON**:
+```json
+{"invites":[{"email":"user@example.com","role":"writer","status":"pending"}]}
+```
+**Jazz**:
+```typescript
+class Invite extends CoMap {
+  email=co.string;
+  role=co.literal("reader","writer","admin");
+  status=co.literal("pending","accepted");
+}
+const inviteLink=createInviteLink(project,"writer");
+useAcceptInvite({ invitedObjectSchema:Project, onAccept:(id)=>navigate(`/projects/${id}`) });
+```
+
+---
+
+Continue: 2_jazz_schema_template.md

packages/cursor-docs/.cursor/docs/2_jazz_schema_template.md

@@ -0,0 +1,216 @@
+---
+
+import { Account, CoList, CoMap, Group, Profile, co } from "jazz-tools";
+
+/**
+ * Represents a main data item in the app’s domain.
+ *
+ * Properties:
+ *  - name: Required field identifying the item.
+ *  - metadata_field: Optional metadata (string).
+ *  - container: Reference to a parent Container.
+ *  - deleted: Soft delete flag for archiving/removing without permanent deletion.
+ */
+export class MainItem extends CoMap {
+  /** A required, identifying name. */
+  name = co.string;
+
+  /** An optional string field for metadata. */
+  metadata_field = co.optional.string;
+
+  /** Reference to the parent container. */
+  container = co.ref(Container);
+
+  /** Soft-delete flag: if true, treat this item as removed. */
+  deleted = co.boolean;
+}
+
+/**
+ * A list/array of MainItem references.
+ * Provides real-time collaboration features (insertion, removal, ordering).
+ */
+export class MainItemList extends CoList.Of(co.ref(MainItem)) {}
+
+/**
+ * A container/organizational structure for grouping MainItem objects.
+ *
+ * Properties:
+ *  - name: A human-friendly name for the container.
+ *  - items: A CoList of MainItem references.
+ */
+export class Container extends CoMap {
+  /** Human-friendly name for this container. */
+  name = co.string;
+
+  /** A list of MainItems held by this container. */
+  items = co.ref(MainItemList);
+}
+
+/**
+ * The top-level structure in the user’s account, representing all stored data.
+ *
+ * Properties:
+ *  - container: The default or root container for MainItems.
+ *  - version: An optional version number for supporting migrations.
+ */
+export class AccountRoot extends CoMap {
+  /** A single container to hold or organize items. */
+  container = co.ref(Container);
+
+  /** Tracks schema version for migrations. */
+  version = co.optional.number;
+}
+
+/**
+ * Represents a user’s profile data.
+ *
+ * Properties:
+ *  - email: Required email field for identification/contact.
+ *
+ * Static method:
+ *  - validate: Enforces that both name and email are provided.
+ */
+export class UserProfile extends Profile {
+  /** Required user email. */
+  email = co.string;
+
+  /**
+   * Validate user profile data, ensuring both "name" and "email" exist and are non-empty.
+   */
+  static validate(data: { name?: string; email?: string }) {
+    const errors: string[] = [];
+    if (!data.name?.trim()) {
+      errors.push("Please enter a name.");
+    }
+    if (!data.email?.trim()) {
+      errors.push("Please enter an email.");
+    }
+    return { errors };
+  }
+}
+
+/**
+ * The main Account class that holds the user’s data (AccountRoot) and profile.
+ * Handles initial migrations (setting up default Container, etc.) and can be extended
+ * to run future schema migrations.
+ */
+export class JazzAccount extends Account {
+  /** Reference to the user’s profile. */
+  profile = co.ref(UserProfile);
+
+  /** Reference to the account root data (container, version, etc.). */
+  root = co.ref(AccountRoot);
+
+  /**
+   * Migrate is run on creation and each login. If there is no root, creates initial data.
+   * Otherwise, you can add version-based migrations (below).
+   */
+  async migrate(creationProps?: { name: string; other?: Record<string, unknown> }) {
+    if (!this._refs.root && creationProps) {
+      await this.initialMigration(creationProps);
+      return;
+    }
+
+    // KEEP THESE COMMENTS IN THE GENERATED SCHEMA CODE
+    // uncomment this to add migrations
+    // Check the current version and run subsequent migrations
+    // const currentVersion = this.root?.version || 0;
+    // if (currentVersion < 1) {
+    //   await this.migrationV1();
+    // }
+    // Add more version checks and migrations as needed
+    // if (currentVersion < 2) {
+    //   await this.migrationV2();
+    // }
+  }
+
+  /**
+   * Executes the initial migration logic when the account is first created:
+   *  - Validates the user’s profile data (name, email).
+   *  - Sets up a public group (readable by "everyone") for the user’s profile.
+   *  - Sets up a private group to own private resources.
+   *  - Creates a default Container with a single MainItem.
+   */
+  private async initialMigration(
+    creationProps: { name: string; other?: Record<string, unknown> }
+  ) {
+    const { name, other } = creationProps;
+
+    // Validate profile data
+    const profileErrors = UserProfile.validate({ name, ...other });
+    if (profileErrors.errors.length > 0) {
+      throw new Error(
+        "Invalid profile data: " + profileErrors.errors.join(", "),
+      );
+    }
+
+    // Create a public group for the profile
+    const publicGroup = Group.create({ owner: this });
+    publicGroup.addMember("everyone", "reader");
+
+    // Create the user profile with validated data
+    this.profile = UserProfile.create(
+      {
+        name,
+        ...other,
+      },
+      { owner: publicGroup },
+    );
+
+    // Create a private group for data that should not be publicly readable
+    const privateGroup = Group.create({ owner: this });
+
+    // Create a default container with one default item
+    const defaultContainer = Container.create(
+      {
+        name: this.profile?.name
+          ? \`\${this.profile.name}'s items\`
+          : "Your items",
+        items: MainItemList.create(
+          [
+            MainItem.create({ name: "Default item" }, privateGroup),
+          ],
+          privateGroup,
+        ),
+      },
+      privateGroup,
+    );
+
+    // Initialize the account root with version tracking
+    this.root = AccountRoot.create(
+      {
+        container: defaultContainer,
+        version: 0, // Start at version 0
+      },
+      { owner: this },
+    );
+  }
+
+  // KEEP THESE COMMENTS IN THE GENERATED SCHEMA CODE
+  // uncomment this to add migrations
+  // private async migrationV1() {
+  //   Example migration logic:
+  //   if (this.root) {
+  //     // e.g., add a new field to all items
+  //     // for (const container of this.root.containers || []) {
+  //     //   for (const item of container.items || []) {
+  //     //     item.newField = "default value";
+  //     //   }
+  //     // }
+  //     this.root.version = 1;
+  //   }
+  // }
+
+  // KEEP THESE COMMENTS IN THE GENERATED SCHEMA CODE
+  // uncomment this to add migrations
+  // private async migrationV2() {
+  //   if (this.root) {
+  //     // Future migration logic goes here
+  //     this.root.version = 2;
+  //   }
+  // }
+}
+
+---
+
+Continue: 3_jazz_rules.md

packages/cursor-docs/.cursor/docs/3_jazz_rules.md

@@ -0,0 +1,55 @@
+---
+
+**Jazz Schema Rules:**
+
+1. **User Profile and Account**
+   1.1. Define `export class UserProfile extends Profile` with exactly one property:
+   ```ts
+   name = co.string;
+   ```
+   1.2. Add a static `validate` method in `UserProfile` that checks `name` is present and non-empty.
+   1.3. Define `export class JazzAccount extends Account` with exactly two properties:
+   ```ts
+   profile = co.ref(UserProfile);
+   root = co.ref(AccountRoot);
+   ```
+   1.4. The `JazzAccount` class must have a `migrate(creationProps?: { name: string; other?: Record<string, unknown> })` method.
+      - Within `migrate`, if `this._refs.root` is undefined and `creationProps` is provided, run `initialMigration`.
+      - The `creationProps` **must** include a `name` property; `other` is optional but do not define more fields.
+
+2. **Container, Root & Ownership**
+   2.1. The `AccountRoot` class (extending `CoMap`) **must** have a `container` property referencing a `Container`.
+   2.2. The `Container` class (extending `CoMap`) should contain the main domain entities of the app.
+   2.3. **Never** define a `name` field in the `Container` class. The template shows an example `name` property for a Container, but these rules override that.
+   2.4. Whenever the root structure is initialized, it is always owned by the current `JazzAccount`:
+   ```ts
+   this.root = AccountRoot.create({ container: defaultContainer, version: 0 }, { owner: this });
+   ```
+
+3. **Groups & Ownership**
+   3.1. If the `UserProfile` is intended to be public, set its owner to a `publicGroup` that has `"everyone"` as `"reader"`. Otherwise, use a private group.
+   3.2. When creating a group, no need to explicitly pass `owner: this`. That is implicit if it's the same account.
+   3.3. **Do not** use properties like `user`, `users`, `group`, or `groups` in CoMaps or CoLists. Ownership is implicit.
+
+4. **No Direct CoList Fields**
+   4.1. **Never** do:
+   ```ts
+   co.ref(CoList.Of(co.ref(SomeClass)));
+   ```
+   4.2. Instead, define a CoList class (e.g. `export class SomeClassList extends CoList.Of(co.ref(SomeClass)) {}`) and reference it.
+
+5. **Schema Structure & Fields**
+   5.1. Follow the provided template patterns. **Do not** add extra entities or fields outside the user’s requirements or the template.
+   5.2. Do **not** use properties like `createdAt` or `updatedAt`; they’re implicit in CoValue.
+   5.3. If a property is optional, denote it with a question mark (`?`) in the field definition, or use `co.optional.*`.
+   5.4. Keep comments from the template, especially around migration blocks, intact.
+   5.5. Never set a property to "co.ref(UserProfile)".
+
+6. **Output & Formatting**
+   6.1. Generate the final schema in TypeScript with no extra markdown or triple backticks.
+   6.2. Do **not** expand or alter the template’s classes beyond what is required.
+   6.3. Avoid redundant or conflicting rules from the template; these revised rules take priority.
+
+---
+
+Continue: 4_1_jazz_example.md

packages/cursor-docs/.cursor/docs/4_1_jazz_example.md

@@ -0,0 +1,229 @@
+# Example app 1: A secure and organized password manager app that allows users to store, manage, and categorize their credentials in folders
+
+```typescript
+import { Account, CoList, CoMap, Group, Profile, co } from "jazz-tools";
+
+/**
+ * Represents a password item in the Password Manager.
+ *
+ * Properties:
+ *  - name: The required name identifying the password item.
+ *  - username: Optional username.
+ *  - username_input_selector: Optional selector for the username input field.
+ *  - password: The required password.
+ *  - password_input_selector: Optional selector for the password input.
+ *  - uri: Optional URI associated with the item.
+ *  - folder: Reference to the parent Folder.
+ *  - deleted: Soft delete flag.
+ */
+export class PasswordItem extends CoMap {
+  name = co.string;
+  username = co.optional.string;
+  username_input_selector = co.optional.string;
+  password = co.string;
+  password_input_selector = co.optional.string;
+  uri = co.optional.string;
+  folder = co.ref(Folder);
+  deleted = co.boolean;
+}
+
+/**
+ * A list of PasswordItem references.
+ */
+export class PasswordList extends CoList.Of(co.ref(PasswordItem)) {}
+
+/**
+ * Represents a folder that groups password items.
+ *
+ * Properties:
+ *  - name: The folder's name.
+ *  - items: A list of PasswordItems contained in the folder.
+ */
+export class Folder extends CoMap {
+  name = co.string;
+  items = co.ref(PasswordList);
+}
+
+/**
+ * A list of Folder references.
+ */
+export class FolderList extends CoList.Of(co.ref(Folder)) {}
+
+/**
+ * Top-level container for the Password Manager.
+ * This container holds the main entities of the app.
+ *
+ * Properties:
+ *  - folders: A list of Folder entities.
+ */
+export class Container extends CoMap {
+  folders = co.ref(FolderList);
+}
+
+/**
+ * The account root holds all user data.
+ *
+ * Properties:
+ *  - container: The main container that organizes the app’s data.
+ *  - version: An optional version number used for migrations.
+ */
+export class PasswordManagerAccountRoot extends CoMap {
+  container = co.ref(Container);
+  version = co.optional.number;
+}
+
+/**
+ * Represents the user's profile.
+ *
+ * Properties:
+ *  - name: The required user name.
+ *
+ * Static method:
+ *  - validate: Ensures that a non-empty name is provided.
+ */
+export class UserProfile extends Profile {
+  name = co.string;
+
+  static validate(data: { name?: string; email?: string }) {
+    const errors: string[] = [];
+    if (!data.name?.trim()) {
+      errors.push("Please enter a name.");
+    }
+    // Note: In this schema, only 'name' is required.
+    return { errors };
+  }
+}
+
+/**
+ * Main account class for the Password Manager.
+ * Contains only the profile and root properties.
+ * Handles data initialization and migrations.
+ */
+export class PasswordManagerAccount extends Account {
+  profile = co.ref(UserProfile);
+  root = co.ref(PasswordManagerAccountRoot);
+
+  /**
+   * The migrate method is called on account creation and login.
+   * If the root is not initialized, it runs the initial migration.
+   * Otherwise, you can add version-based migrations as needed.
+   */
+  async migrate(creationProps?: { name: string; other?: Record<string, unknown> }) {
+    if (!this._refs.root && creationProps) {
+      await this.initialMigration(creationProps);
+      return;
+    }
+
+    // KEEP THESE COMMENTS IN THE GENERATED SCHEMA CODE
+    // Uncomment the following lines to add migrations:
+    // const currentVersion = this.root?.version || 0;
+    // if (currentVersion < 1) {
+    //   await this.migrationV1();
+    // }
+    // if (currentVersion < 2) {
+    //   await this.migrationV2();
+    // }
+  }
+
+  /**
+   * Executes the initial migration logic when the account is first created.
+   *  - Validates the user's profile data.
+   *  - Sets up a public group for the profile (accessible by "everyone").
+   *  - Sets up a private group for private resources.
+   *  - Creates a default Container with a default Folder and a default PasswordItem.
+   */
+  private async initialMigration(creationProps: { name: string; other?: Record<string, unknown> }) {
+    const { name, other } = creationProps;
+    const profileErrors = UserProfile.validate({ name, ...other });
+    if (profileErrors.errors.length > 0) {
+      throw new Error("Invalid profile data: " + profileErrors.errors.join(", "));
+    }
+
+    // Create a public group for the user profile.
+    const publicGroup = Group.create({ owner: this });
+    publicGroup.addMember("everyone", "reader");
+
+    // Create the user profile with validated data.
+    this.profile = UserProfile.create(
+      {
+        name,
+        ...other,
+      },
+      { owner: publicGroup }
+    );
+
+    // Create a private group for private data.
+    const privateGroup = Group.create({ owner: this });
+
+    // Create a default Folder with one default PasswordItem.
+    const defaultFolder = Folder.create(
+      {
+        name: "Default",
+        items: PasswordList.create(
+          [
+            PasswordItem.create(
+              {
+                name: "Gmail",
+                username: "user@gmail.com",
+                password: "password123",
+                uri: "https://gmail.com",
+                // The folder reference will be set after defaultFolder creation.
+                folder: null as any,
+                deleted: false,
+              },
+              privateGroup
+            ),
+          ],
+          privateGroup
+        ),
+      },
+      privateGroup
+    );
+    // Set the folder reference for the default PasswordItem.
+    defaultFolder.items[0].folder = defaultFolder;
+
+    // Create a default container that holds the FolderList.
+    const defaultContainer = Container.create(
+      {
+        folders: FolderList.create([defaultFolder], privateGroup),
+      },
+      privateGroup
+    );
+
+    // Initialize the account root with version tracking.
+    this.root = PasswordManagerAccountRoot.create(
+      {
+        container: defaultContainer,
+        version: 0, // Set initial version
+      },
+      { owner: this }
+    );
+  }
+
+  // KEEP THESE COMMENTS IN THE GENERATED SCHEMA CODE
+  // Uncomment the following methods to add migrations:
+
+  // private async migrationV1() {
+  //   if (this.root) {
+  //     // Example migration logic: add a new field to all password items.
+  //     // for (const folder of this.root.container.folders || []) {
+  //     //   for (const item of folder.items || []) {
+  //     //     item.newField = "default value";
+  //     //   }
+  //     // }
+  //     this.root.version = 1;
+  //   }
+  // }
+
+  // private async migrationV2() {
+  //   if (this.root) {
+  //     // Future migration logic goes here.
+  //     this.root.version = 2;
+  //   }
+  // }
+}
+```
+
+---
+
+Continue: 4_2_jazz_example.md

packages/cursor-docs/.cursor/docs/4_2_jazz_example.md

@@ -0,0 +1,177 @@
+# Example app 2: A feature-rich music player app that allows users to manage playlists, store tracks, and visualize audio waveforms
+
+```typescript
+export class MusicTrack extends CoMap {
+  title = co.string;
+  duration = co.number;
+  sourceTrack = co.optional.ref(MusicTrack);
+  file = co.ref(FileStream);
+  waveform = co.ref(MusicTrackWaveform);
+  container = co.ref(Playlist);
+  deleted = co.boolean;
+}
+
+/**
+ * Represents waveform data for a music track.
+ *
+ * Properties:
+ *  - data: A JSON array of numbers representing the waveform.
+ */
+export class MusicTrackWaveform extends CoMap {
+  data = co.json<number[]>();
+}
+
+/**
+ * A collaborative list of MusicTrack references.
+ */
+export class MusicTrackList extends CoList.Of(co.ref(MusicTrack)) {}
+
+/**
+ * Acts as a container for music tracks.
+ *
+ * Properties:
+ *  - name: The name of the playlist.
+ *  - items: A list of MusicTracks in this playlist.
+ */
+export class Playlist extends CoMap {
+  name = co.string;
+  items = co.ref(MusicTrackList);
+}
+
+/**
+ * The top-level account root for the music app.
+ *
+ * Properties:
+ *  - container: The main playlist (acting as the container for music tracks).
+ *  - version: Optional version number for migrations.
+ */
+export class MusicAccountRoot extends CoMap {
+  container = co.ref(Playlist);
+  version = co.optional.number;
+}
+
+/**
+ * Represents a user's profile.
+ *
+ * Properties:
+ *  - name: The required user name.
+ *
+ * Static method:
+ *  - validate: Ensures that a non-empty name and email are provided.
+ */
+export class UserProfile extends Profile {
+  name = co.string;
+
+  static validate(data: { name?: string; email?: string }) {
+    const errors: string[] = [];
+    if (!data.name?.trim()) {
+      errors.push("Please enter a name.");
+    }
+    if (!data.email?.trim()) {
+      errors.push("Please enter an email.");
+    }
+    return { errors };
+  }
+}
+
+/**
+ * The main Account class for the music app.
+ * Contains only the profile and root properties.
+ * Handles data initialization and migrations.
+ */
+export class MusicAccount extends Account {
+  profile = co.ref(UserProfile);
+  root = co.ref(MusicAccountRoot);
+
+  /**
+   * Migrate is run on account creation and each login.
+   * If the root is not initialized, run initial migration.
+   * Otherwise, version-based migrations can be added.
+   */
+  async migrate(creationProps?: { name: string; other?: Record<string, unknown> }) {
+    if (!this._refs.root && creationProps) {
+      await this.initialMigration(creationProps);
+      return;
+    }
+
+    // KEEP THESE COMMENTS IN THE GENERATED SCHEMA CODE
+    // Uncomment to add migrations:
+    // const currentVersion = this.root?.version || 0;
+    // if (currentVersion < 1) {
+    //   await this.migrationV1();
+    // }
+    // if (currentVersion < 2) {
+    //   await this.migrationV2();
+    // }
+  }
+
+  /**
+   * Executes initial migration when the account is first created:
+   *  - Validates the user's profile data (name, email).
+   *  - Sets up a public group (with "everyone" as reader) for the profile.
+   *  - Creates a default Playlist with an empty MusicTrackList.
+   *  - Initializes the account root with version 0.
+   */
+  private async initialMigration(creationProps: { name: string; other?: Record<string, unknown> }) {
+    const { name, other } = creationProps;
+    const profileErrors = UserProfile.validate({ name, ...other });
+    if (profileErrors.errors.length > 0) {
+      throw new Error("Invalid profile data: " + profileErrors.errors.join(", "));
+    }
+
+    // Create a public group for the profile.
+    const publicGroup = Group.create({ owner: this });
+    publicGroup.addMember("everyone", "reader");
+
+    // Create the user profile with validated data.
+    this.profile = UserProfile.create(
+      { name, ...other },
+      { owner: publicGroup }
+    );
+
+    // Create a private group for the user's music data.
+    const privateGroup = Group.create({ owner: this });
+
+    // Create a default Playlist as the main container.
+    const defaultPlaylist = Playlist.create(
+      {
+        name: this.profile.name + "'s playlist",
+        items: MusicTrackList.create([], privateGroup),
+      },
+      privateGroup
+    );
+
+    // Initialize the account root with version tracking.
+    this.root = MusicAccountRoot.create(
+      {
+        container: defaultPlaylist,
+        version: 0, // Set initial version
+      },
+      { owner: this }
+    );
+  }
+
+  // KEEP THESE COMMENTS IN THE GENERATED SCHEMA CODE
+  // Uncomment to add migrations:
+  // private async migrationV1() {
+  //   if (this.root) {
+  //     // Example migration logic: add a new field to all music tracks.
+  //     // for (const track of this.root.container.items || []) {
+  //     //   track.newField = "default value";
+  //     // }
+  //     this.root.version = 1;
+  //   }
+  // }
+
+  // private async migrationV2() {
+  //   if (this.root) {
+  //     // Future migration logic goes here.
+  //     this.root.version = 2;
+  //   }
+  // }
+}
+```
+
+---
+
+Continue: 4_3_jazz_example.md

packages/cursor-docs/.cursor/docs/4_3_jazz_example.md

@@ -0,0 +1,182 @@
+# Example app 3: A social pet app where users can share pet photos, react with fun emojis, and organize posts in a collaborative feed
+
+```typescript
+import { Account, CoFeed, CoList, CoMap, Group, ImageDefinition, Profile, co } from "jazz-tools";
+
+export const ReactionTypes = [
+  "aww",
+  "love",
+  "haha",
+  "wow",
+  "tiny",
+  "chonkers",
+] as const;
+
+export type ReactionType = (typeof ReactionTypes)[number];
+
+/**
+ * Represents an append-only feed of reactions for a pet post.
+ */
+export class PetReactions extends CoFeed.Of(co.json<ReactionType>()) {}
+
+/**
+ * Represents a pet post.
+ *
+ * Properties:
+ *  - name: The title or caption for the pet post.
+ *  - image: A reference to an ImageDefinition containing the pet's image.
+ *  - reactions: A feed of reactions (of type ReactionType) for the post.
+ */
+export class PetPost extends CoMap {
+  name = co.string;
+  image = co.ref(ImageDefinition);
+  reactions = co.ref(PetReactions);
+}
+
+/**
+ * A collaborative list of PetPost references.
+ */
+export class ListOfPosts extends CoList.Of(co.ref(PetPost)) {}
+
+/**
+ * Container for the pet posts.
+ *
+ * This container acts as the main organizational structure holding the posts.
+ *
+ * Properties:
+ *  - posts: A list of pet posts.
+ */
+export class PetContainer extends CoMap {
+  posts = co.ref(ListOfPosts);
+}
+
+/**
+ * The top-level account root for the pet app.
+ *
+ * Properties:
+ *  - container: The main container that organizes pet posts.
+ *  - version: An optional version number for supporting migrations.
+ */
+export class PetAccountRoot extends CoMap {
+  container = co.ref(PetContainer);
+  version = co.optional.number;
+}
+
+/**
+ * Represents a user’s profile.
+ *
+ * Properties:
+ *  - name: The required user name.
+ *
+ * Static method:
+ *  - validate: Ensures that both "name" and "email" (if provided) are non-empty.
+ */
+export class UserProfile extends Profile {
+  name = co.string;
+
+  static validate(data: { name?: string; email?: string }) {
+    const errors: string[] = [];
+    if (!data.name?.trim()) {
+      errors.push("Please enter a name.");
+    }
+    if (data.email !== undefined && !data.email?.trim()) {
+      errors.push("Please enter an email.");
+    }
+    return { errors };
+  }
+}
+
+/**
+ * Main account class for the pet app.
+ *
+ * Contains only the profile and root properties, and handles account initialization
+ * and migrations.
+ */
+export class PetAccount extends Account {
+  profile = co.ref(UserProfile);
+  root = co.ref(PetAccountRoot);
+
+  /**
+   * Migrate is run on account creation and on every log-in.
+   * If the root is not initialized, it runs the initial migration.
+   * Otherwise, version-based migrations can be added.
+   */
+  async migrate(creationProps?: { name: string; other?: Record<string, unknown> }) {
+    if (!this._refs.root && creationProps) {
+      await this.initialMigration(creationProps);
+      return;
+    }
+
+    // KEEP THESE COMMENTS IN THE GENERATED SCHEMA CODE
+    // Uncomment the following lines to add migrations:
+    // const currentVersion = this.root?.version || 0;
+    // if (currentVersion < 1) {
+    //   await this.migrationV1();
+    // }
+    // if (currentVersion < 2) {
+    //   await this.migrationV2();
+    // }
+  }
+
+  /**
+   * Executes the initial migration logic when the account is first created:
+   *  - Validates the user's profile data (name, email).
+   *  - Sets up a public group (accessible by "everyone") for the user’s profile.
+   *  - Sets up a private group for the user's pet posts.
+   *  - Creates a default container with an empty list of posts.
+   *  - Initializes the account root with version 0.
+   */
+  private async initialMigration(creationProps: { name: string; other?: Record<string, unknown> }) {
+    const { name, other } = creationProps;
+    const profileErrors = UserProfile.validate({ name, ...other });
+    if (profileErrors.errors.length > 0) {
+      throw new Error("Invalid profile data: " + profileErrors.errors.join(", "));
+    }
+
+    // Create a public group for the user profile.
+    const publicGroup = Group.create({ owner: this });
+    publicGroup.addMember("everyone", "reader");
+
+    // Create the user profile with validated data.
+    this.profile = UserProfile.create(
+      { name, ...other },
+      { owner: publicGroup }
+    );
+
+    // Create a private group for pet data.
+    const privateGroup = Group.create({ owner: this });
+
+    // Create a default container holding an empty list of posts.
+    const defaultContainer = PetContainer.create(
+      { posts: ListOfPosts.create([], privateGroup) },
+      privateGroup
+    );
+
+    // Initialize the account root with version tracking.
+    this.root = PetAccountRoot.create(
+      { container: defaultContainer, version: 0 },
+      { owner: this }
+    );
+  }
+
+  // KEEP THESE COMMENTS IN THE GENERATED SCHEMA CODE
+  // Uncomment to add migrations:
+  // private async migrationV1() {
+  //   if (this.root) {
+  //     // Example migration logic: update pet posts if needed.
+  //     this.root.version = 1;
+  //   }
+  // }
+
+  // private async migrationV2() {
+  //   if (this.root) {
+  //     // Future migration logic goes here.
+  //     this.root.version = 2;
+  //   }
+  // }
+}
+```
+
+---
+
+Continue: 4_4_jazz_example.md

packages/cursor-docs/.cursor/docs/4_4_jazz_example.md

@@ -0,0 +1,240 @@
+# Example app 4: A bubble tea ordering app that lets users customize drinks with different tea bases, add-ons, and delivery preferences
+
+```typescript
+import { Account, CoList, CoMap, Group, Profile, co } from "jazz-tools";
+
+export const BubbleTeaAddOnTypes = [
+  "Pearl",
+  "Lychee jelly",
+  "Red bean",
+  "Brown sugar",
+  "Taro",
+] as const;
+
+export const BubbleTeaBaseTeaTypes = [
+  "Black",
+  "Oolong",
+  "Jasmine",
+  "Thai",
+] as const;
+
+/**
+ * A list of Bubble Tea add-ons.
+ * Provides a computed property to check for insertions.
+ */
+export class ListOfBubbleTeaAddOns extends CoList.Of(co.literal(...BubbleTeaAddOnTypes)) {
+  get hasChanges() {
+    return Object.entries(this._raw.insertions).length > 0;
+  }
+}
+
+/**
+ * Represents a finalized Bubble Tea order.
+ *
+ * Properties:
+ *  - baseTea: Selected base tea type.
+ *  - addOns: Selected add-ons.
+ *  - deliveryDate: Delivery date for the order.
+ *  - withMilk: Indicates if the order includes milk.
+ *  - instructions: Optional additional instructions.
+ */
+export class BubbleTeaOrder extends CoMap {
+  baseTea = co.literal(...BubbleTeaBaseTeaTypes);
+  addOns = co.ref(ListOfBubbleTeaAddOns);
+  deliveryDate = co.Date;
+  withMilk = co.boolean;
+  instructions = co.optional.string;
+}
+
+/**
+ * Represents a draft (in-progress) Bubble Tea order.
+ *
+ * Properties:
+ *  - baseTea: Optional base tea type.
+ *  - addOns: Optional reference to selected add-ons.
+ *  - deliveryDate: Optional delivery date.
+ *  - withMilk: Optional milk preference.
+ *  - instructions: Optional instructions.
+ *
+ * Methods:
+ *  - validate: Checks that required fields are present.
+ * Computed:
+ *  - hasChanges: Indicates if there have been modifications.
+ */
+export class DraftBubbleTeaOrder extends CoMap {
+  baseTea = co.optional.literal(...BubbleTeaBaseTeaTypes);
+  addOns = co.optional.ref(ListOfBubbleTeaAddOns);
+  deliveryDate = co.optional.Date;
+  withMilk = co.optional.boolean;
+  instructions = co.optional.string;
+
+  get hasChanges() {
+    return Object.keys(this._edits).length > 1 || this.addOns?.hasChanges;
+  }
+
+  validate() {
+    const errors: string[] = [];
+    if (!this.baseTea) {
+      errors.push("Please select your preferred base tea.");
+    }
+    if (!this.deliveryDate) {
+      errors.push("Please select a delivery date.");
+    }
+    return { errors };
+  }
+}
+
+/**
+ * A collaborative list of finalized Bubble Tea orders.
+ */
+export class ListOfBubbleTeaOrders extends CoList.Of(co.ref(BubbleTeaOrder)) {}
+
+/**
+ * Container for Bubble Tea orders.
+ * Holds the draft order and the list of finalized orders.
+ */
+export class BubbleTeaContainer extends CoMap {
+  draft = co.ref(DraftBubbleTeaOrder);
+  orders = co.ref(ListOfBubbleTeaOrders);
+}
+
+/**
+ * The top-level account root for the Bubble Tea app.
+ *
+ * Properties:
+ *  - container: The main container that organizes the Bubble Tea orders.
+ *  - version: Optional version number for migration tracking.
+ */
+export class BubbleTeaAccountRoot extends CoMap {
+  container = co.ref(BubbleTeaContainer);
+  version = co.optional.number;
+}
+
+/**
+ * Represents a user's profile.
+ *
+ * Properties:
+ *  - name: Required user name.
+ *
+ * Static method:
+ *  - validate: Ensures that a non-empty name and email (if provided) are present.
+ */
+export class UserProfile extends Profile {
+  name = co.string;
+
+  static validate(data: { name?: string; email?: string }) {
+    const errors: string[] = [];
+    if (!data.name?.trim()) {
+      errors.push("Please enter a name.");
+    }
+    if (data.email !== undefined && !data.email.trim()) {
+      errors.push("Please enter an email.");
+    }
+    return { errors };
+  }
+}
+
+/**
+ * Main account class for the Bubble Tea app.
+ * Contains only the profile and root properties.
+ * Handles account initialization and migrations.
+ */
+export class BubbleTeaAccount extends Account {
+  profile = co.ref(UserProfile);
+  root = co.ref(BubbleTeaAccountRoot);
+
+  /**
+   * The migrate method is run on account creation and login.
+   * If the root is not initialized, it runs the initial migration.
+   * Otherwise, version-based migrations can be added.
+   */
+  async migrate(creationProps?: { name: string; other?: Record<string, unknown> }) {
+    if (!this._refs.root && creationProps) {
+      await this.initialMigration(creationProps);
+      return;
+    }
+
+    // KEEP THESE COMMENTS IN THE GENERATED SCHEMA CODE
+    // Uncomment the following lines to add migrations:
+    // const currentVersion = this.root?.version || 0;
+    // if (currentVersion < 1) {
+    //   await this.migrationV1();
+    // }
+    // if (currentVersion < 2) {
+    //   await this.migrationV2();
+    // }
+  }
+
+  /**
+   * Executes the initial migration logic when the account is first created:
+   *  - Validates the user's profile data (name, email).
+   *  - Sets up a public group (accessible by "everyone") for the user's profile.
+   *  - Sets up a private group for the Bubble Tea data.
+   *  - Creates a default BubbleTeaContainer with an empty draft and order list.
+   *  - Initializes the account root with version 0.
+   */
+  private async initialMigration(creationProps: { name: string; other?: Record<string, unknown> }) {
+    const { name, other } = creationProps;
+    const profileErrors = UserProfile.validate({ name, ...other });
+    if (profileErrors.errors.length > 0) {
+      throw new Error("Invalid profile data: " + profileErrors.errors.join(", "));
+    }
+
+    // Create a public group for the user profile.
+    const publicGroup = Group.create({ owner: this });
+    publicGroup.addMember("everyone", "reader");
+
+    // Create the user profile with validated data.
+    this.profile = UserProfile.create(
+      { name, ...other },
+      { owner: publicGroup }
+    );
+
+    // Create a private group for Bubble Tea data.
+    const privateGroup = Group.create({ owner: this });
+
+    // Create a default container with an empty draft order and empty list of finalized orders.
+    const defaultContainer = BubbleTeaContainer.create(
+      {
+        draft: DraftBubbleTeaOrder.create(
+          {
+            addOns: ListOfBubbleTeaAddOns.create([], privateGroup),
+          },
+          privateGroup
+        ),
+        orders: ListOfBubbleTeaOrders.create([], privateGroup),
+      },
+      privateGroup
+    );
+
+    // Initialize the account root with version tracking.
+    this.root = BubbleTeaAccountRoot.create(
+      {
+        container: defaultContainer,
+        version: 0, // Set initial version
+      },
+      { owner: this }
+    );
+  }
+
+  // KEEP THESE COMMENTS IN THE GENERATED SCHEMA CODE
+  // Uncomment to add migrations:
+  // private async migrationV1() {
+  //   if (this.root) {
+  //     // Example migration logic: update orders if needed.
+  //     this.root.version = 1;
+  //   }
+  // }
+
+  // private async migrationV2() {
+  //   if (this.root) {
+  //     // Future migration logic goes here.
+  //     this.root.version = 2;
+  //   }
+  // }
+}
+```
+
+---
+
+Continue: 4_5_jazz_example.md