@livestore/livestore 0.3.0-dev.5 → 0.3.0-dev.50

package/src/store/create-store.ts

@@ -2,21 +2,24 @@ import type {
   Adapter,
   BootStatus,
   ClientSession,
+  ClientSessionDevtoolsChannel,
   IntentionalShutdownCause,
-  StoreDevtoolsChannel,
+  MigrationsReport,
 } from '@livestore/common'
 import { provideOtel, UnexpectedError } from '@livestore/common'
-import type { EventId, LiveStoreSchema, MutationEvent } from '@livestore/common/schema'
-import { LS_DEV } from '@livestore/utils'
-import type { Cause } from '@livestore/utils/effect'
+import type { LiveStoreSchema } from '@livestore/common/schema'
+import { isDevEnv, LS_DEV } from '@livestore/utils'
+import type { Cause, Schema } from '@livestore/utils/effect'
 import {
+  Context,
   Deferred,
   Effect,
   Exit,
+  Fiber,
   identity,
+  Layer,
   Logger,
   LogLevel,
-  MutableHashMap,
   OtelTracer,
   Queue,
   Runtime,
@@ -26,43 +29,112 @@ import {
 import { nanoid } from '@livestore/utils/nanoid'
 import * as otel from '@opentelemetry/api'
 
-import { globalReactivityGraph } from '../global-state.js'
-import type { ReactivityGraph } from '../live-queries/base-class.js'
 import { connectDevtoolsToStore } from './devtools.js'
 import { Store } from './store.js'
-import type { BaseGraphQLContext, GraphQLOptions, OtelOptions, ShutdownDeferred } from './store-types.js'
+import type {
+  LiveStoreContextRunning as LiveStoreContextRunning_,
+  OtelOptions,
+  ShutdownDeferred,
+} from './store-types.js'
+
+export const DEFAULT_PARAMS = {
+  leaderPushBatchSize: 1,
+}
+
+export class LiveStoreContextRunning extends Context.Tag('@livestore/livestore/effect/LiveStoreContextRunning')<
+  LiveStoreContextRunning,
+  LiveStoreContextRunning_
+>() {
+  static fromDeferred = Effect.gen(function* () {
+    const deferred = yield* DeferredStoreContext
+    const ctx = yield* deferred
+    return Layer.succeed(LiveStoreContextRunning, ctx)
+  }).pipe(Layer.unwrapScoped)
+}
+
+export class DeferredStoreContext extends Context.Tag('@livestore/livestore/effect/DeferredStoreContext')<
+  DeferredStoreContext,
+  Deferred.Deferred<LiveStoreContextRunning['Type'], UnexpectedError>
+>() {}
+
+export type LiveStoreContextProps<TSchema extends LiveStoreSchema, TContext = {}> = {
+  schema: TSchema
+  /**
+   * The `storeId` can be used to isolate multiple stores from each other.
+   * So it can be useful for multi-tenancy scenarios.
+   *
+   * The `storeId` is also used for persistence.
+   *
+   * @default 'default'
+   */
+  storeId?: string
+  /** Can be useful for custom live query implementations (e.g. see `@livestore/graphql`) */
+  context?: TContext
+  boot?: (
+    store: Store<TSchema, TContext>,
+  ) => Effect.Effect<void, unknown, OtelTracer.OtelTracer | LiveStoreContextRunning>
+  adapter: Adapter
+  /**
+   * Whether to disable devtools.
+   *
+   * @default 'auto'
+   */
+  disableDevtools?: boolean | 'auto'
+  onBootStatus?: (status: BootStatus) => void
+  batchUpdates: (run: () => void) => void
+}
 
-export interface CreateStoreOptions<TGraphQLContext extends BaseGraphQLContext, TSchema extends LiveStoreSchema> {
+export interface CreateStoreOptions<TSchema extends LiveStoreSchema, TContext = {}> {
   schema: TSchema
   adapter: Adapter
   storeId: string
-  reactivityGraph?: ReactivityGraph
-  graphQLOptions?: GraphQLOptions<TGraphQLContext>
+  context?: TContext
   boot?: (
-    store: Store<TGraphQLContext, TSchema>,
-    parentSpan: otel.Span,
-  ) => void | Promise<void> | Effect.Effect<void, unknown, OtelTracer.OtelTracer>
+    store: Store<TSchema, TContext>,
+    ctx: {
+      migrationsReport: MigrationsReport
+      parentSpan: otel.Span
+    },
+  ) => void | Promise<void> | Effect.Effect<void, unknown, OtelTracer.OtelTracer | LiveStoreContextRunning>
   batchUpdates?: (run: () => void) => void
-  disableDevtools?: boolean
+  /**
+   * Whether to disable devtools.
+   *
+   * @default 'auto'
+   */
+  disableDevtools?: boolean | 'auto'
   onBootStatus?: (status: BootStatus) => void
   shutdownDeferred?: ShutdownDeferred
+  /**
+   * Currently only used in the web adapter:
+   * If true, registers a beforeunload event listener to confirm unsaved changes.
+   *
+   * @default true
+   */
+  confirmUnsavedChanges?: boolean
+  /**
+   * Payload that will be passed to the sync backend when connecting
+   *
+   * @default undefined
+   */
+  syncPayload?: Schema.JsonValue
+  params?: {
+    leaderPushBatchSize?: number
+  }
   debug?: {
     instanceId?: string
   }
 }
 
 /** Create a new LiveStore Store */
-export const createStorePromise = async <
-  TGraphQLContext extends BaseGraphQLContext,
-  TSchema extends LiveStoreSchema = LiveStoreSchema,
->({
+export const createStorePromise = async <TSchema extends LiveStoreSchema = LiveStoreSchema, TContext = {}>({
   signal,
   otelOptions,
   ...options
-}: CreateStoreOptions<TGraphQLContext, TSchema> & {
+}: CreateStoreOptions<TSchema, TContext> & {
   signal?: AbortSignal
   otelOptions?: Partial<OtelOptions>
-}): Promise<Store<TGraphQLContext, TSchema>> =>
+}): Promise<Store<TSchema, TContext>> =>
   Effect.gen(function* () {
     const scope = yield* Scope.make()
     const runtime = yield* Effect.runtime()
@@ -81,34 +153,35 @@ export const createStorePromise = async <
     provideOtel({ parentSpanContext: otelOptions?.rootSpanContext, otelTracer: otelOptions?.tracer }),
     Effect.tapCauseLogPretty,
     Effect.annotateLogs({ thread: 'window' }),
-    Effect.provide(Logger.pretty),
+    Effect.provide(Logger.prettyWithThread('window')),
     Logger.withMinimumLogLevel(LogLevel.Debug),
     Effect.runPromise,
   )
 
-export const createStore = <
-  TGraphQLContext extends BaseGraphQLContext,
-  TSchema extends LiveStoreSchema = LiveStoreSchema,
->({
+export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema, TContext = {}>({
   schema,
   adapter,
   storeId,
-  graphQLOptions,
+  context = {} as TContext,
   boot,
-  reactivityGraph = globalReactivityGraph,
   batchUpdates,
   disableDevtools,
   onBootStatus,
   shutdownDeferred,
+  params,
   debug,
-}: CreateStoreOptions<TGraphQLContext, TSchema>): Effect.Effect<
-  Store<TGraphQLContext, TSchema>,
+  confirmUnsavedChanges = true,
+  syncPayload,
+}: CreateStoreOptions<TSchema, TContext>): Effect.Effect<
+  Store<TSchema, TContext>,
   UnexpectedError,
   Scope.Scope | OtelTracer.OtelTracer
 > =>
   Effect.gen(function* () {
     const lifetimeScope = yield* Scope.make()
 
+    yield* validateStoreId(storeId)
+
     yield* Effect.addFinalizer((_) => Scope.close(lifetimeScope, _))
 
     const debugInstanceId = debug?.instanceId ?? nanoid(10)
@@ -130,7 +203,7 @@ export const createStore = <
 
       const storeDeferred = yield* Deferred.make<Store>()
 
-      const connectDevtoolsToStore_ = (storeDevtoolsChannel: StoreDevtoolsChannel) =>
+      const connectDevtoolsToStore_ = (storeDevtoolsChannel: ClientSessionDevtoolsChannel) =>
         Effect.gen(function* () {
           const store = yield* storeDeferred
           yield* connectDevtoolsToStore({ storeDevtoolsChannel, store })
@@ -139,53 +212,81 @@ export const createStore = <
       const runtime = yield* Effect.runtime<Scope.Scope>()
 
       const shutdown = (cause: Cause.Cause<UnexpectedError | IntentionalShutdownCause>) =>
-        Scope.close(lifetimeScope, Exit.failCause(cause)).pipe(
-          Effect.logWarnIfTakesLongerThan({ label: '@livestore/livestore:shutdown', duration: 500 }),
-          Effect.timeout(1000),
-          Effect.catchTag('TimeoutException', () =>
-            Effect.logError('@livestore/livestore:shutdown: Timed out after 1 second'),
-          ),
-          Effect.tap(() => (shutdownDeferred ? Deferred.failCause(shutdownDeferred, cause) : Effect.void)),
-          Effect.tap(() => Effect.logDebug('LiveStore shutdown complete')),
-          Effect.withSpan('livestore:shutdown'),
+        Effect.gen(function* () {
+          yield* Scope.close(lifetimeScope, Exit.failCause(cause)).pipe(
+            Effect.logWarnIfTakesLongerThan({ label: '@livestore/livestore:shutdown', duration: 500 }),
+            Effect.timeout(1000),
+            Effect.catchTag('TimeoutException', () =>
+              Effect.logError('@livestore/livestore:shutdown: Timed out after 1 second'),
+            ),
+          )
+
+          if (shutdownDeferred) {
+            yield* Deferred.failCause(shutdownDeferred, cause)
+          }
+
+          yield* Effect.logDebug('LiveStore shutdown complete')
+        }).pipe(
+          Effect.withSpan('@livestore/livestore:shutdown'),
+          Effect.provide(runtime),
+          Effect.tapCauseLogPretty,
+          // Given that the shutdown flow might also interrupt the effect that is calling the shutdown,
+          // we want to detach the shutdown effect so it's not interrupted by itself
+          Effect.runFork,
+          Fiber.join,
         )
 
       const clientSession: ClientSession = yield* adapter({
         schema,
         storeId,
-        devtoolsEnabled: disableDevtools !== true,
+        devtoolsEnabled: getDevtoolsEnabled(disableDevtools),
         bootStatusQueue,
         shutdown,
         connectDevtoolsToStore: connectDevtoolsToStore_,
         debugInstanceId,
+        syncPayload,
       }).pipe(Effect.withPerformanceMeasure('livestore:makeAdapter'), Effect.withSpan('createStore:makeAdapter'))
 
-      // TODO fill up with unsynced mutation events from the client session
-      const unsyncedMutationEvents = MutableHashMap.empty<EventId.EventId, MutationEvent.ForSchema<TSchema>>()
-
-      const store = Store.createStore<TGraphQLContext, TSchema>(
-        {
-          clientSession,
-          schema,
-          graphQLOptions,
-          otelOptions: { tracer: otelTracer, rootSpanContext: otelRootSpanContext },
-          reactivityGraph,
-          disableDevtools,
-          unsyncedMutationEvents,
-          lifetimeScope,
-          runtime,
-          // NOTE during boot we're not yet executing mutations in a batched context
-          // but only set the provided `batchUpdates` function after boot
-          batchUpdates: (run) => run(),
-          storeId,
+      if (LS_DEV && clientSession.leaderThread.initialState.migrationsReport.migrations.length > 0) {
+        yield* Effect.logDebug(
+          '[@livestore/livestore:createStore] migrationsReport',
+          ...clientSession.leaderThread.initialState.migrationsReport.migrations.map((m) =>
+            m.hashes.actual === undefined
+              ? `Table '${m.tableName}' doesn't exist yet. Creating table...`
+              : `Schema hash mismatch for table '${m.tableName}' (DB: ${m.hashes.actual}, expected: ${m.hashes.expected}), migrating table...`,
+          ),
+        )
+      }
+
+      const store = new Store<TSchema, TContext>({
+        clientSession,
+        schema,
+        context,
+        otelOptions: { tracer: otelTracer, rootSpanContext: otelRootSpanContext },
+        effectContext: { lifetimeScope, runtime },
+        // TODO find a better way to detect if we're running LiveStore in the LiveStore devtools
+        // But for now this is a good enough approximation with little downsides
+        __runningInDevtools: getDevtoolsEnabled(disableDevtools) === false,
+        confirmUnsavedChanges,
+        // NOTE during boot we're not yet executing events in a batched context
+        // but only set the provided `batchUpdates` function after boot
+        batchUpdates: (run) => run(),
+        storeId,
+        params: {
+          leaderPushBatchSize: params?.leaderPushBatchSize ?? DEFAULT_PARAMS.leaderPushBatchSize,
         },
-        span,
-      )
+      })
+
+      // Starts background fibers (syncing, event processing, etc) for store
+      yield* store.boot
 
       if (boot !== undefined) {
         // TODO also incorporate `boot` function progress into `bootStatusQueue`
-        yield* Effect.tryAll(() => boot(store, span)).pipe(
+        yield* Effect.tryAll(() =>
+          boot(store, { migrationsReport: clientSession.leaderThread.initialState.migrationsReport, parentSpan: span }),
+        ).pipe(
           UnexpectedError.mapToUnexpectedError,
+          Effect.provide(Layer.succeed(LiveStoreContextRunning, { stage: 'running', store: store as any as Store })),
           Effect.withSpan('createStore:boot'),
         )
       }
@@ -208,3 +309,28 @@ export const createStore = <
       Scope.extend(lifetimeScope),
     )
   })
+
+const validateStoreId = (storeId: string) =>
+  Effect.gen(function* () {
+    const validChars = /^[a-zA-Z0-9_-]+$/
+
+    if (!validChars.test(storeId)) {
+      return yield* UnexpectedError.make({
+        cause: `Invalid storeId: ${storeId}. Only alphanumeric characters, underscores, and hyphens are allowed.`,
+        payload: { storeId },
+      })
+    }
+  })
+
+const getDevtoolsEnabled = (disableDevtools: boolean | 'auto' | undefined) => {
+  // If an explicit value is provided, use that
+  if (disableDevtools === true || disableDevtools === false) {
+    return !disableDevtools
+  }
+
+  if (isDevEnv() === true) {
+    return true
+  }
+
+  return false
+}

package/src/store/devtools.ts

@@ -1,20 +1,22 @@
-import type { ClientSession, DebugInfo } from '@livestore/common'
+import type { ClientSession, ClientSessionSyncProcessor, DebugInfo, SyncState } from '@livestore/common'
 import { Devtools, liveStoreVersion, UnexpectedError } from '@livestore/common'
 import { throttle } from '@livestore/utils'
 import type { WebChannel } from '@livestore/utils/effect'
 import { Effect, Stream } from '@livestore/utils/effect'
+import { nanoid } from '@livestore/utils/nanoid'
 
 import type { LiveQuery, ReactivityGraph } from '../live-queries/base-class.js'
 import { NOT_REFRESHED_YET } from '../reactive.js'
-import type { SynchronousDatabaseWrapper } from '../SynchronousDatabaseWrapper.js'
-import { emptyDebugInfo as makeEmptyDebugInfo } from '../SynchronousDatabaseWrapper.js'
+import type { SqliteDbWrapper } from '../SqliteDbWrapper.js'
+import { emptyDebugInfo as makeEmptyDebugInfo } from '../SqliteDbWrapper.js'
 import type { ReferenceCountedSet } from '../utils/data-structures.js'
 
 type IStore = {
   clientSession: ClientSession
   reactivityGraph: ReactivityGraph
-  syncDbWrapper: SynchronousDatabaseWrapper
+  sqliteDbWrapper: SqliteDbWrapper
   activeQueries: ReferenceCountedSet<LiveQuery<any>>
+  syncProcessor: ClientSessionSyncProcessor
 }
 
 type Unsub = () => void
@@ -34,13 +36,17 @@ export const connectDevtoolsToStore = ({
   storeDevtoolsChannel,
   store,
 }: {
-  storeDevtoolsChannel: WebChannel.WebChannel<Devtools.MessageToAppClientSession, Devtools.MessageFromAppClientSession>
+  storeDevtoolsChannel: WebChannel.WebChannel<
+    Devtools.ClientSession.MessageToApp,
+    Devtools.ClientSession.MessageFromApp
+  >
   store: IStore
 }) =>
   Effect.gen(function* () {
     const reactivityGraphSubcriptions: SubMap = new Map()
     const liveQueriesSubscriptions: SubMap = new Map()
     const debugInfoHistorySubscriptions: SubMap = new Map()
+    const syncHeadClientSessionSubscriptions: SubMap = new Map()
 
     const { clientId, sessionId } = store.clientSession
 
@@ -49,13 +55,16 @@ export const connectDevtoolsToStore = ({
         reactivityGraphSubcriptions.forEach((unsub) => unsub())
         liveQueriesSubscriptions.forEach((unsub) => unsub())
         debugInfoHistorySubscriptions.forEach((unsub) => unsub())
+        syncHeadClientSessionSubscriptions.forEach((unsub) => unsub())
       }),
     )
 
-    const sendToDevtools = (message: Devtools.MessageFromAppClientSession) =>
+    const handledRequestIds = new Set<RequestId>()
+
+    const sendToDevtools = (message: Devtools.ClientSession.MessageFromApp) =>
       storeDevtoolsChannel.send(message).pipe(Effect.tapCauseLogPretty, Effect.runFork)
 
-    const onMessage = (decodedMessage: typeof Devtools.MessageToAppClientSession.Type) => {
+    const onMessage = (decodedMessage: typeof Devtools.ClientSession.MessageToApp.Type) => {
       // console.debug('@livestore/livestore:store:devtools:onMessage', decodedMessage)
 
       if (decodedMessage.clientId !== clientId || decodedMessage.sessionId !== sessionId) {
@@ -63,18 +72,29 @@ export const connectDevtoolsToStore = ({
         return
       }
 
-      if (decodedMessage._tag === 'LSD.Disconnect') {
+      if (decodedMessage._tag === 'LSD.ClientSession.Disconnect') {
         // console.error('TODO handle disconnect properly in store')
         return
       }
 
       const requestId = decodedMessage.requestId
 
+      // TODO we should try to move the duplicate message handling on the webmesh layer
+      // So far I could only observe this problem with webmesh proxy channels (e.g. for Expo)
+      // Proof: https://share.cleanshot.com/V9G87B0B
+      // Also see `leader-worker-devtools.ts` for same problem
+      if (handledRequestIds.has(requestId)) {
+        return
+      }
+
+      handledRequestIds.add(requestId)
+
       const requestIdleCallback = globalThis.requestIdleCallback ?? ((cb: () => void) => cb())
 
       switch (decodedMessage._tag) {
-        case 'LSD.ReactivityGraphSubscribe': {
+        case 'LSD.ClientSession.ReactivityGraphSubscribe': {
           const includeResults = decodedMessage.includeResults
+          const { subscriptionId } = decodedMessage
 
           const send = () =>
             // In order to not add more work to the current tick, we use requestIdleCallback
@@ -82,12 +102,13 @@ export const connectDevtoolsToStore = ({
             requestIdleCallback(
               () =>
                 sendToDevtools(
-                  Devtools.ReactivityGraphRes.make({
+                  Devtools.ClientSession.ReactivityGraphRes.make({
                     reactivityGraph: store.reactivityGraph.getSnapshot({ includeResults }),
-                    requestId,
+                    requestId: nanoid(10),
                     clientId,
                     sessionId,
                     liveStoreVersion,
+                    subscriptionId,
                   }),
                 ),
               { timeout: 500 },
@@ -100,14 +121,14 @@ export const connectDevtoolsToStore = ({
           // This might need to be tweaked further and possibly be exposed to the user in some way.
           const throttledSend = throttle(send, 20)
 
-          reactivityGraphSubcriptions.set(requestId, store.reactivityGraph.subscribeToRefresh(throttledSend))
+          reactivityGraphSubcriptions.set(subscriptionId, store.reactivityGraph.subscribeToRefresh(throttledSend))
 
           break
         }
-        case 'LSD.DebugInfoReq': {
+        case 'LSD.ClientSession.DebugInfoReq': {
           sendToDevtools(
-            Devtools.DebugInfoRes.make({
-              debugInfo: store.syncDbWrapper.debugInfo,
+            Devtools.ClientSession.DebugInfoRes.make({
+              debugInfo: store.sqliteDbWrapper.debugInfo,
               requestId,
               clientId,
               sessionId,
@@ -116,28 +137,30 @@ export const connectDevtoolsToStore = ({
           )
           break
         }
-        case 'LSD.DebugInfoHistorySubscribe': {
+        case 'LSD.ClientSession.DebugInfoHistorySubscribe': {
+          const { subscriptionId } = decodedMessage
           const buffer: DebugInfo[] = []
           let hasStopped = false
           let tickHandle: number | undefined
 
           const tick = () => {
-            buffer.push(store.syncDbWrapper.debugInfo)
+            buffer.push(store.sqliteDbWrapper.debugInfo)
 
             // NOTE this resets the debug info, so all other "readers" e.g. in other `requestAnimationFrame` loops,
             // will get the empty debug info
             // TODO We need to come up with a more graceful way to do store. Probably via a single global
             // `requestAnimationFrame` loop that is passed in somehow.
-            store.syncDbWrapper.debugInfo = makeEmptyDebugInfo()
+            store.sqliteDbWrapper.debugInfo = makeEmptyDebugInfo()
 
             if (buffer.length > 10) {
               sendToDevtools(
-                Devtools.DebugInfoHistoryRes.make({
+                Devtools.ClientSession.DebugInfoHistoryRes.make({
                   debugInfoHistory: buffer,
-                  requestId,
+                  requestId: nanoid(10),
                   clientId,
                   sessionId,
                   liveStoreVersion,
+                  subscriptionId,
                 }),
               )
               buffer.length = 0
@@ -158,44 +181,53 @@ export const connectDevtoolsToStore = ({
             }
           }
 
-          debugInfoHistorySubscriptions.set(requestId, unsub)
+          debugInfoHistorySubscriptions.set(subscriptionId, unsub)
 
           break
         }
-        case 'LSD.DebugInfoHistoryUnsubscribe': {
-          // NOTE given WebMesh channels have persistent retry behaviour, it can happen that a previous
-          // WebMesh channel will send a unsubscribe message for an old requestId. Thus the `?.()` handling.
-          debugInfoHistorySubscriptions.get(requestId)?.()
-          debugInfoHistorySubscriptions.delete(requestId)
+        case 'LSD.ClientSession.DebugInfoHistoryUnsubscribe': {
+          const { subscriptionId } = decodedMessage
+          // NOTE given Webmesh channels have persistent retry behaviour, it can happen that a previous
+          // Webmesh channel will send a unsubscribe message for an old requestId. Thus the `?.()` handling.
+          debugInfoHistorySubscriptions.get(subscriptionId)?.()
+          debugInfoHistorySubscriptions.delete(subscriptionId)
           break
         }
-        case 'LSD.DebugInfoResetReq': {
-          store.syncDbWrapper.debugInfo.slowQueries.clear()
-          sendToDevtools(Devtools.DebugInfoResetRes.make({ requestId, clientId, sessionId, liveStoreVersion }))
+        case 'LSD.ClientSession.DebugInfoResetReq': {
+          store.sqliteDbWrapper.debugInfo.slowQueries.clear()
+          sendToDevtools(
+            Devtools.ClientSession.DebugInfoResetRes.make({ requestId, clientId, sessionId, liveStoreVersion }),
+          )
           break
         }
-        case 'LSD.DebugInfoRerunQueryReq': {
+        case 'LSD.ClientSession.DebugInfoRerunQueryReq': {
           const { queryStr, bindValues, queriedTables } = decodedMessage
-          store.syncDbWrapper.select(queryStr, { bindValues, queriedTables, skipCache: true })
-          sendToDevtools(Devtools.DebugInfoRerunQueryRes.make({ requestId, clientId, sessionId, liveStoreVersion }))
+          store.sqliteDbWrapper.select(queryStr, bindValues, { queriedTables, skipCache: true })
+          sendToDevtools(
+            Devtools.ClientSession.DebugInfoRerunQueryRes.make({ requestId, clientId, sessionId, liveStoreVersion }),
+          )
           break
         }
-        case 'LSD.ReactivityGraphUnsubscribe': {
-          // NOTE given WebMesh channels have persistent retry behaviour, it can happen that a previous
-          // WebMesh channel will send a unsubscribe message for an old requestId. Thus the `?.()` handling.
-          reactivityGraphSubcriptions.get(requestId)?.()
+        case 'LSD.ClientSession.ReactivityGraphUnsubscribe': {
+          const { subscriptionId } = decodedMessage
+          // NOTE given Webmesh channels have persistent retry behaviour, it can happen that a previous
+          // Webmesh channel will send a unsubscribe message for an old requestId. Thus the `?.()` handling.
+          reactivityGraphSubcriptions.get(subscriptionId)?.()
+          reactivityGraphSubcriptions.delete(subscriptionId)
           break
         }
-        case 'LSD.LiveQueriesSubscribe': {
+        case 'LSD.ClientSession.LiveQueriesSubscribe': {
+          const { subscriptionId } = decodedMessage
           const send = () =>
             requestIdleCallback(
               () =>
                 sendToDevtools(
-                  Devtools.LiveQueriesRes.make({
+                  Devtools.ClientSession.LiveQueriesRes.make({
                     liveQueries: [...store.activeQueries].map((q) => ({
                       _tag: q._tag,
                       id: q.id,
                       label: q.label,
+                      hash: q.def.hash,
                       runs: q.runs,
                       executionTimes: q.executionTimes.map((_) => Number(_.toString().slice(0, 5))),
                       lastestResult:
@@ -204,10 +236,11 @@ export const connectDevtoolsToStore = ({
                           : q.results$.previousResult,
                       activeSubscriptions: Array.from(q.activeSubscriptions),
                     })),
-                    requestId,
+                    requestId: nanoid(10),
                     liveStoreVersion,
                     clientId,
                     sessionId,
+                    subscriptionId,
                   }),
                 ),
               { timeout: 500 },
@@ -218,18 +251,63 @@ export const connectDevtoolsToStore = ({
           // Same as in the reactivity graph subscription case above, we need to throttle the updates
           const throttledSend = throttle(send, 20)
 
-          liveQueriesSubscriptions.set(requestId, store.reactivityGraph.subscribeToRefresh(throttledSend))
+          liveQueriesSubscriptions.set(subscriptionId, store.reactivityGraph.subscribeToRefresh(throttledSend))
+
+          break
+        }
+        case 'LSD.ClientSession.LiveQueriesUnsubscribe': {
+          const { subscriptionId } = decodedMessage
+          // NOTE given Webmesh channels have persistent retry behaviour, it can happen that a previous
+          // Webmesh channel will send a unsubscribe message for an old requestId. Thus the `?.()` handling.
+          liveQueriesSubscriptions.get(subscriptionId)?.()
+          liveQueriesSubscriptions.delete(subscriptionId)
+          break
+        }
+        case 'LSD.ClientSession.SyncHeadSubscribe': {
+          const { subscriptionId } = decodedMessage
+          const send = (syncState: SyncState.SyncState) =>
+            sendToDevtools(
+              Devtools.ClientSession.SyncHeadRes.make({
+                local: syncState.localHead,
+                upstream: syncState.upstreamHead,
+                requestId: nanoid(10),
+                clientId,
+                sessionId,
+                liveStoreVersion,
+                subscriptionId,
+              }),
+            )
+
+          send(store.syncProcessor.syncState.pipe(Effect.runSync))
+
+          syncHeadClientSessionSubscriptions.set(
+            subscriptionId,
+            store.syncProcessor.syncState.changes.pipe(
+              Stream.tap((syncState) => send(syncState)),
+              Stream.runDrain,
+              Effect.interruptible,
+              Effect.tapCauseLogPretty,
+              Effect.runCallback,
+            ),
+          )
 
           break
         }
-        case 'LSD.LiveQueriesUnsubscribe': {
-          // NOTE given WebMesh channels have persistent retry behaviour, it can happen that a previous
-          // WebMesh channel will send a unsubscribe message for an old requestId. Thus the `?.()` handling.
-          liveQueriesSubscriptions.get(requestId)?.()
-          liveQueriesSubscriptions.delete(requestId)
+        case 'LSD.ClientSession.SyncHeadUnsubscribe': {
+          const { subscriptionId } = decodedMessage
+          // NOTE given Webmesh channels have persistent retry behaviour, it can happen that a previous
+          // Webmesh channel will send a unsubscribe message for an old requestId. Thus the `?.()` handling.
+          syncHeadClientSessionSubscriptions.get(subscriptionId)?.()
+          syncHeadClientSessionSubscriptions.delete(subscriptionId)
           break
         }
-        // No default
+        case 'LSD.ClientSession.Ping': {
+          sendToDevtools(Devtools.ClientSession.Pong.make({ requestId, clientId, sessionId, liveStoreVersion }))
+          break
+        }
+        default: {
+          console.warn(`[LSD.ClientSession] Unknown message`, decodedMessage)
+        }
       }
     }