@livestore/livestore 0.4.0-dev.21 → 0.4.0-dev.22

package/docs/patterns/auth/index.md

@@ -10,31 +10,43 @@ Use the `syncPayload` store option to send a custom payload to your sync backend
 
 The following example sends the authenticated user's JWT to the server.
 
-## `patterns/auth/live-store-provider.tsx`
+## `patterns/auth/store-with-auth.tsx`
 
-```tsx filename="patterns/auth/live-store-provider.tsx"
+```tsx filename="patterns/auth/store-with-auth.tsx"
 
-const schema = {} as Parameters<typeof LiveStoreProvider>[0]['schema']
+const schema = {} as LiveStoreSchema
 const storeId = 'demo-store'
 const user = { jwt: 'user-token' }
-const children: ReactNode = null
 const adapter = makeInMemoryAdapter()
 
 // ---cut---
-export const AuthenticatedProvider = () => (
-  <LiveStoreProvider
-    schema={schema}
-    storeId={storeId}
-    adapter={adapter}
-    batchUpdates={batchUpdates}
-    syncPayload={{
+const useAppStore = () =>
+  useStore({
+    storeId,
+    schema,
+    adapter,
+    batchUpdates,
+    syncPayload: {
       authToken: user.jwt, // Using a JWT
-    }}
-  >
-    {/* ... */}
-    {children}
-  </LiveStoreProvider>
-)
+    },
+  })
+
+export const App = () => {
+  const [storeRegistry] = useState(() => new StoreRegistry())
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <StoreRegistryProvider storeRegistry={storeRegistry}>
+        <AppContent />
+      </StoreRegistryProvider>
+    </Suspense>
+  )
+}
+
+const AppContent = () => {
+  const _store = useAppStore()
+  // Use the store in your components
+  return <div>{/* Your app content */}</div>
+}
 ```
 
 On the sync server, validate the token and allow or reject the sync based on the result. See the following example:
@@ -184,6 +196,133 @@ export const verifyJwt = (token: string): Claims => {
 
 You can extend `ensureAuthorized` to project additional claims, memoise verification per `authToken`, or enforce application-specific policies without changing LiveStore internals.
 
+## Cookie-based authentication
+
+If you prefer cookie-based authentication (e.g., with [better-auth](https://www.better-auth.com/)), you can forward HTTP headers to your `onPush` and `onPull` callbacks using the `forwardHeaders` option.
+
+### Why forward headers?
+
+Passing tokens in URL parameters (`syncPayload`) exposes them in browser history, server logs, and referrer headers. Cookie-based auth avoids these issues since cookies are sent automatically with each request and aren't logged in URLs.
+
+### Example
+
+The following example forwards `Cookie` and `Authorization` headers to the Durable Object callbacks:
+
+## `patterns/auth/cookie-auth.ts`
+
+```ts filename="patterns/auth/cookie-auth.ts"
+
+export class SyncBackendDO extends makeDurableObject({
+  // Forward Cookie and Authorization headers to onPush/onPull callbacks
+  forwardHeaders: ['Cookie', 'Authorization'],
+
+  onPush: async (message, context) => {
+    const { storeId, headers } = context
+
+    // Access forwarded headers in callbacks
+    const cookie = headers?.get('cookie')
+    const _authorization = headers?.get('authorization')
+
+    if (cookie) {
+      // Parse session from cookie (example with better-auth)
+      const sessionToken = parseCookie(cookie, 'session_token')
+      const session = await getSessionFromToken(sessionToken)
+
+      if (!session) {
+        throw new Error('Invalid session')
+      }
+
+      console.log('Push from user:', session.userId, 'store:', storeId)
+    }
+
+    console.log('onPush', message.batch)
+  },
+
+  onPull: async (message, context) => {
+    const { storeId, headers } = context
+
+    // Same header access in onPull
+    const cookie = headers?.get('cookie')
+
+    if (cookie) {
+      const sessionToken = parseCookie(cookie, 'session_token')
+      const session = await getSessionFromToken(sessionToken)
+
+      if (!session) {
+        throw new Error('Invalid session')
+      }
+
+      console.log('Pull from user:', session.userId, 'store:', storeId)
+    }
+
+    console.log('onPull', message)
+  },
+}) {}
+
+export default makeWorker({
+  syncBackendBinding: 'SYNC_BACKEND_DO',
+  // Optional: validate at worker level using headers
+  validatePayload: async (_payload, context) => {
+    const { headers } = context
+    const cookie = headers.get('cookie')
+
+    if (cookie) {
+      const sessionToken = parseCookie(cookie, 'session_token')
+      const session = await getSessionFromToken(sessionToken)
+
+      if (!session) {
+        throw new Error('Unauthorized: Invalid session')
+      }
+    }
+  },
+  enableCORS: true,
+})
+
+// --- Helper functions (implement based on your auth library) ---
+
+function parseCookie(cookieHeader: string, name: string): string | undefined {
+  const cookies = cookieHeader.split(';').map((c) => c.trim())
+  for (const cookie of cookies) {
+    const [key, value] = cookie.split('=')
+    if (key === name) return value
+  }
+  return undefined
+}
+
+interface Session {
+  userId: string
+  email: string
+}
+
+async function getSessionFromToken(_token: string | undefined): Promise<Session | null> {
+  // Implement session lookup using your auth library
+  // Example with better-auth:
+  // return await auth.api.getSession({ headers: { cookie: `session_token=${token}` } })
+  return { userId: 'user-123', email: 'user@example.com' }
+}
+```
+
+### How it works
+
+1. **Configure `forwardHeaders`** in `makeDurableObject()` to specify which headers to forward.
+2. **Headers are stored** in the WebSocket attachment during connection upgrade, surviving hibernation.
+3. **Access headers** via `context.headers` in `onPush` and `onPull` callbacks.
+4. **Worker-level validation** can also access headers via `context.headers` in `validatePayload`.
+
+### Custom header extraction
+
+For more control, pass a function to `forwardHeaders`:
+
+```typescript
+export class SyncBackendDO extends makeDurableObject({
+  forwardHeaders: (request) => ({
+    'x-user-id': request.headers.get('x-user-id') ?? '',
+    'x-session': request.headers.get('cookie')?.split('session=')[1]?.split(';')[0] ?? '',
+  }),
+  // ...
+}) {}
+```
+
 ## Client identity vs user identity
 
 LiveStore's `clientId` identifies a client instance, while user identity is an application-level concern that must be modeled through your application's events and logic.
@@ -196,31 +335,43 @@ LiveStore's `clientId` identifies a client instance, while user identity is an a
 
 The `syncPayload` is primarily intended for authentication purposes:
 
-## `patterns/auth/live-store-provider.tsx`
+## `patterns/auth/store-with-auth.tsx`
 
-```tsx filename="patterns/auth/live-store-provider.tsx"
+```tsx filename="patterns/auth/store-with-auth.tsx"
 
-const schema = {} as Parameters<typeof LiveStoreProvider>[0]['schema']
+const schema = {} as LiveStoreSchema
 const storeId = 'demo-store'
 const user = { jwt: 'user-token' }
-const children: ReactNode = null
 const adapter = makeInMemoryAdapter()
 
 // ---cut---
-export const AuthenticatedProvider = () => (
-  <LiveStoreProvider
-    schema={schema}
-    storeId={storeId}
-    adapter={adapter}
-    batchUpdates={batchUpdates}
-    syncPayload={{
+const useAppStore = () =>
+  useStore({
+    storeId,
+    schema,
+    adapter,
+    batchUpdates,
+    syncPayload: {
       authToken: user.jwt, // Using a JWT
-    }}
-  >
-    {/* ... */}
-    {children}
-  </LiveStoreProvider>
-)
+    },
+  })
+
+export const App = () => {
+  const [storeRegistry] = useState(() => new StoreRegistry())
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <StoreRegistryProvider storeRegistry={storeRegistry}>
+        <AppContent />
+      </StoreRegistryProvider>
+    </Suspense>
+  )
+}
+
+const AppContent = () => {
+  const _store = useAppStore()
+  // Use the store in your components
+  return <div>{/* Your app content */}</div>
+}
 ```
 
 User identification and semantic data (like user IDs) should typically be handled through your event payloads and application state rather than relying solely on the sync payload.

package/docs/patterns/effect/index.md

@@ -2,6 +2,16 @@
 
 LiveStore itself is built on top of [Effect](https://effect.website) which is a powerful library to write production-grade TypeScript code. It's also possible (and recommended) to use Effect directly in your application code.
 
+## Store context for Effect
+
+For applications built with Effect, LiveStore provides `makeStoreContext()` - a factory that creates typed store contexts for the Effect layer system. This preserves your schema types through Effect's dependency injection and supports multiple stores.
+
+See the [Store Effect integration](/building-with-livestore/store#effect-integration) section for details on:
+- Creating typed store contexts
+- Using stores in Effect services
+- Layer composition patterns
+- Multiple stores in the same app
+
 ## Schema
 
 LiveStore uses the [Effect Schema](https://effect.website/docs/schema/introduction/) library to define schemas for the following:
@@ -430,7 +440,7 @@ export const pendingUsersAtom = Atom.make<PendingUser[]>([])
 
 ### Using queries in React components
 
-Access query results in React components with the `useAtomValue` hook. When using `StoreTag.makeQuery` (non-unsafe API), the result is wrapped in a Result type for proper loading and error handling:
+Access query results in React components with the `useAtomValue()` hook. When using `StoreTag.makeQuery` (non-unsafe API), the result is wrapped in a Result type for proper loading and error handling:
 
 ## `patterns/effect/store-setup/user-list.tsx`
 

package/docs/patterns/storybook/index.md

@@ -20,7 +20,7 @@ export const WithInitialText: Story = {
     ])
   ],
 }`,
-  
+
   storybookPreview: `import React from 'react'
 
 // Default decorator with no seed data
@@ -28,40 +28,57 @@ const LiveStoreDecorator = createLiveStoreDecorator()
 
 export const decorators = [LiveStoreDecorator]`,
 
-  decorator: `import React from 'react'
+  decorator: `import React, { Suspense, useState } from 'react'
+
+const adapter = makeInMemoryAdapter()
 
 // Create LiveStore decorator with optional seeding
 export const createLiveStoreDecorator = (seedEvents = []) => (Story) => {
-  const onBoot = (store) => {
-    // Seed data through events during boot
-    if (seedEvents.length > 0) {
-      store.commit(...seedEvents)
-    }
-  }
+  const [storeRegistry] = useState(() => new StoreRegistry())
 
   return (
-    <LiveStoreProvider
-      schema={schema}
-      adapter={makeInMemoryAdapter()}
-      batchUpdates={batchUpdates}
-      boot={onBoot}
-      renderLoading={(status) => <div>Loading LiveStore ({status.stage})...</div>}
-    >
-      <Story />
-    </LiveStoreProvider>
+    <Suspense fallback={<div>Loading LiveStore...</div>}>
+      <StoreRegistryProvider storeRegistry={storeRegistry}>
+        <StoryWithStore Story={Story} seedEvents={seedEvents} />
+      </StoreRegistryProvider>
+    </Suspense>
   )
+}
+
+const StoryWithStore = ({ Story, seedEvents }) => {
+  const store = useStore({
+    storeId: 'storybook',
+    schema,
+    adapter,
+    batchUpdates,
+    boot: (store) => {
+      if (seedEvents.length > 0) {
+        store.commit(...seedEvents)
+      }
+    },
+  })
+  return <Story />
 }`,
 
-  todoInput: `import React from 'react'
+  todoInput: `import { useStore } from '@livestore/react'
+
+const adapter = makeInMemoryAdapter()
 
 // Define queries (like in TodoMVC)
 const uiState$ = queryDb(tables.uiState.get(), { label: 'uiState' })
 
+const useAppStore = () => useStore({
+  storeId: 'todo-app',
+  schema,
+  adapter,
+  batchUpdates,
+})
+
 export const TodoInput = () => {
-  const { store } = useStore()
+  const store = useAppStore()
   const { newTodoText } = store.useQuery(uiState$)
 
-  const updateNewTodoText = (text: string) => 
+  const updateNewTodoText = (text: string) =>
     store.commit(events.uiStateSet({ newTodoText: text }))
 
   const createTodo = () => {
@@ -110,13 +127,13 @@ export const tables = {
   // Client document for UI state
   uiState: State.SQLite.clientDocument({
     name: 'uiState',
-    schema: Schema.Struct({ 
-      newTodoText: Schema.String, 
-      filter: Schema.Literal('all', 'active', 'completed') 
+    schema: Schema.Struct({
+      newTodoText: Schema.String,
+      filter: Schema.Literal('all', 'active', 'completed')
     }),
-    default: { 
-      id: SessionIdSymbol, 
-      value: { newTodoText: '', filter: 'all' } 
+    default: {
+      id: SessionIdSymbol,
+      value: { newTodoText: '', filter: 'all' }
     },
   }),
 }

package/docs/platform-adapters/expo-adapter/index.md

@@ -31,7 +31,7 @@ For a complete setup including sync and devtools, see the [Expo getting started
 
 ## Basic Usage
 
-Create an adapter and wrap your app with the `LiveStoreProvider`:
+Create an adapter and a custom `useAppStore()` hook, then set up a `StoreRegistry` with `<StoreRegistryProvider>`:
 
 ## `reference/platform-adapters/expo-adapter/usage.tsx`
 
@@ -39,27 +39,39 @@ Create an adapter and wrap your app with the `LiveStoreProvider`:
 
 const adapter = makePersistedAdapter()
 
-export const App = () => (
-  <SafeAreaView style={{ flex: 1 }}>
-    <LiveStoreProvider
-      schema={schema}
-      adapter={adapter}
-      storeId="my-app"
-      batchUpdates={batchUpdates}
-      renderLoading={(status) => <Text>Loading ({status.stage})...</Text>}
-      renderError={(error) => <Text>Error: {String(error)}</Text>}
-    >
-      {/* Your app content */}
-    </LiveStoreProvider>
-  </SafeAreaView>
-)
+const useAppStore = () =>
+  useStore({
+    storeId: 'my-app',
+    schema,
+    adapter,
+    batchUpdates,
+  })
+
+export const App = () => {
+  const [storeRegistry] = useState(() => new StoreRegistry())
+  return (
+    <SafeAreaView style={{ flex: 1 }}>
+      <Suspense fallback={<Text>Loading...</Text>}>
+        <StoreRegistryProvider storeRegistry={storeRegistry}>
+          <TodoList />
+        </StoreRegistryProvider>
+      </Suspense>
+    </SafeAreaView>
+  )
+}
+
+const TodoList = () => {
+  const store = useAppStore()
+  const todos = store.useQuery(queryDb(tables.todos.select()))
+  return <Text>{todos.length} todos</Text>
+}
 ```
 
 ### `reference/platform-adapters/expo-adapter/schema.ts`
 
 ```ts filename="reference/platform-adapters/expo-adapter/schema.ts"
 
-const tables = {
+export const tables = {
   todos: State.SQLite.table({
     name: 'todos',
     columns: {
@@ -88,7 +100,7 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
-The adapter requires minimal configuration. For more details on the provider props, see the [React integration guide](/framework-integrations/react-integration).
+For more details on the registry, and hooks, see the [React integration guide](/framework-integrations/react-integration).
 
 ## Configuration Options
 
@@ -99,7 +111,11 @@ The adapter requires minimal configuration. For more details on the provider pro
 // ---cut---
 
 const adapter = makePersistedAdapter({
-  storage: { subDirectory: 'my-app' },
+  storage: {
+    // Optional: custom base directory (defaults to expo-sqlite's default)
+    // directory: '/custom/path/to/databases',
+    subDirectory: 'my-app',
+  },
 })
 ```
 
@@ -107,7 +123,8 @@ const adapter = makePersistedAdapter({
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `storage.subDirectory` | `string` | Subdirectory within the default SQLite location for organizing databases |
+| `storage.directory` | `string` | Base directory for database files (defaults to `expo-sqlite`'s default directory) |
+| `storage.subDirectory` | `string` | Subdirectory relative to `directory` for organizing databases |
 | `sync` | `SyncOptions` | Sync backend configuration (see [Syncing](/building-with-livestore/syncing)) |
 | `clientId` | `string` | Custom client identifier (defaults to device ID) |
 | `sessionId` | `string` | Session identifier (defaults to `'static'`) |

package/docs/platform-adapters/web-adapter/index.md

@@ -149,6 +149,43 @@ During development (`NODE_ENV !== 'production'`), LiveStore automatically copies
 
 LiveStore also uses `window.sessionStorage` to retain the identity of a client session (e.g. tab/window) across reloads.
 
+### Private browsing mode
+
+In Safari and Firefox private browsing mode, OPFS is not available due to browser restrictions. When this happens, LiveStore automatically falls back to in-memory storage. This means:
+
+- The app will continue to work normally during the session
+- Data will not persist across page reloads or tab closures
+- Sync functionality (if configured) will still work
+
+You can detect when the store is running in-memory mode using `store.storageMode`:
+
+```tsx
+if (store.storageMode === 'in-memory') {
+  // Show a warning to the user
+  showToast('Data will not be saved in private browsing mode')
+}
+```
+
+The `storageMode` property returns:
+- `'persisted'`: Data is being persisted to disk (e.g., via OPFS)
+- `'in-memory'`: Data is only stored in memory and will be lost on page refresh
+
+You can also listen for boot status events including warnings using the `onBootStatus` callback in your store options:
+
+```ts
+const useAppStore = () => useStore({
+  storeId: 'app',
+  schema,
+  adapter,
+  batchUpdates: ReactDOM.unstable_batchedUpdates,
+  onBootStatus: (status) => {
+    if (status.stage === 'warning') {
+      console.warn(`Storage warning (${status.reason}): ${status.message}`)
+    }
+  },
+})
+```
+
 ### Resetting local persistence
 
 Resetting local persistence only clears data stored in the browser and does not affect any connected sync backend.
@@ -201,8 +238,40 @@ Assuming the web adapter in a multi-client, multi-tab browser application, a dia
 
 ## Browser support
 
-- Notable required browser APIs: OPFS, SharedWorker, `navigator.locks`, WASM
-- The web adapter of LiveStore currently doesn't work on Android browsers as they don't support the `SharedWorker` API (see [Chromium bug](https://issues.chromium.org/issues/40290702)).
+- Notable required browser APIs: OPFS, `navigator.locks`, WASM
+- SharedWorker is used for multi-tab synchronization but is not strictly required
+
+### Android Chrome (Single-tab mode)
+
+Android Chrome does not support the `SharedWorker` API ([Chromium bug #40290702](https://issues.chromium.org/issues/40290702)). When running on Android Chrome, LiveStore automatically falls back to **single-tab mode**:
+
+- Each browser tab runs independently with its own leader worker
+- Data is still persisted to OPFS (same as full mode)
+- Multi-tab synchronization is not available
+- Devtools are not supported in single-tab mode
+- A warning is logged to the console when this fallback occurs
+
+You can also explicitly use single-tab mode if you don't need multi-tab support:
+
+## `reference/platform-adapters/web-adapter/single-tab.ts`
+
+```ts filename="reference/platform-adapters/web-adapter/single-tab.ts"
+/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline adapter */
+// ---cut---
+
+// Use this only if you specifically need single-tab mode.
+// Prefer makePersistedAdapter which auto-detects SharedWorker support.
+const adapter = makeSingleTabAdapter({
+  worker: LiveStoreWorker,
+  storage: { type: 'opfs' },
+})
+```
+
+:::note
+The single-tab adapter is intended as a fallback for browsers without SharedWorker support.
+We plan to remove it once SharedWorker is supported in Android Chrome.
+Track progress: [LiveStore #321](https://github.com/livestorejs/livestore/issues/321)
+:::
 
 ## Best practices
 

package/docs/tutorial/1-setup-starter-project/index.md

@@ -25,7 +25,7 @@ Once you've downloaded the project, you can navigate to the project directory an
 The project currently is set up as follows:
 - Minimal project created via [`vite create`](https://vite.dev/guide/#scaffolding-your-first-vite-project) using React and TypeScript.
 - Using [Tailwind CSS](https://tailwindcss.com/) for styling.
-- Has basic functionality for adding and deleting todos via local [`React.useState`](https://react.dev/learn/state-a-components-memory).
+- Has basic functionality for adding and deleting todos via local [`React.useState()`](https://react.dev/learn/state-a-components-memory).
 
 ## Understand the current project state
 
@@ -80,8 +80,8 @@ function App() {
 
   return (
     // Render input text field and todo list ...
-    // ... and invoke `addTodo` and `deleteTodo` 
-    // ... when the buttons are clicked. 
+    // ... and invoke `addTodo` and `deleteTodo`
+    // ... when the buttons are clicked.
   )
 }
 ```
@@ -98,8 +98,8 @@ The "problem" with this code is that the todo items are not _persisted_, meaning
 - the page is refreshed in the browser.
 - the development server is restarted.
 
-In the next chapters, you'll learn how to persist the todos in the list, so that they'll "survive" both actions. 
+In the next chapters, you'll learn how to persist the todos in the list, so that they'll "survive" both actions.
 
-Even more: They will not only persist, they will automatically sync across multiple browsers tabs/windows, and even across devices—without you needing to think about the syncing logic and managing remote state. 
+Even more: They will not only persist, they will automatically sync across multiple browsers tabs/windows, and even across devices—without you needing to think about the syncing logic and managing remote state.
 
 That's the power of LiveStore!