crann 1.0.49 → 2.0.2

package/README.md

@@ -1,4 +1,4 @@
-Crann: Effortless State Synchronization for Web Extensions
+# Crann: Effortless State Synchronization for Web Extensions
 
 ![crann_logo](img/crann_logo_smaller.png)
 
@@ -7,743 +7,502 @@ Crann: Effortless State Synchronization for Web Extensions
 ## Table of Contents
 
 - [Core Features](#core-features)
-- [Quick Start](#quick-start-a-simple-synchronization-example)
-- [Core Usage](#getting-started-core-usage)
-- [Advanced Features](#advanced-features)
-  - [Complex Types](#handling-complex-types)
-  - [Partitioned State](#understanding-partitioned-state)
-  - [Persistence](#state-persistence-options)
-  - [Advanced API](#advanced-api-functions)
-  - [Remote Procedure Calls (RPC Actions)](#remote-procedure-calls-rpc-actions)
-  - [React Integration](#react-integration)
-- [What Was The Problem?](#what-was-the-problem)
-- [Why Is This Better?](#why-is-this-better-how-crann-simplifies-synchronization)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Store API (Service Worker)](#store-api-service-worker)
+- [Agent API (Content Scripts, Popup, etc.)](#agent-api)
+- [React Integration](#react-integration)
+- [RPC Actions](#rpc-actions)
+- [State Persistence](#state-persistence)
+- [Migration from v1](#migration-from-v1)
+
+## Core Features
+
+- **Minimal size** (< 5kb gzipped)
+- **Multi-context sync** - Content Scripts, Service Worker, Devtools, Sidepanels, Popup
+- **No message boilerplate** - Eliminates `chrome.runtime.sendMessage` / `onMessage`
+- **Reactive updates** - Subscribe to state changes
+- **Persistence** - Optional local or session storage
+- **Full TypeScript** - Complete type inference from config
+- **React hooks** - First-class React integration via `crann/react`
+- **RPC Actions** - Execute logic in the service worker from any context
+
+## Quick Start
+
+### 1. Define Your Config
 
-## State Synchronization for Web Extensions
-
-Crann synchronizes state across all parts of your Web Extension with full TypeScript support, eliminating the need for complex manual message passing. Focus on your extension's features, not the plumbing.
-
-**Core Features:**
-
-- Minimal size (< 5kb)
-- Syncs state between any context (Content Scripts, Service Worker, Devtools, Sidepanels, Popup, etc.)
-- Eliminates manual `chrome.runtime.sendMessage` / `onMessage` boilerplate
-- Reactive state updates via subscriptions (`subscribe`)
-- Optional state persistence (`Persistence.Local` / `Persistence.Session`)
-- Strong TypeScript inference and support for type safety
-
-### Quick Start: A Simple Synchronization Example
-
-Let's see how easy it is. Imagine we want a toggle in the popup to control whether a border is applied to the current web page by a content script.
+```typescript
+// config.ts
+import { createConfig, Persist } from "crann";
+
+export const config = createConfig({
+  name: "myExtension", // Required: unique store name
+  version: 1, // Optional: for migrations
+
+  // Define your state
+  isEnabled: { default: false },
+  count: { default: 0, persist: Persist.Local },
+
+  // Define actions (RPC)
+  actions: {
+    increment: {
+      handler: async (ctx, amount: number = 1) => {
+        return { count: ctx.state.count + amount };
+      },
+    },
+  },
+});
+```
 
-**1. Define the state in your Service Worker:**
+### 2. Initialize the Store (Service Worker)
 
 ```typescript
 // service-worker.ts
-import { create } from "crann";
+import { createStore } from "crann";
+import { config } from "./config";
 
-const crann = create({
-  isBorderEnabled: { default: false }, // Single shared state item
-});
+const store = createStore(config);
 
-console.log("Crann hub initialized.");
-// Keep the service worker alive if needed (e.g., using chrome.runtime.connect)
-// Crann itself doesn't automatically keep the SW alive.
+store.subscribe((state, changes) => {
+  console.log("State changed:", changes);
+});
 ```
 
-**2. Control the state from your Popup:**
+### 3. Connect from Any Context
 
 ```typescript
-// popup.ts
-import { connect } from "crann";
+// popup.ts or content-script.ts
+import { connectStore } from "crann";
+import { config } from "./config";
 
-const { set, get } = connect(); // Connect to the Crann hub
+const agent = connectStore(config);
 
-const toggleButton = document.getElementById("toggleBorder");
+agent.onReady(() => {
+  console.log("Connected! Current state:", agent.getState());
 
-// Set initial button state
-const currentState = get();
-toggleButton.textContent = currentState.isBorderEnabled
-  ? "Disable Border"
-  : "Enable Border";
+  // Update state
+  agent.setState({ isEnabled: true });
 
-// Add click listener to update state
-toggleButton.addEventListener("click", () => {
-  const newState = !get().isBorderEnabled; // Get current state before setting
-  set({ isBorderEnabled: newState });
-  // Update button text immediately (or subscribe to changes)
-  toggleButton.textContent = newState ? "Disable Border" : "Enable Border";
+  // Call actions
+  agent.actions.increment(5);
 });
 ```
 
-**3. React to the state in your Content Script:**
+### 4. Use with React
 
 ```typescript
-// content-script.ts
-import { connect } from "crann";
+// hooks.ts
+import { createCrannHooks } from "crann/react";
+import { config } from "./config";
 
-const { subscribe } = connect(); // Connect to the Crann hub
+export const { useCrannState, useCrannActions, useCrannReady } =
+  createCrannHooks(config);
 
-console.log("Content script connected to Crann.");
+// Counter.tsx
+function Counter() {
+  const count = useCrannState((s) => s.count);
+  const { increment } = useCrannActions();
+  const isReady = useCrannReady();
 
-// Subscribe to changes in 'isBorderEnabled'
-subscribe(
-  (state) => {
-    console.log("Border state changed:", state.isBorderEnabled);
-    document.body.style.border = state.isBorderEnabled ? "5px solid green" : "";
-  },
-  ["isBorderEnabled"]
-); // Optional: Only trigger for specific key changes
-
-// Apply initial state
-const initialState = connect().get(); // Can call connect() again or store result
-document.body.style.border = initialState.isBorderEnabled
-  ? "5px solid green"
-  : "";
+  if (!isReady) return <div>Loading...</div>;
+
+  return <button onClick={() => increment(1)}>Count: {count}</button>;
+}
 ```
 
-**Notice:** We achieved synchronization between the popup and content script _without writing any `chrome.runtime.sendMessage` or `chrome.runtime.onMessage` code!_ Crann handled the communication behind the scenes.
+## Configuration
 
-## Getting Started: Core Usage
+The `createConfig` function defines your store schema:
 
-### Step 1: Create the State Hub (Service Worker)
+```typescript
+import { createConfig, Scope, Persist } from "crann";
 
-The service worker is where you initialize your shared state. Here's a more detailed example showing how to define different types of state:
+const config = createConfig({
+  // Required: unique identifier for this store
+  name: "myStore",
 
-```typescript
-// service-worker.ts
-import { create, Partition, Persistence } from "crann";
+  // Optional: version number for migrations (default: 1)
+  version: 1,
 
-const crann = create({
-  // Basic state with default value
-  active: { default: false },
+  // State definitions
+  count: { default: 0 },
 
-  // State that's unique to each context
-  name: {
-    default: "",
-    partition: Partition.Instance,
+  // With persistence
+  theme: {
+    default: "light" as "light" | "dark",
+    persist: Persist.Local, // Persist.Local | Persist.Session | Persist.None
   },
 
-  // State that persists between sessions
-  timesUsed: {
-    default: 0,
-    persistence: Persistence.Local,
+  // Agent-scoped state (each tab/frame gets its own copy)
+  selectedElement: {
+    default: null as HTMLElement | null,
+    scope: Scope.Agent, // Scope.Shared (default) | Scope.Agent
   },
 
-  // State that resets when the browser closes
-  sessionStart: {
-    default: new Date(),
-    persistence: Persistence.Session,
+  // Actions (RPC handlers)
+  actions: {
+    doSomething: {
+      handler: async (ctx, arg1: string, arg2: number) => {
+        // ctx.state - current state
+        // ctx.setState - update state
+        // ctx.agentId - calling agent's ID
+        return { result: "value" };
+      },
+      validate: (arg1, arg2) => {
+        if (!arg1) throw new Error("arg1 required");
+      },
+    },
   },
 });
+```
 
-// Get shared state (no instance state)
-const { active, timesUsed } = crann.get();
+## Store API (Service Worker)
 
-// Optionally: Get state for a specific instance (includes instance state)
-const { active, timesUsed, name } = crann.get("instanceKey");
+The Store runs in the service worker and manages all state:
 
-// Subscribe to state changes
-crann.subscribe((state, changes, key) => {
-  // state contains all state (shared + relevant partition)
-  // changes contains only the keys that changed
-  // key identifies which context made the change (null if from service worker)
-  console.log("State changed:", changes);
+```typescript
+import { createStore } from "crann";
+
+const store = createStore(config, {
+  debug: true, // Enable debug logging
 });
-```
 
-### Step 2: Connect from Other Contexts
+// Get current state
+const state = store.getState();
 
-Other parts of your extension connect to the state hub. They automatically get access to both shared and their own partitioned state:
+// Update state
+await store.setState({ count: 5 });
 
-```typescript
-// popup.ts or content-script.ts
-import { connect } from "crann";
+// Get agent-scoped state for a specific agent
+const agentState = store.getAgentState(agentId);
 
-const { get, set, subscribe } = connect();
+// Subscribe to all state changes
+const unsubscribe = store.subscribe((state, changes, agentInfo) => {
+  console.log("Changed:", changes);
+});
 
-// Get all state (shared + this context's partition)
-const { active, name, timesUsed } = get();
+// Listen for agent connections
+store.onAgentConnect((agent) => {
+  console.log(`Agent ${agent.id} connected from tab ${agent.tabId}`);
+});
 
-// Set state
-set({ name: "My Context's Name" });
+store.onAgentDisconnect((agent) => {
+  console.log(`Agent ${agent.id} disconnected`);
+});
 
-// Subscribe to specific state changes
-subscribe(
-  (changes) => {
-    console.log("Times used changed:", changes.timesUsed);
-  },
-  ["timesUsed"]
-);
-```
+// Get all connected agents
+const agents = store.getAgents();
+const contentScripts = store.getAgents({ context: "contentscript" });
 
-## Advanced Features
+// Clear all state to defaults
+await store.clear();
 
-### Handling Complex Types
+// Destroy the store (cleanup)
+store.destroy();
+// Or clear persisted data on destroy:
+store.destroy({ clearPersisted: true });
+```
 
-Sometimes the default value alone isn't enough for TypeScript to infer the full type. Use type assertions to specify the complete type:
+## Agent API
 
-```typescript
-import { create } from "crann";
+Agents connect to the store from content scripts, popups, and other contexts:
 
-// Example 1: Custom object type with null default
-type CustomType = { name: string; age: number };
+```typescript
+import { connectStore } from "crann";
 
-// Example 2: Specific string literal union
-type ConnectionStatus = "idle" | "connecting" | "connected" | "error";
+const agent = connectStore(config, {
+  debug: true,
+});
 
-const crann = create({
-  person: {
-    default: null as null | CustomType,
-  },
-  connectionStatus: {
-    default: "idle" as ConnectionStatus,
-  },
-  userStatus: {
-    default: "active" as "active" | "inactive",
-    persistence: Persistence.Local,
-  },
+// Wait for connection to be ready
+agent.onReady(() => {
+  console.log("Connected!");
 });
 
-// Now TypeScript understands the full potential types
-const state = crann.get();
-// state.person could be null or { name: string; age: number }
-// state.connectionStatus could be 'idle', 'connecting', 'connected', or 'error'
-```
+// Or use the promise
+await agent.ready();
 
-### Understanding Partitioned State
+// Get current state
+const state = agent.getState();
 
-Partitioned state (`Partition.Instance`) is useful when you want each context to have its own version of a state variable. For example:
+// Update state
+await agent.setState({ count: 10 });
 
-- Each content script might need its own `selectedElement` state
-- Each popup might need its own `isOpen` state
-- Each devtools panel might need its own `activeTab` state
+// Subscribe to changes
+const unsubscribe = agent.subscribe((changes, state) => {
+  console.log("State changed:", changes);
+});
+
+// Call actions (RPC)
+const result = await agent.actions.doSomething("arg1", 42);
 
-The service worker can access any context's partitioned state using `get('instanceKey')`, but typically you'll let each context manage its own partitioned state.
+// Get agent info
+const info = agent.getInfo();
+// { id, tabId, frameId, context }
 
-### State Persistence Options
+// Handle disconnect/reconnect
+agent.onDisconnect(() => console.log("Disconnected"));
+agent.onReconnect(() => console.log("Reconnected"));
+
+// Clean up
+agent.disconnect();
+```
 
-Crann offers two levels of persistence:
+## React Integration
 
-- **Session Storage** (`Persistence.Session`): State persists between page refreshes but resets when the browser closes
-- **Local Storage** (`Persistence.Local`): State persists long-term until explicitly cleared
+Import from `crann/react` for React hooks:
 
 ```typescript
-const crann = create({
-  // Will be remembered between browser sessions
-  userPreferences: {
-    default: { theme: "light" },
-    persistence: Persistence.Local,
-  },
+import { createCrannHooks } from "crann/react";
+import { config } from "./config";
 
-  // Will reset when browser closes
-  currentSession: {
-    default: { startTime: new Date() },
-    persistence: Persistence.Session,
-  },
-});
+// Create hooks bound to your config
+export const {
+  useCrannState,
+  useCrannActions,
+  useCrannReady,
+  useAgent,
+  CrannProvider,
+} = createCrannHooks(config);
 ```
 
-Remember: Persisted state is always shared state (not partitioned).
+### useCrannState
 
-### Advanced API Functions
-
-The `create` function returns an object with the following methods:
+Two patterns for reading state:
 
 ```typescript
-const crann = create({
-  // ... state config ...
-});
+// Selector pattern - returns selected value
+const count = useCrannState((s) => s.count);
+const theme = useCrannState((s) => s.settings.theme);
 
-// Get state
-const state = crann.get(); // Get all state
-const instanceState = crann.get("instanceKey"); // Get state for specific instance
+// Key pattern - returns [value, setValue] tuple
+const [count, setCount] = useCrannState("count");
+setCount(10); // Updates state
+```
 
-// Set state
-await crann.set({ key: "value" }); // Set service state
-await crann.set({ key: "value" }, "instanceKey"); // Set instance state
+### useCrannActions
 
-// Subscribe to state changes
-crann.subscribe((state, changes, agent) => {
-  // state: The complete state
-  // changes: Only the changed values
-  // agent: Info about which context made the change
-});
+Returns typed actions with stable references (won't cause re-renders):
 
-// Subscribe to instance ready events
-const unsubscribe = crann.onInstanceReady((instanceId, agent) => {
-  // Called when a new instance connects
-  // Returned function can be called to unsubscribe
-});
+```typescript
+const { increment, fetchData } = useCrannActions();
 
-// Find an instance by location
-const instanceId = crann.findInstance({
-  context: "content-script",
-  tabId: 123,
-  frameId: 0,
-});
+// Actions are async
+await increment(5);
+const result = await fetchData("https://api.example.com");
+```
 
-// Query agents by location
-const agents = crann.queryAgents({
-  context: "content-script",
-});
+### useCrannReady
 
-// Clear all state
-await crann.clear();
-```
+Check connection status:
 
-### Remote Procedure Calls (RPC Actions)
+```typescript
+const isReady = useCrannReady();
 
-Crann supports RPC-style actions that execute in the service worker context while being callable from any extension context. This is perfect for operations that need to run in the service worker, like making network requests or accessing extension APIs.
+if (!isReady) {
+  return <LoadingSpinner />;
+}
+```
 
-#### Defining Actions in the Service Worker
+### CrannProvider (Optional)
 
-Actions are defined in your config alongside regular state items. The key difference is that actions have a `handler` property:
+For testing or dependency injection:
 
 ```typescript
-// service-worker.ts
-import { create } from "crann";
-import { BrowserLocation } from "porter-source";
+// In tests
+const mockAgent = createMockAgent();
 
-const crann = create({
-  // Regular state
-  counter: {
-    default: 0,
-    persist: "local",
-  },
+render(
+  <CrannProvider agent={mockAgent}>
+    <MyComponent />
+  </CrannProvider>
+);
+```
 
-  // RPC action
-  increment: {
-    handler: async (
-      state: any,
-      setState: (newState: Partial<any>) => Promise<void>,
-      target: BrowserLocation,
-      amount: number
-    ) => {
-      // This runs in the service worker
-      const newCounter = state.counter + amount;
-      await setState({ counter: newCounter });
-      return { counter: newCounter };
-    },
-    validate: (amount: number) => {
-      if (amount < 0) throw new Error("Amount must be positive");
-    },
-  },
+## RPC Actions
 
-  // Another action example
-  fetchData: {
-    handler: async (
-      state: any,
-      setState: (newState: Partial<any>) => Promise<void>,
-      target: BrowserLocation,
-      url: string
-    ) => {
-      // This runs in the service worker where we can make network requests
-      const response = await fetch(url);
-      const data = await response.json();
-      return { data };
-    },
-    validate: (url: string) => {
-      if (!url.startsWith("https://")) {
-        throw new Error("URL must be HTTPS");
-      }
+Actions execute in the service worker but can be called from any context:
+
+```typescript
+// In config
+const config = createConfig({
+  name: "myStore",
+  count: { default: 0 },
+
+  actions: {
+    increment: {
+      handler: async (ctx, amount: number = 1) => {
+        const newCount = ctx.state.count + amount;
+        // Option 1: Return state updates
+        return { count: newCount };
+
+        // Option 2: Use ctx.setState
+        // await ctx.setState({ count: newCount });
+        // return { success: true };
+      },
     },
-  },
 
-  // Action that returns the current time
-  getCurrentTime: {
-    handler: async (
-      state: any,
-      setState: (newState: Partial<any>) => Promise<void>,
-      target: BrowserLocation
-    ) => {
-      return { time: new Date().toISOString() };
+    fetchUser: {
+      handler: async (ctx, userId: string) => {
+        // Runs in service worker - can make network requests
+        const response = await fetch(`/api/users/${userId}`);
+        const user = await response.json();
+        return { user };
+      },
+      validate: (userId) => {
+        if (!userId) throw new Error("userId required");
+      },
     },
   },
 });
-```
 
-#### Understanding Action Handler Parameters
+// From any context (popup, content script, etc.)
+const agent = connectStore(config);
+await agent.ready();
+
+const result = await agent.actions.increment(5);
+console.log(result.count); // 5
+
+const { user } = await agent.actions.fetchUser("123");
+console.log(user.name);
+```
 
-Action handlers receive four parameters that are automatically provided by Crann:
+### ActionContext
 
-1. **`state`**: The current state object containing all shared and service state
-2. **`setState`**: A function to update the state from within the action. Use this to persist changes made by your action
-3. **`target`**: A `BrowserLocation` object that identifies which context called the action
-4. **`...args`**: The arguments passed to the action when called via `callAction()`
+Action handlers receive a context object:
 
 ```typescript
-// Example showing how to use each parameter
-incrementWithLogging: {
-  handler: async (
-    state: any,
-    setState: (newState: Partial<any>) => Promise<void>,
-    target: BrowserLocation,
-    amount: number
-  ) => {
-    // Read from state
-    const currentCount = state.counter;
-
-    // Log which context called this action
-    console.log(`Increment called from ${target.context} with amount ${amount}`);
-
-    // Update state
-    const newCount = currentCount + amount;
-    await setState({ counter: newCount });
-
-    // Return result (optional)
-    return { counter: newCount, previousValue: currentCount };
-  },
+interface ActionContext<TState> {
+  state: TState; // Current state snapshot
+  setState: (partial: Partial<TState>) => Promise<void>; // Update state
+  agentId: string; // Calling agent's ID
+  agentLocation: BrowserLocation; // Tab/frame info
 }
 ```
 
-#### Using Actions in Service Worker
+## State Persistence
 
-Actions can be called from any context that connects to Crann:
+Control how state is persisted:
 
 ```typescript
-// content-script.ts
-import { connect } from "crann";
-import { config } from "./config";
-
-const { get, subscribe, onReady, callAction } = connect(config);
-
-// Wait for connection
-onReady((status) => {
-  if (status.connected) {
-    console.log("Connected to Crann");
-
-    // Use the increment action
-    document
-      .getElementById("incrementButton")
-      .addEventListener("click", async () => {
-        try {
-          const result = await callAction("increment", 1);
-          console.log("Counter incremented to:", result);
-          // Counter is updated in state automatically
-        } catch (error) {
-          console.error("Failed to increment:", error.message);
-        }
-      });
-
-    // Use the fetchData action
-    document
-      .getElementById("fetchButton")
-      .addEventListener("click", async () => {
-        try {
-          const result = await callAction(
-            "fetchData",
-            "https://api.example.com/data"
-          );
-          console.log("Fetched data:", result.data);
-        } catch (error) {
-          console.error("Failed to fetch data:", error.message);
-        }
-      });
-  }
-});
-```
+import { createConfig, Persist } from "crann";
 
-#### Using Actions in Popup/Options Pages
+const config = createConfig({
+  name: "myStore",
 
-The same pattern works in popup and options pages:
+  // No persistence (default) - resets on service worker restart
+  volatile: { default: null },
 
-```typescript
-// popup.ts
-import { connect } from "crann";
-import { config } from "./config";
+  // Local storage - persists across browser sessions
+  preferences: {
+    default: { theme: "light" },
+    persist: Persist.Local,
+  },
 
-const { get, callAction } = connect(config);
-
-document.addEventListener("DOMContentLoaded", () => {
-  // Display the current counter
-  const counterElement = document.getElementById("counter");
-  counterElement.textContent = get().counter.toString();
-
-  // Add click handler for the increment button
-  document
-    .getElementById("incrementButton")
-    .addEventListener("click", async () => {
-      try {
-        const result = await callAction("increment", 1);
-        counterElement.textContent = result.counter.toString();
-      } catch (error) {
-        console.error("Failed to increment:", error.message);
-      }
-    });
-
-  // Get and display the current time
-  document.getElementById("timeButton").addEventListener("click", async () => {
-    try {
-      const result = await callAction("getCurrentTime");
-      document.getElementById("currentTime").textContent = result.time;
-    } catch (error) {
-      console.error("Failed to get time:", error.message);
-    }
-  });
+  // Session storage - persists until browser closes
+  sessionData: {
+    default: {},
+    persist: Persist.Session,
+  },
 });
 ```
 
-#### Using Actions in React Components
+### Storage Keys
 
-Crann's React integration also supports RPC actions through the `useCrannState` hook:
+Crann uses structured storage keys: `crann:{name}:v{version}:{key}`
 
-```tsx
-// MyReactComponent.tsx
-import React, { useState } from "react";
-import { createCrannStateHook } from "crann";
-import { config } from "./config";
+This prevents collisions and enables clean migrations.
 
-// Create a custom hook for your config
-const useCrannState = createCrannStateHook(config);
-
-function CounterComponent() {
-  const { useStateItem, callAction } = useCrannState();
-  const [counter, setCounter] = useStateItem("counter");
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [currentTime, setCurrentTime] = useState<string | null>(null);
-
-  const handleIncrement = async () => {
-    setIsLoading(true);
-    setError(null);
-
-    try {
-      // Call the increment action defined in the service worker
-      const result = await callAction("increment", 1);
-      // Note: The state will be automatically updated through the subscription,
-      // but you can also use the result directly if needed
-      console.log("Counter incremented to:", result.counter);
-    } catch (err) {
-      setError(err.message);
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  const fetchCurrentTime = async () => {
-    setIsLoading(true);
-    setError(null);
-
-    try {
-      const result = await callAction("getCurrentTime");
-      setCurrentTime(result.time);
-    } catch (err) {
-      setError(err.message);
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  return (
-    <div>
-      <h2>Counter: {counter}</h2>
-
-      <button onClick={handleIncrement} disabled={isLoading}>
-        {isLoading ? "Incrementing..." : "Increment Counter"}
-      </button>
-
-      <button onClick={fetchCurrentTime} disabled={isLoading}>
-        {isLoading ? "Fetching..." : "Get Current Time"}
-      </button>
-
-      {currentTime && <p>Current time: {currentTime}</p>}
-      {error && <p className="error">Error: {error}</p>}
-    </div>
-  );
-}
+## Migration from v1
 
-export default CounterComponent;
-```
+### Key Changes
 
-#### Key Benefits of RPC Actions
+| v1                        | v2                        |
+| ------------------------- | ------------------------- |
+| `create()`                | `createStore()`           |
+| `connect()`               | `connectStore()`          |
+| `Partition.Instance`      | `Scope.Agent`             |
+| `Partition.Service`       | `Scope.Shared`            |
+| `crann.set()`             | `store.setState()`        |
+| `crann.get()`             | `store.getState()`        |
+| `callAction("name", arg)` | `agent.actions.name(arg)` |
+| Config object literal     | `createConfig()`          |
 
-1. **Type Safety**: Full TypeScript support for action parameters and return values
-2. **Validation**: Optional validation of action parameters before execution
-3. **Service Worker Context**: Actions run in the service worker where they have access to all extension APIs
-4. **Automatic State Updates**: Actions can return state updates that are automatically synchronized
-5. **Error Handling**: Proper error propagation from service worker to calling context
-6. **Unified API**: Same pattern works across all contexts (content scripts, popups, React components)
-7. **Simplified Architecture**: Centralize complex operations in the service worker
+### Migration Steps
 
-### React Integration
-
-Crann provides a custom React hook for easy integration with React applications. This is particularly useful when you have a React app running in an iframe injected by your content script.
+1. **Update config to use `createConfig()`:**
 
 ```typescript
-// In your React component
-import { useCrann } from "crann";
-
-function MyReactComponent() {
-  // The hook returns the same interface as connect()
-  const { get, set, subscribe } = useCrann();
-
-  // Get the current state
-  const { isEnabled, count } = get();
+// Before (v1)
+const crann = create({
+  count: { default: 0 },
+});
 
-  // Set state (triggers re-render)
-  const toggleEnabled = () => {
-    set({ isEnabled: !isEnabled });
-  };
+// After (v2)
+const config = createConfig({
+  name: "myStore", // Required in v2
+  count: { default: 0 },
+});
 
-  // Subscribe to specific state changes
-  subscribe(
-    (changes) => {
-      console.log("Count changed:", changes.count);
-    },
-    ["count"]
-  );
-
-  return (
-    <div>
-      <button onClick={toggleEnabled}>
-        {isEnabled ? "Disable" : "Enable"}
-      </button>
-      <p>Count: {count}</p>
-    </div>
-  );
-}
+const store = createStore(config);
 ```
 
-The `useCrann` hook provides the same functionality as `connect()`, but with React-specific optimizations:
+2. **Update terminology:**
 
-- Automatically re-renders components when subscribed state changes
-- Handles cleanup of subscriptions when components unmount
-- Provides TypeScript support for your state types
+```typescript
+// Before (v1)
+partition: Partition.Instance;
 
-#### Using with TypeScript
+// After (v2)
+scope: Scope.Agent;
+```
 
-For better type safety, you can create a custom hook that includes your state types:
+3. **Update React hooks:**
 
 ```typescript
-// types.ts
-interface MyState {
-  isEnabled: boolean;
-  count: number;
-  user: {
-    name: string;
-    age: number;
-  } | null;
-}
-
-// hooks.ts
+// Before (v1)
 import { useCrann } from "crann";
-import type { MyState } from "./types";
-
-export function useMyCrann() {
-  return useCrann<MyState>();
-}
-
-// MyComponent.tsx
-import { useMyCrann } from "./hooks";
+const { get, set, callAction } = useCrann();
 
-function MyComponent() {
-  const { get, set } = useMyCrann();
-
-  // TypeScript now knows the shape of your state
-  const { user } = get();
-
-  const updateUser = () => {
-    set({
-      user: {
-        name: "Alice",
-        age: 30,
-      },
-    });
-  };
-
-  return (
-    <div>
-      {user && <p>Hello, {user.name}!</p>}
-      <button onClick={updateUser}>Update User</button>
-    </div>
-  );
-}
+// After (v2)
+import { createCrannHooks } from "crann/react";
+const { useCrannState, useCrannActions } = createCrannHooks(config);
 ```
 
-#### Performance Considerations
-
-The `useCrann` hook is optimized for React usage:
-
-- Only re-renders when subscribed state actually changes
-- Batches multiple state updates to minimize re-renders
-- Automatically cleans up subscriptions on unmount
-- Supports selective subscription to specific state keys
-
-For best performance:
-
-1. Subscribe only to the state keys your component needs
-2. Use the second parameter of `subscribe` to specify which keys to listen for
-3. Consider using `useMemo` for derived state
-4. Use `useCallback` for event handlers that update state
+4. **Update action calls:**
 
 ```typescript
-function OptimizedComponent() {
-  const { get, set, subscribe } = useCrann();
-  const { items, filter } = get();
-
-  // Only re-render when items or filter changes
-  const filteredItems = useMemo(() => {
-    return items.filter((item) => item.includes(filter));
-  }, [items, filter]);
-
-  // Memoize the handler
-  const handleFilterChange = useCallback(
-    (newFilter: string) => {
-      set({ filter: newFilter });
-    },
-    [set]
-  );
+// Before (v1)
+await callAction("increment", 5);
 
-  // Only subscribe to the keys we care about
-  subscribe(
-    (changes) => {
-      console.log("Filter changed:", changes.filter);
-    },
-    ["filter"]
-  );
-
-  return (
-    <div>
-      <input
-        value={filter}
-        onChange={(e) => handleFilterChange(e.target.value)}
-      />
-      <ul>
-        {filteredItems.map((item) => (
-          <li key={item}>{item}</li>
-        ))}
-      </ul>
-    </div>
-  );
-}
+// After (v2)
+await agent.actions.increment(5);
 ```
 
-## What Was The Problem?
-
-Browser extensions often have multiple components:
+## Why Crann?
 
-- **Service Worker:** A background script handling core logic and events.
-- **Content Scripts:** JavaScript injected directly into web pages.
-- **Popup:** A small window shown when clicking the extension icon.
-- **Side Panels, DevTools Pages:** Other specialized UI or inspection contexts.
+Browser extensions have multiple isolated contexts (content scripts, popup, devtools, sidepanel) that need to share state. The traditional approach using `sendMessage`/`onMessage` forces a painful pattern:
 
-These components run in isolated environments. Sharing data or coordinating actions between them traditionally requires manually sending messages back and forth using APIs like `chrome.runtime.sendMessage` and setting up listeners (`chrome.runtime.onMessage`). This can quickly lead to complex, hard-to-debug "spaghetti code" as your extension grows.
+[![Message Router Problem](https://mermaid.ink/img/pako:eNp9k2tvmzAUhv-KZSlikyjCEBLgwyJK2FapbSJwVbVhihi4BDXYyJi2WZT_PodcmtvmT4f3PK998DlewpRlBLqw01kWtBAuWCpiRkqiuEDJEv6qrFadTkxf5uw9nSVcgNswpkCuuvmd86SaAS8nVNSTGLYB8BkV5EPUMfy1AdfLj9CkTUggSnlRCYCO0sZp2jhIj0eTMaua6kAa4smQvAnG5vVWJTSL6Ulp0aMsKyL8rUgJeGT8lfCjsrKCk1QUjAJ8_amGowcchNJ5R-o6yQkIWSNOnJ_RwWE32P8pbfV7IdLZl7LONbGoyNcj47-PbS8CSX-a1AQoPwI8jbCHA-XM7xt7KvoPZe6pMLj1nqZ4NMXe9QWwuwe_B_IXpkMPexcwa489REE49Xx8M7q_wPUkp2naeeJ-t8FgMDjKtr07aaIcGXB19W3bjZ1mnGnj0Zk0xGfSJm7lTZ-gCkvCy6TI5PAv11AM28GPoSvD9ejHMKYrySWNYNGCptAVvCEq5KzJZ9B9Sea1_GqqLBFkWCRyCsq9WiX0mbFyZ5Gf0F3CD-gamqMjByHLNsyurfdtU4UL6CK9r3Wdfh_pes80bKuPVir80-6ga47joC6ykWEaXcswbRXmfF339iwub41wnzVUQLdnWSokWSEYv9u87PaBr_4CI3YYvA?type=png)](https://mermaid.live/edit#pako:eNp9k2tvmzAUhv-KZSlikyjCEBLgwyJK2FapbSJwVbVhihi4BDXYyJi2WZT_PodcmtvmT4f3PK998DlewpRlBLqw01kWtBAuWCpiRkqiuEDJEv6qrFadTkxf5uw9nSVcgNswpkCuuvmd86SaAS8nVNSTGLYB8BkV5EPUMfy1AdfLj9CkTUggSnlRCYCO0sZp2jhIj0eTMaua6kAa4smQvAnG5vVWJTSL6Ulp0aMsKyL8rUgJeGT8lfCjsrKCk1QUjAJ8_amGowcchNJ5R-o6yQkIWSNOnJ_RwWE32P8pbfV7IdLZl7LONbGoyNcj47-PbS8CSX-a1AQoPwI8jbCHA-XM7xt7KvoPZe6pMLj1nqZ4NMXe9QWwuwe_B_IXpkMPexcwa489REE49Xx8M7q_wPUkp2naeeJ-t8FgMDjKtr07aaIcGXB19W3bjZ1mnGnj0Zk0xGfSJm7lTZ-gCkvCy6TI5PAv11AM28GPoSvD9ejHMKYrySWNYNGCptAVvCEq5KzJZ9B9Sea1_GqqLBFkWCRyCsq9WiX0mbFyZ5Gf0F3CD-gamqMjByHLNsyurfdtU4UL6CK9r3Wdfh_pes80bKuPVir80-6ga47joC6ykWEaXcswbRXmfF339iwub41wnzVUQLdnWSokWSEYv9u87PaBr_4CI3YYvA)
 
-## Why Is This Better: How Crann Simplifies Synchronization
+**The problem with `sendMessage` / `onMessage`:**
 
-Crann acts as a central state management hub, typically initialized in your service worker. It provides a single source of truth for your shared data. Other contexts connect to this hub, allowing them to easily read state, update it, and subscribe to changes.
+- Agents can't message each other directly—everything routes through the service worker
+- Your service worker becomes a message router with growing `switch/case` statements
+- Every new feature means more message types, more handlers, more coupling
+- Manual async handling (`return true` in Chrome, different in Firefox)
+- Hand-rolled TypeScript types that may or may not stay in sync
 
-**Visualizing the Problem: Manual Message Passing vs. Crann's Centralized State**
+**With Crann:**
 
-![with_messages](img/with_messages.png)
-_Traditional message passing requires complex, bidirectional communication between all parts._
+- Define your state and actions in one place
+- Agents sync automatically through the central store
+- Full TypeScript inference—no manual type definitions
+- No message routing, no relay logic, no `return true`
+- Focus on your features, not the plumbing
 
-![with_crann](img/with_crann.png)
-_Crann's centralized state management simplifies the architecture by eliminating the need for manual message passing._
+---
 
-This dramatically simplifies your architecture:
+**License:** ISC
 
-- **No more manual messaging:** Crann handles the communication internally.
-- **Single source of truth:** State is managed centrally.
-- **Reactivity:** Components automatically react to state changes they care about.
+**Repository:** [github.com/moclei/crann](https://github.com/moclei/crann)