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

package/docs/building-with-livestore/tools/mcp/index.md

@@ -1,187 +0,0 @@
-# MCP integration
-
-LiveStore includes MCP (Model Context Protocol) integration that allows AI assistants like Claude to access LiveStore documentation, examples, and development tools.
-
-:::caution[Experimental]
-The MCP integration is experimental and under active development. Features may change.
-:::
-
-For installation and general CLI usage, see the [LiveStore CLI](/building-with-livestore/tools/cli) documentation.
-
-## What is MCP?
-
-MCP (Model Context Protocol) is a standard for providing AI assistants with access to external resources and tools. LiveStore's MCP server gives AI assistants access to:
-
-- LiveStore documentation and guides
-- Schema examples for common app types
-- Development tools and utilities
-
-## Usage
-
-Start the MCP server:
-
-```bash
-bunx @livestore/cli mcp
-```
-
-## Available commands
-
-### `bunx @livestore/cli mcp coach`
-Starts an AI coaching assistant with access to LiveStore documentation and best practices.
-
-### `bunx @livestore/cli mcp tools`
-Provides development tools and utilities for working with LiveStore projects.
-
-### LiveStore Runtime Tools
-
-- `livestore_instance_connect`
-  - Connects a single in-process LiveStore instance by dynamically importing a module that exports `schema` and a `syncBackend` factory (and optionally `syncPayload`).
-  - Notes:
-    - Only one instance can be active at a time; connecting again shuts down and replaces the previous instance.
-    - Reconnecting creates a fresh, in-memory client database. The visible state is populated by your backend's initial sync. Until sync completes, queries may return empty or partial results.
-  - Module contract (generic example):
-
-## `reference/mcp/module-contract.ts`
-
-```ts filename="reference/mcp/module-contract.ts"
-
-export { schema } from './schema.ts'
-
-export const syncBackend = makeWsSync({ url: process.env.LIVESTORE_SYNC_URL ?? 'ws://localhost:8787' })
-
-export const syncPayload = { authToken: process.env.LIVESTORE_SYNC_AUTH_TOKEN ?? 'insecure-token-change-me' }
-```
-
-### `reference/mcp/schema.ts`
-
-```ts filename="reference/mcp/schema.ts"
-
-const events = {
-  entityCreated: Events.synced({
-    name: 'v1.EntityCreated',
-    schema: Schema.Struct({
-      id: Schema.String,
-      title: Schema.String,
-      createdAt: Schema.DateFromString,
-    }),
-  }),
-}
-
-const tables = {
-  entities: State.SQLite.table({
-    name: 'entities',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      title: State.SQLite.text({ default: '' }),
-      createdAt: State.SQLite.text({ default: '' }),
-    },
-  }),
-}
-
-const materializers = State.SQLite.materializers(events, {
-  'v1.EntityCreated': ({ id, title, createdAt }) =>
-    tables.entities.insert({ id, title, createdAt: createdAt.toISOString() }),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-- Params example: `{ "configPath": "livestore-cli.config.ts", "storeId": "<store-id>" }`
-  - Returns example:
-    `{ "storeId": "<store-id>", "clientId": "client-123", "sessionId": "session-abc", "schemaInfo": { "tableNames": ["..."], "eventNames": ["..."] } }`
-
-- `livestore_instance_query`
-  - Executes raw SQL against the client database (read-only).
-  - Notes:
-    - SQLite dialect; use valid SQLite syntax.
-    - `bindValues` must be an array (positional `?`) or a record (named `$key`). Do not pass stringified JSON.
-  - Params example (positional): `{ "sql": "SELECT * FROM my_table WHERE userId = ?", "bindValues": ["u1"] }`
-  - Params example (named): `{ "sql": "SELECT * FROM my_table WHERE userId = $userId", "bindValues": { "userId": "u1" } }`
-  - Returns example: `{ "rows": [{ "col": "value" }], "rowCount": 1 }`
-
-- `livestore_instance_commit_events`
-  - Commits one or more events defined by your connected schema.
-  - Notes:
-    - Use the canonical event name declared in your schema (e.g., `v1.EntityCreated`).
-    - `args` must be a non-stringified JSON object matching the event schema. Date fields typically accept ISO 8601 strings.
-  - Params example: `{ "events": [{ "name": "v1.EntityCreated", "args": { "id": "e1", "title": "Hello", "createdAt": "2024-01-01T00:00:00.000Z" } }] }`
-  - Returns example: `{ "committed": 1 }`
-
-- `livestore_instance_status`
-  - Reports instance/runtime info.
-  - Returns example (connected): `{ "_tag": "connected", "storeId": "<store-id>", "clientId": "client-123", "sessionId": "session-abc", "tableCounts": { "my_table": 12 } }`
-  - Returns example (not connected): `{ "_tag": "disconnected" }`
-
-- `livestore_instance_disconnect`
-  - Disconnects the current LiveStore instance and releases resources.
-  - Returns: `{ "_tag": "disconnected" }`
-
-### Sync export/import tools
-
-These tools connect directly to the sync backend (without creating a full LiveStore instance) to export or import events. Useful for backup, migration, and debugging.
-
-- `livestore_sync_export`
-  - Exports all events from a sync backend to JSON data.
-  - Notes:
-    - Connects directly to the sync backend and pulls all events.
-    - Returns the export data as a JSON object that can be saved or passed to import.
-  - Params example: `{ "configPath": "livestore-cli.config.ts", "storeId": "my-store" }`
-  - Returns example: `{ "storeId": "my-store", "eventCount": 127, "exportedAt": "2024-01-15T10:30:00.000Z", "data": { "version": 1, "storeId": "my-store", "events": [...] } }`
-
-- `livestore_sync_import`
-  - Imports events from export data to a sync backend.
-  - Notes:
-    - The sync backend must be empty before importing.
-    - Use `force: true` to import even if the store ID in the data doesn't match.
-    - Use `dryRun: true` to validate the import without actually importing.
-  - Params example: `{ "configPath": "livestore-cli.config.ts", "storeId": "my-store", "data": { "version": 1, "storeId": "my-store", "events": [...] } }`
-  - Params with options: `{ "configPath": "...", "storeId": "...", "data": {...}, "force": true, "dryRun": true }`
-  - Returns example: `{ "storeId": "my-store", "eventCount": 127, "dryRun": false }`
-
-## Local Cloudflare sync (dev)
-
-Run a local Cloudflare sync backend:
-
-1. Start the sync worker (wrangler):
-   - `cd tests/integration/src/tests/adapter-cloudflare/fixtures`
-   - `wrangler dev`
-   - You should see an info page at `http://localhost:8787/`.
-
-2. Start the MCP server in another terminal:
-   - `bunx @livestore/cli mcp server`
-
-3. From your MCP client (e.g., Claude Desktop), call tools:
-   - Use your own config file path and storeId. The repo also provides an example: `examples/cf-chat/livestore-cli.config.ts`.
-   - Connect: `livestore_instance_connect` with `{ "configPath": "livestore-cli.config.ts", "storeId": "<store-id>" }`
-   - Commit: `livestore_instance_commit_events` with `[ { "name": "v1.EntityCreated", "args": { "id": "e1", "title": "Hello", "createdAt": "2024-01-01T00:00:00.000Z" } } ]`
-   - Query: `livestore_instance_query` with `{ "sql": "SELECT * FROM my_table ORDER BY createdAt DESC LIMIT 5" }`
-   - Status: `livestore_instance_status`
-   - Disconnect: `livestore_instance_disconnect`
-
-## Adding to Claude
-
-To use with Claude Desktop, add the MCP server to your Claude configuration:
-
-```json
-{
-  "mcpServers": {
-    "livestore": {
-      "command": "bunx",
-      "args": ["@livestore/cli", "mcp"]
-    }
-  }
-}
-```
-
-## Available resources
-
-The MCP server provides access to:
-
-- **Documentation**: Overview, features, getting started guides
-- **Architecture**: Technical design and principles  
-- **Schema Examples**: Pre-built schemas for todo, blog, e-commerce, and social apps
-- **Development Tools**: Project scaffolding and utilities
-
-This enables AI assistants to provide context-aware help with LiveStore development.

package/docs/examples/cloudflare-adapter/index.md

@@ -1,44 +0,0 @@
-# Cloudflare Durable Objects examples
-
-# Cloudflare Durable Objects Examples
-
-Examples using `@livestore/adapter-cloudflare` for Cloudflare Workers and Durable Objects.
-
-<CardGrid>
-{cloudflareExamples.map((example) => {
-  const { url, label } = getExampleDemoLinks(example);
-
-  return (
-    <Card title={example.title} key={example.title}>
-    {example.image ? (
-      <Image src={example.image.url} width={example.image.width} height={example.image.height} alt={`${example.title} application interface`} />
-    ) : (
-      <div style="background: linear-gradient(135deg, #1f2937 0%, #374151 100%); height: 200px; display: flex; align-items: center; justify-content: center; color: #9ca3af; font-size: 14px; border-radius: 8px;">
-        Screenshot coming soon
-      </div>
-    )}
-    <p>{example.description}</p>
-    <p><strong>Technologies:</strong> {example.technologies.join(' • ')}</p>
-    {example.syncProvider && (
-      <p><strong>Sync Provider:</strong> {example.syncProvider}</p>
-    )}
-    <div style="margin-top: auto; padding-top: 1rem;">
-      {url && (
-        <p style="margin: 0 0 0.5rem 0;"><a href={url} target="_blank" rel="noopener noreferrer">{label}</a></p>
-      )}
-      <p style="margin: 0;"><a href={example.sourceUrl} target="_blank" rel="noopener noreferrer">View Source →</a></p>
-    </div>
-    </Card>
-  );
-})}
-</CardGrid>
-
-## Cloudflare Adapter
-
-- Runs LiveStore inside Cloudflare Durable Objects
-- Uses Durable Object Storage API (not traditional databases)
-- SQLite WASM with Cloudflare-specific VFS
-- No WebSocket support - uses Durable Objects' distributed consistency
-
----
-<a href={`https://github.com/livestorejs/livestore/tree/${getBranchName()}/examples`}>View all examples on GitHub →</a>

package/docs/examples/expo-adapter/index.md

@@ -1,44 +0,0 @@
-# Expo adapter examples
-
-# Expo Adapter Examples
-
-Examples using `@livestore/adapter-expo` for React Native mobile applications.
-
-<CardGrid>
-{expoExamples.map((example) => {
-  const { url, label } = getExampleDemoLinks(example);
-
-  return (
-    <Card title={example.title} key={example.title}>
-    {example.image ? (
-      <Image src={example.image.url} width={example.image.width} height={example.image.height} alt={`${example.title} application interface`} />
-    ) : (
-      <div style="background: linear-gradient(135deg, #1f2937 0%, #374151 100%); height: 200px; display: flex; align-items: center; justify-content: center; color: #9ca3af; font-size: 14px; border-radius: 8px;">
-        Screenshot coming soon
-      </div>
-    )}
-    <p>{example.description}</p>
-    <p><strong>Technologies:</strong> {example.technologies.join(' • ')}</p>
-    {example.syncProvider && (
-      <p><strong>Sync Provider:</strong> {example.syncProvider}</p>
-    )}
-    <div style="margin-top: auto; padding-top: 1rem;">
-      {url && (
-        <p style="margin: 0 0 0.5rem 0;"><a href={url} target="_blank" rel="noopener noreferrer">{label}</a></p>
-      )}
-      <p style="margin: 0;"><a href={example.sourceUrl} target="_blank" rel="noopener noreferrer">View Source →</a></p>
-    </div>
-    </Card>
-  );
-})}
-</CardGrid>
-
-## Expo Adapter
-
-- Uses native Expo SQLite stored in device's SQLite directory
-- Requires New Architecture (Fabric) - incompatible with old architecture
-- Single-threaded operation in main thread
-- WebSocket connections for sync via React Native dev server
-
----
-<a href={`https://github.com/livestorejs/livestore/tree/${getBranchName()}/examples`}>View all examples on GitHub →</a>

package/docs/examples/index.md

@@ -1,55 +0,0 @@
-# Examples
-
-# Example Applications
-
-Discover how to build local-first applications with LiveStore through our comprehensive collection of example apps. Each example demonstrates different features, patterns, and platform integrations to help you get started quickly.
-
-## Browse by platform adapter
-
-LiveStore supports multiple platform adapters, each optimized for different environments. Choose the adapter that matches your target platform:
-
-<CardGrid>
-  <LinkCard 
-    title="Web Adapter" 
-    href="/examples/web-adapter/"
-    description={`Browser-based applications with SQLite WASM, Web Workers, and framework integrations. ${webExamples.length} examples • React, SolidJS, Svelte, Web Components`}
-  />
-
-  <LinkCard 
-    title="Node Adapter" 
-    href="/examples/node-adapter/"
-    description={`Server-side applications, CLI tools, and backend services with native SQLite performance. ${nodeExamples.length} examples • Effect, CLI applications`}
-  />
-
-  <LinkCard 
-    title="Expo Adapter" 
-    href="/examples/expo-adapter/"
-    description={`React Native mobile applications with offline-first architecture and cross-platform sync. ${expoExamples.length} examples • iOS, Android, React Native`}
-  />
-
-  <LinkCard 
-    title="Cloudflare Durable Objects" 
-    href="/examples/cloudflare-adapter/"
-    description={`Edge computing with Durable Objects, global distribution, and serverless scaling. ${cloudflareExamples.length} examples • Workers, Durable Objects, Edge`}
-  />
-</CardGrid>
-
-## Getting started
-
-1. **Choose your platform** from the adapter categories above
-2. **Browse examples** that match your use case and framework preference  
-3. **Clone and run** the examples locally to see LiveStore in action
-4. **Study the source code** to understand patterns and best practices
-
-## Multi-adapter examples
-
-Some examples demonstrate **cross-platform synchronization** by using multiple adapters:
-- **CF Chat** uses both Web and Cloudflare adapters for hybrid client-server architecture
-- **Sync-enabled examples** show how to connect different platforms seamlessly
-
-## About LiveStore
-
-LiveStore is a local-first data layer that runs everywhere - from browsers to mobile apps to edge computing. Each adapter provides platform-optimized features while maintaining a consistent API across all environments.
-
----
-<a href={`https://github.com/livestorejs/livestore/tree/${getBranchName()}/examples`}>View all examples on GitHub →</a>

package/docs/examples/node-adapter/index.md

@@ -1,44 +0,0 @@
-# Node adapter examples
-
-# Node Adapter Examples
-
-Examples using `@livestore/adapter-node` for Node.js server-side applications.
-
-<CardGrid>
-{nodeExamples.map((example) => {
-  const { url, label } = getExampleDemoLinks(example);
-
-  return (
-    <Card title={example.title} key={example.title}>
-    {example.image ? (
-      <Image src={example.image.url} width={example.image.width} height={example.image.height} alt={`${example.title} application interface`} />
-    ) : (
-      <div style="background: linear-gradient(135deg, #1f2937 0%, #374151 100%); height: 200px; display: flex; align-items: center; justify-content: center; color: #9ca3af; font-size: 14px; border-radius: 8px;">
-        Screenshot coming soon
-      </div>
-    )}
-    <p>{example.description}</p>
-    <p><strong>Technologies:</strong> {example.technologies.join(' • ')}</p>
-    {example.syncProvider && (
-      <p><strong>Sync Provider:</strong> {example.syncProvider}</p>
-    )}
-    <div style="margin-top: auto; padding-top: 1rem;">
-      {url && (
-        <p style="margin: 0 0 0.5rem 0;"><a href={url} target="_blank" rel="noopener noreferrer">{label}</a></p>
-      )}
-      <p style="margin: 0;"><a href={example.sourceUrl} target="_blank" rel="noopener noreferrer">View Source →</a></p>
-    </div>
-    </Card>
-  );
-})}
-</CardGrid>
-
-## Node Adapter
-
-- Uses native Node.js SQLite with file system storage
-- Stores SQLite files directly on disk (default: current directory)
-- Supports single-threaded or worker thread modes
-- WebSocket connections for sync and devtools integration
-
----
-<a href={`https://github.com/livestorejs/livestore/tree/${getBranchName()}/examples`}>View all examples on GitHub →</a>

package/docs/examples/web-adapter/index.md

@@ -1,52 +0,0 @@
-# Web adapter examples
-
-# Web Adapter Examples
-
-Examples using `@livestore/adapter-web` for browser environments.
-
-<CardGrid>
-{webExamples.map((example) => {
-  const { url, label } = getExampleDemoLinks(example);
-
-  return (
-    <Card title={example.title} key={example.title}>
-    {example.image ? (
-      <Image src={example.image.url} width={example.image.width} height={example.image.height} alt={`${example.title} application interface`} />
-    ) : (
-      <div style="background: linear-gradient(135deg, #1f2937 0%, #374151 100%); height: 200px; display: flex; align-items: center; justify-content: center; color: #9ca3af; font-size: 14px; border-radius: 8px;">
-        Screenshot coming soon
-      </div>
-    )}
-    <p>{example.description}</p>
-    <p><strong>Technologies:</strong> {example.technologies.join(' • ')}</p>
-    {example.syncProvider && (
-      <p><strong>Sync Provider:</strong> {example.syncProvider}</p>
-    )}
-    <div style="margin-top: auto; padding-top: 1rem;">
-      {url && (
-        <p style="margin: 0 0 0.5rem 0;"><a href={url} target="_blank" rel="noopener noreferrer">{label}</a></p>
-      )}
-      <p style="margin: 0;"><a href={example.sourceUrl} target="_blank" rel="noopener noreferrer">View Source →</a></p>
-    </div>
-    </Card>
-  );
-})}
-</CardGrid>
-
-## Web Adapter
-
-- Uses SQLite WASM with OPFS (Origin Private File System) for browser storage
-- Runs in Web Workers and SharedWorkers for multi-tab coordination
-- Persists data via OPFS Access Handle Pool VFS
-- Supports WebSocket connections for sync and devtools
-
-## Frameworks
-
-- React (`@livestore/react`)
-- SolidJS (`@livestore/solid`) 
-- Svelte (`@livestore/svelte`)
-- Web Components
-- Vanilla JavaScript
-
----
-<a href={`https://github.com/livestorejs/livestore/tree/${getBranchName()}/examples`}>View all examples on GitHub →</a>

package/docs/framework-integrations/custom-elements/index.md

@@ -1,142 +0,0 @@
-# Custom elements
-
-LiveStore can be used with custom elements/web components.
-
-## Example
-
-See [examples](/examples) for a complete example.
-
-## `reference/custom-elements/main.ts`
-
-```ts filename="reference/custom-elements/main.ts"
-
-const adapter = makePersistedAdapter({
-  storage: { type: 'opfs' },
-  worker: LiveStoreWorker,
-  sharedWorker: LiveStoreSharedWorker,
-})
-
-const store = await createStorePromise({ schema, adapter, storeId: 'custom-elements-demo' })
-
-const visibleTodos$ = queryDb(tables.todos.where({ deletedAt: null }))
-
-class TodoListElement extends HTMLElement {
-  private list: HTMLUListElement
-  private input: HTMLInputElement
-
-  constructor() {
-    super()
-    const shadow = this.attachShadow({ mode: 'open' })
-
-    this.input = document.createElement('input')
-    this.input.placeholder = 'What needs to be done?'
-
-    this.list = document.createElement('ul')
-    this.list.style.listStyle = 'none'
-    this.list.style.padding = '0'
-    this.list.style.margin = '16px 0 0'
-
-    this.input.addEventListener('keydown', (event) => {
-      if (event.key === 'Enter' && this.input.value.trim()) {
-        store.commit(events.todoCreated({ id: crypto.randomUUID(), text: this.input.value.trim() }))
-        this.input.value = ''
-      }
-    })
-
-    shadow.append(this.input, this.list)
-  }
-
-  connectedCallback(): void {
-    this.renderTodos(Array.from(store.query(tables.todos.where({ deletedAt: null }))))
-
-    store.subscribe(visibleTodos$, (todos) => this.renderTodos(todos))
-  }
-
-  private renderTodos(todos: ReadonlyArray<typeof tables.todos.Type>): void {
-    const nodes = Array.from(todos, (todo) => {
-      const item = document.createElement('li')
-      item.textContent = todo.text
-      item.style.cursor = 'pointer'
-      item.addEventListener('click', () => {
-        store.commit(todo.completed ? events.todoUncompleted({ id: todo.id }) : events.todoCompleted({ id: todo.id }))
-      })
-
-      const deleteButton = document.createElement('button')
-      deleteButton.type = 'button'
-      deleteButton.textContent = '✕'
-      deleteButton.style.marginLeft = '8px'
-      deleteButton.addEventListener('click', (event) => {
-        event.stopPropagation()
-        store.commit(events.todoDeleted({ id: todo.id, deletedAt: new Date() }))
-      })
-
-      const row = document.createElement('div')
-      row.style.display = 'flex'
-      row.style.alignItems = 'center'
-      row.appendChild(item)
-      row.appendChild(deleteButton)
-
-      const wrapper = document.createElement('li')
-      wrapper.appendChild(row)
-      return wrapper
-    })
-
-    this.list.replaceChildren(...nodes)
-  }
-}
-
-customElements.define('todo-list', TodoListElement)
-```
-
-### `reference/custom-elements/livestore/schema.ts`
-
-```ts filename="reference/custom-elements/livestore/schema.ts"
-
-export const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text({ default: '' }),
-      completed: State.SQLite.boolean({ default: false }),
-      deletedAt: State.SQLite.integer({ nullable: true, schema: Schema.DateFromNumber }),
-    },
-  }),
-  uiState: State.SQLite.clientDocument({
-    name: 'uiState',
-    schema: Schema.Struct({ newTodoText: Schema.String }),
-    default: { id: SessionIdSymbol, value: { newTodoText: '' } },
-  }),
-}
-
-export const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-  todoCompleted: Events.synced({
-    name: 'v1.TodoCompleted',
-    schema: Schema.Struct({ id: Schema.String }),
-  }),
-  todoUncompleted: Events.synced({
-    name: 'v1.TodoUncompleted',
-    schema: Schema.Struct({ id: Schema.String }),
-  }),
-  todoDeleted: Events.synced({
-    name: 'v1.TodoDeleted',
-    schema: Schema.Struct({ id: Schema.String, deletedAt: Schema.Date }),
-  }),
-  uiStateSet: tables.uiState.set,
-}
-
-const materializers = State.SQLite.materializers(events, {
-  'v1.TodoCreated': ({ id, text }) => tables.todos.insert({ id, text, completed: false }),
-  'v1.TodoCompleted': ({ id }) => tables.todos.update({ completed: true }).where({ id }),
-  'v1.TodoUncompleted': ({ id }) => tables.todos.update({ completed: false }).where({ id }),
-  'v1.TodoDeleted': ({ id, deletedAt }) => tables.todos.update({ deletedAt }).where({ id }),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```