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

package/docs/framework-integrations/react-integration/index.md

@@ -1,918 +0,0 @@
-# React integration for LiveStore
-
-While LiveStore is framework agnostic, the `@livestore/react` package provides a first-class integration with React.
-
-## Features
-
-- High performance
-- Fine-grained reactivity (using LiveStore's signals-based reactivity system)
-- Instant, synchronous query results (without the need for `useEffect` and `isLoading` checks)
-- Transactional state transitions (via `batchUpdates`)
-- Also supports Expo / React Native via `@livestore/adapter-expo`
-
-## API
-
-### `LiveStoreProvider`
-
-In order to use LiveStore with React, you need to wrap your application in a `LiveStoreProvider`.
-
-## `reference/framework-integrations/react/provider.tsx`
-
-```tsx filename="reference/framework-integrations/react/provider.tsx"
-
-const adapter = makeInMemoryAdapter()
-
-export const Root: FC<{ children: ReactNode }> = ({ children }) => (
-  <LiveStoreProvider schema={schema} adapter={adapter} batchUpdates={batchUpdates}>
-    {children}
-  </LiveStoreProvider>
-)
-```
-
-### `reference/framework-integrations/react/schema.ts`
-
-```ts filename="reference/framework-integrations/react/schema.ts"
-
-export const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-  uiState: State.SQLite.clientDocument({
-    name: 'UiState',
-    schema: Schema.Struct({ text: Schema.String }),
-    default: { value: { text: '' } },
-  }),
-} as const
-
-export const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-} as const
-
-const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
-    tables.todos.insert({ id, text, completed: false }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-#### Logging
-
-`LiveStoreProvider` accepts optional logging configuration:
-
-```tsx
-
-<LiveStoreProvider
-  schema={schema}
-  adapter={adapter}
-  batchUpdates={batchUpdates}
-  // Optional: swap the logger implementation
-  logger={Logger.prettyWithThread('app')}
-  // Optional: set minimum log level (use LogLevel.None to disable)
-  logLevel={LogLevel.Info}
->
-  <App />
-</LiveStoreProvider>
-```
-
-For scenarios where you have an existing store instance, you can manually create a `LiveStoreContext.Provider`:
-
-## `reference/framework-integrations/react/context-provider.tsx`
-
-```tsx filename="reference/framework-integrations/react/context-provider.tsx"
-
-declare const store: Store & ReactApi
-
-export const Root: FC<{ children: ReactNode }> = ({ children }) => (
-  <LiveStoreContext.Provider value={{ stage: 'running', store }}>{children}</LiveStoreContext.Provider>
-)
-```
-
-### useStore
-
-## `reference/framework-integrations/react/use-store.tsx`
-
-```tsx filename="reference/framework-integrations/react/use-store.tsx"
-
-export const MyComponent: FC = () => {
-  const { store } = useStore()
-
-  useEffect(() => {
-    store.commit(events.todoCreated({ id: '1', text: 'Hello, world!' }))
-  }, [store])
-
-  return <div>...</div>
-}
-```
-
-### `reference/framework-integrations/react/schema.ts`
-
-```ts filename="reference/framework-integrations/react/schema.ts"
-
-export const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-  uiState: State.SQLite.clientDocument({
-    name: 'UiState',
-    schema: Schema.Struct({ text: Schema.String }),
-    default: { value: { text: '' } },
-  }),
-} as const
-
-export const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-} as const
-
-const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
-    tables.todos.insert({ id, text, completed: false }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-### useQuery
-
-## `reference/framework-integrations/react/use-query.tsx`
-
-```tsx filename="reference/framework-integrations/react/use-query.tsx"
-
-const query$ = queryDb(tables.todos.where({ completed: true }).orderBy('id', 'desc'), {
-  label: 'completedTodos',
-})
-
-export const CompletedTodos: FC = () => {
-  const { store } = useStore()
-  const todos = store.useQuery(query$)
-
-  return (
-    <div>
-      {todos.map((todo) => (
-        <div key={todo.id}>{todo.text}</div>
-      ))}
-    </div>
-  )
-}
-```
-
-### `reference/framework-integrations/react/schema.ts`
-
-```ts filename="reference/framework-integrations/react/schema.ts"
-
-export const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-  uiState: State.SQLite.clientDocument({
-    name: 'UiState',
-    schema: Schema.Struct({ text: Schema.String }),
-    default: { value: { text: '' } },
-  }),
-} as const
-
-export const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-} as const
-
-const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
-    tables.todos.insert({ id, text, completed: false }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-### useClientDocument
-
-## `reference/framework-integrations/react/use-client-document.tsx`
-
-```tsx filename="reference/framework-integrations/react/use-client-document.tsx"
-
-export const TodoItem: FC<{ id: string }> = ({ id }) => {
-  const { store } = useStore()
-  const [todo, updateTodo] = store.useClientDocument(tables.uiState, id)
-
-  return (
-    <button type="button" onClick={() => updateTodo({ text: 'Hello, world!' })}>
-      {todo.text}
-    </button>
-  )
-}
-```
-
-### `reference/framework-integrations/react/schema.ts`
-
-```ts filename="reference/framework-integrations/react/schema.ts"
-
-export const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-  uiState: State.SQLite.clientDocument({
-    name: 'UiState',
-    schema: Schema.Struct({ text: Schema.String }),
-    default: { value: { text: '' } },
-  }),
-} as const
-
-export const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-} as const
-
-const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
-    tables.todos.insert({ id, text, completed: false }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-## Usage with ...
-
-### Vite
-
-LiveStore works with Vite out of the box.
-
-### Tanstack Start
-
-LiveStore works with Tanstack Start out of the box.
-
-#### Notes
-
-When using LiveStore with TanStack Start, it's crucial to place `LiveStoreProvider` in the correct location to avoid remounting on navigation.
-
-:::warn
-**Do NOT place `LiveStoreProvider` inside `shellComponent`**. The `shellComponent` can be re-rendered on navigation, causing LiveStore to remount and show the loading screen on every page transition.
-:::
-
-#### Correct pattern
-
-Use the `component` prop on `createRootRoute` for `LiveStoreProvider`:
-
-```tsx
-
-export const Route = createRootRoute({
-  shellComponent: RootShell,    // HTML structure only - NO state or providers
-  component: RootComponent,      // App shell - LiveStoreProvider goes HERE
-})
-
-// HTML document shell - keep this stateless
-function RootShell({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <head><HeadContent /></head>
-      <body>
-        {children}
-        <Scripts />
-      </body>
-    </html>
-  )
-}
-
-// App shell - persists across SPA navigation
-function RootComponent() {
-  return (
-    <LiveStoreProvider 
-      schema={schema} 
-      adapter={adapter} 
-      batchUpdates={batchUpdates}
-    >
-      <Outlet />
-    </LiveStoreProvider>
-  )
-}
-```
-
-#### Why this matters
-
-TanStack Start's `shellComponent` is designed for SSR HTML streaming and may be re-evaluated on server requests during navigation. When `LiveStoreProvider` is placed there:
-
-- The WebSocket connection is re-established on each navigation
-- The "Loading LiveStore" screen appears
-- All LiveStore state is re-initialized
-
-The `component` prop creates a React component that stays mounted during client-side SPA navigation, preserving LiveStore's connection and state.
-
-#### Debugging
-
-If you see the loading screen on every navigation, check your server logs. Multiple "Launching WebSocket" messages indicate `LiveStoreProvider` is remounting incorrectly.
-
-### Expo / React Native
-
-LiveStore has a first-class integration with Expo / React Native via `@livestore/adapter-expo`.
-
-### Next.js
-
-Given various Next.js limitations, LiveStore doesn't yet work with Next.js out of the box.
-
-## Multi-Store
-
-The multi-store API enables managing multiple stores within a single React application. This is useful for:
-
-- **Partial data synchronization** - Load only the data you need, when you need it
-- **Multi-tenant applications** - Separate stores for each workspace, organization, or project (like Slack workspaces, Notion pages, or Linear teams)
-
-## `reference/framework-integrations/react/multi-store/minimal.tsx`
-
-```tsx filename="reference/framework-integrations/react/multi-store/minimal.tsx"
-
-const issueStoreOptions = (issueId: string) =>
-  storeOptions({
-    storeId: `issue-${issueId}`,
-    schema,
-    adapter: makeInMemoryAdapter(),
-  })
-
-export function App() {
-  const [registry] = useState(() => new StoreRegistry({ defaultOptions: { batchUpdates } }))
-  return (
-    <StoreRegistryProvider storeRegistry={registry}>
-      <IssueView />
-    </StoreRegistryProvider>
-  )
-}
-
-function IssueView() {
-  const store = useStore(issueStoreOptions('abc123'))
-  const [issue] = store.useQuery(queryDb(tables.issue.select()))
-  return <div>{issue?.title}</div>
-}
-```
-
-### `reference/framework-integrations/react/multi-store/schema.ts`
-
-```ts filename="reference/framework-integrations/react/multi-store/schema.ts"
-
-// Event definitions
-export const events = {
-  issueCreated: Events.synced({
-    name: 'v1.IssueCreated',
-    schema: Schema.Struct({
-      id: Schema.String,
-      title: Schema.String,
-      status: Schema.Literal('todo', 'done'),
-    }),
-  }),
-  issueStatusChanged: Events.synced({
-    name: 'v1.IssueStatusChanged',
-    schema: Schema.Struct({
-      id: Schema.String,
-      status: Schema.Literal('todo', 'done'),
-    }),
-  }),
-}
-
-// State definition
-export const tables = {
-  issue: State.SQLite.table({
-    name: 'issue',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      title: State.SQLite.text(),
-      status: State.SQLite.text(),
-    },
-  }),
-}
-
-const materializers = State.SQLite.materializers(events, {
-  'v1.IssueCreated': ({ id, title, status }) => tables.issue.insert({ id, title, status }),
-  'v1.IssueStatusChanged': ({ id, status }) => tables.issue.update({ status }).where({ id }),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-:::caution[Experimental API]
-The Multi-Store API is still early in its development.
-
-If you have feedback or questions about this API, please don't hesitate to comment on the [RFC](https://github.com/livestorejs/livestore/pull/585)
-:::
-
-### Core Concepts
-
-The multi-store API introduces four main primitives:
-
-- **StoreRegistry** - Manages and caches all store instances with automatic garbage collection
-- **useStore()** - Suspense-enabled hook for accessing individual store instances
-- **storeOptions()** - Type-safe way to define reusable store configurations
-
-Stores are cached by their `storeId` and automatically disposed after being unused for a configurable duration (`unusedCacheTime`)
-
-### Setting Up
-
-First, define your re-usable store configuration using `storeOptions()`:
-
-## `reference/framework-integrations/react/multi-store/store.ts`
-
-```ts filename="reference/framework-integrations/react/multi-store/store.ts"
-
-// Define reusable store configuration with storeOptions()
-// This helper provides type safety and can be reused across your app
-export const issueStoreOptions = (issueId: string) =>
-  storeOptions({
-    storeId: `issue-${issueId}`,
-    schema,
-    adapter: makeInMemoryAdapter(),
-  })
-```
-
-### `reference/framework-integrations/react/multi-store/schema.ts`
-
-```ts filename="reference/framework-integrations/react/multi-store/schema.ts"
-
-// Event definitions
-export const events = {
-  issueCreated: Events.synced({
-    name: 'v1.IssueCreated',
-    schema: Schema.Struct({
-      id: Schema.String,
-      title: Schema.String,
-      status: Schema.Literal('todo', 'done'),
-    }),
-  }),
-  issueStatusChanged: Events.synced({
-    name: 'v1.IssueStatusChanged',
-    schema: Schema.Struct({
-      id: Schema.String,
-      status: Schema.Literal('todo', 'done'),
-    }),
-  }),
-}
-
-// State definition
-export const tables = {
-  issue: State.SQLite.table({
-    name: 'issue',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      title: State.SQLite.text(),
-      status: State.SQLite.text(),
-    },
-  }),
-}
-
-const materializers = State.SQLite.materializers(events, {
-  'v1.IssueCreated': ({ id, title, status }) => tables.issue.insert({ id, title, status }),
-  'v1.IssueStatusChanged': ({ id, status }) => tables.issue.update({ status }).where({ id }),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-Then create a `StoreRegistry` and provide it to your app:
-
-## `reference/framework-integrations/react/multi-store/App.tsx`
-
-```tsx filename="reference/framework-integrations/react/multi-store/App.tsx"
-
-export function App({ children }: { children: ReactNode }) {
-  const [storeRegistry] = useState(() => new StoreRegistry({ defaultOptions: { batchUpdates } }))
-
-  return <StoreRegistryProvider storeRegistry={storeRegistry}>{children}</StoreRegistryProvider>
-}
-```
-
-### Using Stores
-
-Use the `useStore()` hook to load or get a store instance. It suspends until the store is loaded:
-
-## `reference/framework-integrations/react/multi-store/IssueView.tsx`
-
-```tsx filename="reference/framework-integrations/react/multi-store/IssueView.tsx"
-
-export function IssueView({ issueId }: { issueId: string }) {
-  // useStore() suspends the component until the store is loaded
-  // If the same store was already loaded, it returns immediately
-  const issueStore = useStore(issueStoreOptions(issueId))
-
-  // Query data from the store
-  const [issue] = issueStore.useQuery(queryDb(tables.issue.select().where({ id: issueId })))
-
-  if (!issue) return <div>Issue not found</div>
-
-  return (
-    <div>
-      <h3>{issue.title}</h3>
-      <p>Status: {issue.status}</p>
-    </div>
-  )
-}
-
-// Wrap with Suspense and ErrorBoundary for loading and error states
-export function IssueViewWithSuspense({ issueId }: { issueId: string }) {
-  return (
-    <ErrorBoundary fallback={<div>Error loading issue</div>}>
-      <Suspense fallback={<div>Loading issue...</div>}>
-        <IssueView issueId={issueId} />
-      </Suspense>
-    </ErrorBoundary>
-  )
-}
-```
-
-### `reference/framework-integrations/react/multi-store/schema.ts`
-
-```ts filename="reference/framework-integrations/react/multi-store/schema.ts"
-
-// Event definitions
-export const events = {
-  issueCreated: Events.synced({
-    name: 'v1.IssueCreated',
-    schema: Schema.Struct({
-      id: Schema.String,
-      title: Schema.String,
-      status: Schema.Literal('todo', 'done'),
-    }),
-  }),
-  issueStatusChanged: Events.synced({
-    name: 'v1.IssueStatusChanged',
-    schema: Schema.Struct({
-      id: Schema.String,
-      status: Schema.Literal('todo', 'done'),
-    }),
-  }),
-}
-
-// State definition
-export const tables = {
-  issue: State.SQLite.table({
-    name: 'issue',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      title: State.SQLite.text(),
-      status: State.SQLite.text(),
-    },
-  }),
-}
-
-const materializers = State.SQLite.materializers(events, {
-  'v1.IssueCreated': ({ id, title, status }) => tables.issue.insert({ id, title, status }),
-  'v1.IssueStatusChanged': ({ id, status }) => tables.issue.update({ status }).where({ id }),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-### `reference/framework-integrations/react/multi-store/store.ts`
-
-```ts filename="reference/framework-integrations/react/multi-store/store.ts"
-
-// Define reusable store configuration with storeOptions()
-// This helper provides type safety and can be reused across your app
-export const issueStoreOptions = (issueId: string) =>
-  storeOptions({
-    storeId: `issue-${issueId}`,
-    schema,
-    adapter: makeInMemoryAdapter(),
-  })
-```
-
-### Multiple Instances
-
-You can create multiple instances of the same store type by using different `storeId` values:
-
-## `reference/framework-integrations/react/multi-store/IssueList.tsx`
-
-```tsx filename="reference/framework-integrations/react/multi-store/IssueList.tsx"
-
-function IssueCard({ issueId }: { issueId: string }) {
-  // Each call to useStore with a different storeId loads/gets a separate store instance
-  const issueStore = useStore(issueStoreOptions(issueId))
-  const [issue] = issueStore.useQuery(queryDb(tables.issue.select().where({ id: issueId })))
-
-  if (!issue) return <div>Issue not found</div>
-
-  return (
-    <div>
-      <h4>{issue.title}</h4>
-      <p>Store ID: {issueStore.storeId}</p>
-      <p>Status: {issue.status}</p>
-    </div>
-  )
-}
-
-// Component that displays multiple independent store instances with shared error and loading states
-export function IssueList() {
-  const issueIds = ['issue-1', 'issue-2', 'issue-3']
-
-  return (
-    <div>
-      <h3>Issues</h3>
-      <ErrorBoundary fallback={<div>Error loading issues</div>}>
-        <Suspense fallback={<div>Loading issues...</div>}>
-          {issueIds.map((id) => (
-            <IssueCard key={id} issueId={id} />
-          ))}
-        </Suspense>
-      </ErrorBoundary>
-    </div>
-  )
-}
-```
-
-### `reference/framework-integrations/react/multi-store/schema.ts`
-
-```ts filename="reference/framework-integrations/react/multi-store/schema.ts"
-
-// Event definitions
-export const events = {
-  issueCreated: Events.synced({
-    name: 'v1.IssueCreated',
-    schema: Schema.Struct({
-      id: Schema.String,
-      title: Schema.String,
-      status: Schema.Literal('todo', 'done'),
-    }),
-  }),
-  issueStatusChanged: Events.synced({
-    name: 'v1.IssueStatusChanged',
-    schema: Schema.Struct({
-      id: Schema.String,
-      status: Schema.Literal('todo', 'done'),
-    }),
-  }),
-}
-
-// State definition
-export const tables = {
-  issue: State.SQLite.table({
-    name: 'issue',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      title: State.SQLite.text(),
-      status: State.SQLite.text(),
-    },
-  }),
-}
-
-const materializers = State.SQLite.materializers(events, {
-  'v1.IssueCreated': ({ id, title, status }) => tables.issue.insert({ id, title, status }),
-  'v1.IssueStatusChanged': ({ id, status }) => tables.issue.update({ status }).where({ id }),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-### `reference/framework-integrations/react/multi-store/store.ts`
-
-```ts filename="reference/framework-integrations/react/multi-store/store.ts"
-
-// Define reusable store configuration with storeOptions()
-// This helper provides type safety and can be reused across your app
-export const issueStoreOptions = (issueId: string) =>
-  storeOptions({
-    storeId: `issue-${issueId}`,
-    schema,
-    adapter: makeInMemoryAdapter(),
-  })
-```
-
-Each store instance is completely isolated with its own data, event log, and synchronization state.
-
-### Preloading
-
-When you know a store will be needed soon, you can preload it in advance:
-
-## `reference/framework-integrations/react/multi-store/PreloadedIssue.tsx`
-
-```tsx filename="reference/framework-integrations/react/multi-store/PreloadedIssue.tsx"
-
-export function PreloadedIssue({ issueId }: { issueId: string }) {
-  const [showIssue, setShowIssue] = useState(false)
-  const storeRegistry = useStoreRegistry()
-
-  // Preload the store when user hovers (before they click)
-  const handleMouseEnter = () => {
-    storeRegistry.preload(issueStoreOptions(issueId))
-  }
-
-  return (
-    <div>
-      {!showIssue ? (
-        <button type="button" onMouseEnter={handleMouseEnter} onClick={() => setShowIssue(true)}>
-          Show Issue
-        </button>
-      ) : (
-        <ErrorBoundary fallback={<div>Error loading issue</div>}>
-          <Suspense fallback={<div>Loading issue...</div>}>
-            <IssueView issueId={issueId} />
-          </Suspense>
-        </ErrorBoundary>
-      )}
-    </div>
-  )
-}
-```
-
-### `reference/framework-integrations/react/multi-store/IssueView.tsx`
-
-```tsx filename="reference/framework-integrations/react/multi-store/IssueView.tsx"
-
-export function IssueView({ issueId }: { issueId: string }) {
-  // useStore() suspends the component until the store is loaded
-  // If the same store was already loaded, it returns immediately
-  const issueStore = useStore(issueStoreOptions(issueId))
-
-  // Query data from the store
-  const [issue] = issueStore.useQuery(queryDb(tables.issue.select().where({ id: issueId })))
-
-  if (!issue) return <div>Issue not found</div>
-
-  return (
-    <div>
-      <h3>{issue.title}</h3>
-      <p>Status: {issue.status}</p>
-    </div>
-  )
-}
-
-// Wrap with Suspense and ErrorBoundary for loading and error states
-export function IssueViewWithSuspense({ issueId }: { issueId: string }) {
-  return (
-    <ErrorBoundary fallback={<div>Error loading issue</div>}>
-      <Suspense fallback={<div>Loading issue...</div>}>
-        <IssueView issueId={issueId} />
-      </Suspense>
-    </ErrorBoundary>
-  )
-}
-```
-
-### `reference/framework-integrations/react/multi-store/schema.ts`
-
-```ts filename="reference/framework-integrations/react/multi-store/schema.ts"
-
-// Event definitions
-export const events = {
-  issueCreated: Events.synced({
-    name: 'v1.IssueCreated',
-    schema: Schema.Struct({
-      id: Schema.String,
-      title: Schema.String,
-      status: Schema.Literal('todo', 'done'),
-    }),
-  }),
-  issueStatusChanged: Events.synced({
-    name: 'v1.IssueStatusChanged',
-    schema: Schema.Struct({
-      id: Schema.String,
-      status: Schema.Literal('todo', 'done'),
-    }),
-  }),
-}
-
-// State definition
-export const tables = {
-  issue: State.SQLite.table({
-    name: 'issue',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      title: State.SQLite.text(),
-      status: State.SQLite.text(),
-    },
-  }),
-}
-
-const materializers = State.SQLite.materializers(events, {
-  'v1.IssueCreated': ({ id, title, status }) => tables.issue.insert({ id, title, status }),
-  'v1.IssueStatusChanged': ({ id, status }) => tables.issue.update({ status }).where({ id }),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-### `reference/framework-integrations/react/multi-store/store.ts`
-
-```ts filename="reference/framework-integrations/react/multi-store/store.ts"
-
-// Define reusable store configuration with storeOptions()
-// This helper provides type safety and can be reused across your app
-export const issueStoreOptions = (issueId: string) =>
-  storeOptions({
-    storeId: `issue-${issueId}`,
-    schema,
-    adapter: makeInMemoryAdapter(),
-  })
-```
-
-This warms up the cache so the store is ready when the user navigates to it.
-
-### StoreId Guidelines
-
-When creating `storeId` values:
-
-- **Use namespaces** - Prefix with the entity type (e.g., `workspace-abc123`, `issue-456`) to avoid collisions between different store types and improve debugging
-- **Globally unique** - Prefer globally unique IDs (e.g., nanoid) to prevent collisions
-- **Keep them stable** - The same entity should always use the same `storeId` across renders
-- **Sanitize user input** - If incorporating user data, be sure to validate/sanitize to prevent injection attacks
-- **Document your conventions** - Document your conventions and special IDs like `user-current` as they're part of your API contract
-
-### API Reference
-
-#### `storeOptions(options)`
-
-Defines reusable store configuration with type safety. Returns options that can be passed to `useStore()` or `registry.preload()`.
-
-Options:
-- `storeId` - Unique identifier for this store instance (required)
-- `schema` - The LiveStore schema (required)
-- `adapter` - The platform adapter (required)
-- `unusedCacheTime` - Time in milliseconds to keep unused stores in memory (default: 60_000 in browser, infinity in non-browser)
-- `boot` - Function called when the store is first loaded
-- `batchUpdates` - Function for batching React updates
-- And other `CreateStoreOptions`
-
-#### `new StoreRegistry(config?)`
-
-Creates a registry that manages store instances.
-
-Config:
-- `defaultOptions` - Default options applied to all stores (can be overridden per-store)
-
-#### `StoreRegistryProvider`
-
-React context provider that supplies the registry to components.
-
-Props:
-- `storeRegistry` - The registry instance (required)
-- `children` - React nodes (required)
-
-#### `useStore(options)`
-
-Hook that returns a store instance, suspending until it's loaded.
-
-- Throws a Promise during loading (for React Suspense)
-- Throws an Error if loading fails (for Error Boundaries)
-- Returns the loaded store when ready
-
-#### `useStoreRegistry()`
-
-Returns the current `StoreRegistry` from context. Useful for advanced operations like preloading.
-
-#### `registry.preload(options)`
-
-Starts loading a store without suspending. Returns a Promise that resolves when loading completes (or rejects on error). This is a fire-and-forget operation.
-
-### Complete Example
-
-See the <a href={`https://github.com/livestorejs/livestore/tree/${getBranchName()}/examples/web-multi-store`}>Multi-Store example</a> for a complete working application demonstrating various multi-store patterns.
-
-## Technical notes
-
-- `@livestore/react` uses `React.useState` under the hood for `useQuery` / `useClientDocument` to bind LiveStore's reactivity to React's reactivity. Some libraries are using `React.useExternalSyncStore` for similar purposes but using `React.useState` in this case is more efficient and all that's needed for LiveStore.
-- `@livestore/react` supports React Strict Mode.