@livestore/livestore 0.4.0-dev.2 → 0.4.0-dev.20

package/src/reactive.ts

@@ -22,7 +22,7 @@
 // - At every thunk we check value equality with the previous value and cutoff propagation if possible.
 
 import { BoundArray } from '@livestore/common'
-import { deepEqual, shouldNeverHappen } from '@livestore/utils'
+import { deepEqual, omitUndefineds, shouldNeverHappen } from '@livestore/utils'
 import type { Types } from '@livestore/utils/effect'
 import type * as otel from '@opentelemetry/api'
 // import { getDurationMsFromSpan } from './otel.ts'
@@ -45,9 +45,9 @@ export type Ref<T, TContext, TDebugRefreshReason extends DebugRefreshReason> = {
   computeResult: () => T
   sub: Set<Atom<any, TContext, TDebugRefreshReason>> // always empty
   super: Set<Thunk<any, TContext, TDebugRefreshReason> | Effect<TDebugRefreshReason>>
-  label?: string
+  label?: string | undefined
   /** Container for meta information (e.g. the LiveStore Store) */
-  meta?: any
+  meta?: any | undefined
   equal: (a: T, b: T) => boolean
   refreshes: number
 }
@@ -61,9 +61,9 @@ export type Thunk<TResult, TContext, TDebugRefreshReason extends DebugRefreshRea
   previousResult: TResult | NOT_REFRESHED_YET
   sub: Set<Atom<any, TContext, TDebugRefreshReason>>
   super: Set<Thunk<any, TContext, TDebugRefreshReason> | Effect<TDebugRefreshReason>>
-  label?: string
+  label?: string | undefined
   /** Container for meta information (e.g. the LiveStore Store) */
-  meta?: any
+  meta?: any | undefined
   equal: (a: TResult, b: TResult) => boolean
   recomputations: number
 
@@ -80,7 +80,7 @@ export type Effect<TDebugRefreshReason extends DebugRefreshReason> = {
   isDestroyed: boolean
   doEffect: (otelContext?: otel.Context | undefined, debugRefreshReason?: TDebugRefreshReason | undefined) => void
   sub: Set<Atom<any, TODO, TODO>>
-  label?: string
+  label?: string | undefined
   invocations: number
 }
 
@@ -103,10 +103,10 @@ export type DebugRefreshReasonBase =
   /** Usually in response to some `commit` calls with `skipRefresh: true` */
   | {
       _tag: 'runDeferredEffects'
-      originalRefreshReasons?: ReadonlyArray<DebugRefreshReasonBase>
-      manualRefreshReason?: DebugRefreshReasonBase
+      originalRefreshReasons?: ReadonlyArray<DebugRefreshReasonBase> | undefined
+      manualRefreshReason?: DebugRefreshReasonBase | undefined
     }
-  | { _tag: 'makeThunk'; label?: string }
+  | { _tag: 'makeThunk'; label?: string | undefined }
   | { _tag: 'unknown' }
 
 export type DebugRefreshReason<T extends string = string> = DebugRefreshReasonBase | { _tag: T }
@@ -135,7 +135,7 @@ const unknownRefreshReason = () => {
   return { _tag: 'unknown' as const }
 }
 
-export type EncodedOption<A> = { _tag: 'Some'; value?: A } | { _tag: 'None' }
+export type EncodedOption<A> = { _tag: 'Some'; value?: A | undefined } | { _tag: 'None' }
 const encodedOptionSome = <A>(value: A): EncodedOption<A> => ({ _tag: 'Some', value })
 const encodedOptionNone = <A>(): EncodedOption<A> => ({ _tag: 'None' })
 
@@ -192,7 +192,7 @@ export const __resetIds = () => {
 export class ReactiveGraph<
   TDebugRefreshReason extends DebugRefreshReason,
   TDebugThunkInfo extends DebugThunkInfo,
-  TContext extends { effectsWrapper?: (runEffects: () => void) => void } = {},
+  TContext extends { effectsWrapper?: ((runEffects: () => void) => void) | undefined } = {},
 > {
   id = uniqueGraphId()
 
@@ -211,10 +211,8 @@ export class ReactiveGraph<
 
   private refreshCallbacks: Set<() => void> = new Set()
 
-  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: for debugging
   private nodeIdCounter = 0
   private uniqueNodeId = () => `node-${++this.nodeIdCounter}`
-  // biome-ignore lint/correctness/noUnusedPrivateClassMembers: for debugging
   private refreshInfoIdCounter = 0
   private uniqueRefreshInfoId = () => `refresh-info-${++this.refreshInfoIdCounter}`
 
@@ -231,8 +229,7 @@ export class ReactiveGraph<
       computeResult: () => ref.previousResult,
       sub: new Set(),
       super: new Set(),
-      label: options?.label,
-      meta: options?.meta,
+      ...omitUndefineds({ label: options?.label, meta: options?.meta }),
       equal: options?.equal ?? deepEqual,
       refreshes: 0,
     }
@@ -267,8 +264,11 @@ export class ReactiveGraph<
       computeResult: (otelContext, debugRefreshReason) => {
         if (thunk.isDirty) {
           const neededCurrentRefresh = this.currentDebugRefresh === undefined
+          let localDebugRefresh: { refreshedAtoms: any[]; startMs: number } | undefined
           if (neededCurrentRefresh) {
-            this.currentDebugRefresh = { refreshedAtoms: [], startMs: performance.now() }
+            // Use local variable to prevent corruption from nested computations
+            localDebugRefresh = { refreshedAtoms: [], startMs: performance.now() }
+            this.currentDebugRefresh = localDebugRefresh
           }
 
           // Reset previous subcomputations as we're about to re-add them as part of the `doEffect` call below
@@ -300,15 +300,20 @@ export class ReactiveGraph<
             debugInfo: debugInfo ?? (unknownRefreshReason() as TDebugThunkInfo),
           } satisfies AtomDebugInfo<TDebugThunkInfo>
 
-          this.currentDebugRefresh!.refreshedAtoms.push(debugInfoForAtom)
+          // Use currentDebugRefresh if available (could be from parent or local)
+          const debugRefresh = localDebugRefresh ?? this.currentDebugRefresh
+          if (debugRefresh) {
+            debugRefresh.refreshedAtoms.push(debugInfoForAtom)
+          }
 
           thunk.isDirty = false
           thunk.previousResult = result
           thunk.recomputations++
 
-          if (neededCurrentRefresh) {
-            const refreshedAtoms = this.currentDebugRefresh!.refreshedAtoms
-            const durationMs = performance.now() - this.currentDebugRefresh!.startMs
+          if (neededCurrentRefresh && localDebugRefresh) {
+            // Use local reference which can't be corrupted by nested calls
+            const refreshedAtoms = localDebugRefresh.refreshedAtoms
+            const durationMs = performance.now() - localDebugRefresh.startMs
             this.currentDebugRefresh = undefined
 
             this.debugRefreshInfos.push({
@@ -330,8 +335,7 @@ export class ReactiveGraph<
       sub: new Set(),
       super: new Set(),
       recomputations: 0,
-      label: options?.label,
-      meta: options?.meta,
+      ...omitUndefineds({ label: options?.label, meta: options?.meta }),
       equal: options?.equal ?? deepEqual,
       __getResult: getResult,
     }
@@ -407,7 +411,7 @@ export class ReactiveGraph<
         doEffect(getAtom as GetAtom, otelContext, debugRefreshReason)
       },
       sub: new Set(),
-      label: options?.label,
+      ...omitUndefineds({ label: options?.label }),
       invocations: 0,
     }
 
@@ -461,7 +465,7 @@ export class ReactiveGraph<
     } else {
       this.runEffects(effectsToRefresh, {
         debugRefreshReason: options?.debugRefreshReason ?? (unknownRefreshReason() as TDebugRefreshReason),
-        otelContext: options?.otelContext,
+        ...omitUndefineds({ otelContext: options?.otelContext }),
       })
     }
   }
@@ -475,15 +479,21 @@ export class ReactiveGraph<
   ) => {
     const effectsWrapper = this.context?.effectsWrapper ?? ((runEffects: () => void) => runEffects())
     effectsWrapper(() => {
-      this.currentDebugRefresh = { refreshedAtoms: [], startMs: performance.now() }
-
-      for (const effect of effectsToRefresh) {
-        effect.doEffect(options?.otelContext, options.debugRefreshReason)
+      // Capture debug state in local variable to prevent corruption from nested runEffects
+      const previousDebugRefresh = this.currentDebugRefresh
+      const localDebugRefresh = { refreshedAtoms: [], startMs: performance.now() }
+      this.currentDebugRefresh = localDebugRefresh
+
+      try {
+        for (const effect of effectsToRefresh) {
+          effect.doEffect(options?.otelContext, options.debugRefreshReason)
+        }
+      } finally {
+        this.currentDebugRefresh = previousDebugRefresh
       }
 
-      const refreshedAtoms = this.currentDebugRefresh.refreshedAtoms
-      const durationMs = performance.now() - this.currentDebugRefresh.startMs
-      this.currentDebugRefresh = undefined
+      const refreshedAtoms = localDebugRefresh.refreshedAtoms
+      const durationMs = performance.now() - localDebugRefresh.startMs
 
       const refreshDebugInfo: RefreshDebugInfo<TDebugRefreshReason, TDebugThunkInfo> = {
         id: this.uniqueRefreshInfoId(),
@@ -509,9 +519,9 @@ export class ReactiveGraph<
         debugRefreshReason: {
           _tag: 'runDeferredEffects',
           originalRefreshReasons: Array.from(debugRefreshReasons) as ReadonlyArray<DebugRefreshReasonBase>,
-          manualRefreshReason: options?.debugRefreshReason,
-        } as TDebugRefreshReason,
-        otelContext: options?.otelContext,
+          ...omitUndefineds({ manualRefreshReason: options?.debugRefreshReason }),
+        } as unknown as TDebugRefreshReason,
+        ...omitUndefineds({ otelContext: options?.otelContext }),
       })
     }
   }
@@ -641,8 +651,7 @@ const serializeAtom = (atom: Atom<any, unknown, any>, includeResult: boolean): S
     return {
       _tag: atom._tag,
       id: atom.id,
-      label: atom.label,
-      meta: atom.meta,
+      ...omitUndefineds({ label: atom.label, meta: atom.meta }),
       isDirty: atom.isDirty,
       sub,
       super: super_,
@@ -655,8 +664,7 @@ const serializeAtom = (atom: Atom<any, unknown, any>, includeResult: boolean): S
   return {
     _tag: 'thunk',
     id: atom.id,
-    label: atom.label,
-    meta: atom.meta,
+    ...omitUndefineds({ label: atom.label, meta: atom.meta }),
     isDirty: atom.isDirty,
     sub,
     super: super_,
@@ -676,7 +684,7 @@ const serializeEffect = (effect: Effect<any>): SerializedEffect => {
   return {
     _tag: effect._tag,
     id: effect.id,
-    label: effect.label,
+    ...omitUndefineds({ label: effect.label }),
     sub,
     invocations: effect.invocations,
     isDestroyed: effect.isDestroyed,

package/src/store/create-store.ts

@@ -5,13 +5,17 @@ import {
   type ClientSessionDevtoolsChannel,
   type ClientSessionSyncProcessorSimulationParams,
   type IntentionalShutdownCause,
+  type InvalidPullError,
+  type IsOfflineError,
+  LogConfig,
+  type MaterializeError,
   type MigrationsReport,
   provideOtel,
   type SyncError,
-  UnexpectedError,
+  UnknownError,
 } from '@livestore/common'
 import type { LiveStoreSchema } from '@livestore/common/schema'
-import { isDevEnv, LS_DEV } from '@livestore/utils'
+import { isDevEnv, LS_DEV, omitUndefineds } from '@livestore/utils'
 import {
   Context,
   Deferred,
@@ -20,12 +24,10 @@ import {
   Fiber,
   identity,
   Layer,
-  Logger,
-  LogLevel,
   OtelTracer,
   Queue,
   Runtime,
-  type Schema,
+  Schema,
   Scope,
   TaskTracing,
 } from '@livestore/utils/effect'
@@ -39,6 +41,7 @@ import type {
   OtelOptions,
   ShutdownDeferred,
 } from './store-types.ts'
+import { StoreInternalsSymbol } from './store-types.ts'
 
 export const DEFAULT_PARAMS = {
   leaderPushBatchSize: 100,
@@ -57,10 +60,14 @@ export class LiveStoreContextRunning extends Context.Tag('@livestore/livestore/e
 
 export class DeferredStoreContext extends Context.Tag('@livestore/livestore/effect/DeferredStoreContext')<
   DeferredStoreContext,
-  Deferred.Deferred<LiveStoreContextRunning['Type'], UnexpectedError>
+  Deferred.Deferred<LiveStoreContextRunning['Type'], UnknownError>
 >() {}
 
-export type LiveStoreContextProps<TSchema extends LiveStoreSchema, TContext = {}> = {
+export type LiveStoreContextProps<
+  TSchema extends LiveStoreSchema,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+> = {
   schema: TSchema
   /**
    * The `storeId` can be used to isolate multiple stores from each other.
@@ -85,9 +92,32 @@ export type LiveStoreContextProps<TSchema extends LiveStoreSchema, TContext = {}
   disableDevtools?: boolean | 'auto'
   onBootStatus?: (status: BootStatus) => void
   batchUpdates: (run: () => void) => void
+  /**
+   * Schema describing the shape of the sync payload and used to encode it.
+   *
+   * - If omitted, `Schema.JsonValue` is used (no additional typing/validation).
+   * - Prefer exporting a schema from your app (e.g. `export const SyncPayload = Schema.Struct({ authToken: Schema.String })`)
+   *   and pass it here to get end-to-end type safety and validation.
+   */
+  syncPayloadSchema?: TSyncPayloadSchema
+  /**
+   * Payload that is sent to the sync backend during connection establishment.
+   *
+   * - Its TypeScript type is inferred from `syncPayloadSchema` (i.e. `typeof SyncPayload.Type`).
+   * - At runtime this value is encoded with `syncPayloadSchema` before being handed to the adapter.
+   *
+   * Example:
+   *   const SyncPayload = Schema.Struct({ authToken: Schema.String })
+   *   <LiveStoreProvider syncPayloadSchema={SyncPayload} syncPayload={{ authToken: '...' }} />
+   */
+  syncPayload?: Schema.Schema.Type<TSyncPayloadSchema>
 }
 
-export interface CreateStoreOptions<TSchema extends LiveStoreSchema, TContext = {}> {
+export interface CreateStoreOptions<
+  TSchema extends LiveStoreSchema,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+> extends LogConfig.WithLoggerOptions {
   schema: TSchema
   adapter: Adapter
   storeId: string
@@ -116,11 +146,23 @@ export interface CreateStoreOptions<TSchema extends LiveStoreSchema, TContext =
    */
   confirmUnsavedChanges?: boolean
   /**
-   * Payload that will be passed to the sync backend when connecting
+   * Schema describing the shape of the sync payload and used to encode it.
+   *
+   * - If omitted, `Schema.JsonValue` is used (no additional typing/validation).
+   * - Prefer exporting a schema from your app (e.g. `export const SyncPayload = Schema.Struct({ authToken: Schema.String })`)
+   *   and pass it here to get end-to-end type safety and validation.
+   */
+  syncPayloadSchema?: TSyncPayloadSchema
+  /**
+   * Payload that is sent to the sync backend during connection establishment.
+   *
+   * - Its TypeScript type is inferred from `syncPayloadSchema` (i.e. `typeof SyncPayload.Type`).
+   * - At runtime this value is encoded with `syncPayloadSchema` and carried through the adapter
+   *   to the backend where it can be decoded with the same schema.
    *
    * @default undefined
    */
-  syncPayload?: Schema.JsonValue
+  syncPayload?: Schema.Schema.Type<TSyncPayloadSchema>
   params?: {
     leaderPushBatchSize?: number
     simulation?: {
@@ -132,15 +174,25 @@ export interface CreateStoreOptions<TSchema extends LiveStoreSchema, TContext =
   }
 }
 
+export type CreateStoreOptionsPromise<
+  TSchema extends LiveStoreSchema = LiveStoreSchema.Any,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+> = CreateStoreOptions<TSchema, TContext, TSyncPayloadSchema> & {
+  signal?: AbortSignal
+  otelOptions?: Partial<OtelOptions>
+}
+
 /** Create a new LiveStore Store */
-export const createStorePromise = async <TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}>({
+export const createStorePromise = async <
+  TSchema extends LiveStoreSchema = LiveStoreSchema.Any,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+>({
   signal,
   otelOptions,
   ...options
-}: CreateStoreOptions<TSchema, TContext> & {
-  signal?: AbortSignal
-  otelOptions?: Partial<OtelOptions>
-}): Promise<Store<TSchema, TContext>> =>
+}: CreateStoreOptionsPromise<TSchema, TContext, TSyncPayloadSchema>): Promise<Store<TSchema, TContext>> =>
   Effect.gen(function* () {
     const scope = yield* Scope.make()
     const runtime = yield* Effect.runtime()
@@ -156,15 +208,18 @@ export const createStorePromise = async <TSchema extends LiveStoreSchema = LiveS
     Effect.withSpan('createStore', {
       attributes: { storeId: options.storeId, disableDevtools: options.disableDevtools },
     }),
-    provideOtel({ parentSpanContext: otelOptions?.rootSpanContext, otelTracer: otelOptions?.tracer }),
+    provideOtel(omitUndefineds({ parentSpanContext: otelOptions?.rootSpanContext, otelTracer: otelOptions?.tracer })),
     Effect.tapCauseLogPretty,
     Effect.annotateLogs({ thread: 'window' }),
-    Effect.provide(Logger.prettyWithThread('window')),
-    Logger.withMinimumLogLevel(LogLevel.Debug),
+    LogConfig.withLoggerConfig(options, { threadName: 'window' }),
     Effect.runPromise,
   )
 
-export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}>({
+export const createStore = <
+  TSchema extends LiveStoreSchema = LiveStoreSchema.Any,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+>({
   schema,
   adapter,
   storeId,
@@ -178,9 +233,10 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
   debug,
   confirmUnsavedChanges = true,
   syncPayload,
-}: CreateStoreOptions<TSchema, TContext>): Effect.Effect<
+  syncPayloadSchema,
+}: CreateStoreOptions<TSchema, TContext, TSyncPayloadSchema>): Effect.Effect<
   Store<TSchema, TContext>,
-  UnexpectedError,
+  UnknownError,
   Scope.Scope | OtelTracer.OtelTracer
 > =>
   Effect.gen(function* () {
@@ -191,6 +247,7 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
     yield* Effect.addFinalizer((_) => Scope.close(lifetimeScope, _))
 
     const debugInstanceId = debug?.instanceId ?? nanoid(10)
+    const resolvedSyncPayloadSchema = (syncPayloadSchema ?? Schema.JsonValue) as TSyncPayloadSchema
 
     return yield* Effect.gen(function* () {
       const span = yield* OtelTracer.currentOtelSpan.pipe(Effect.orDie)
@@ -217,7 +274,12 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
 
       const runtime = yield* Effect.runtime<Scope.Scope>()
 
-      const shutdown = (exit: Exit.Exit<IntentionalShutdownCause, UnexpectedError | SyncError>) =>
+      const shutdown = (
+        exit: Exit.Exit<
+          IntentionalShutdownCause,
+          UnknownError | MaterializeError | SyncError | InvalidPullError | IsOfflineError
+        >,
+      ) =>
         Effect.gen(function* () {
           yield* Scope.close(lifetimeScope, exit).pipe(
             Effect.logWarnIfTakesLongerThan({ label: '@livestore/livestore:shutdown', duration: 500 }),
@@ -242,6 +304,11 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
           Fiber.join,
         )
 
+      const syncPayloadEncoded =
+        syncPayload === undefined
+          ? undefined
+          : yield* Schema.encode(resolvedSyncPayloadSchema)(syncPayload).pipe(UnknownError.mapToUnknownError)
+
       const clientSession: ClientSession = yield* adapter({
         schema,
         storeId,
@@ -250,7 +317,8 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
         shutdown,
         connectDevtoolsToStore: connectDevtoolsToStore_,
         debugInstanceId,
-        syncPayload,
+        syncPayloadSchema: resolvedSyncPayloadSchema,
+        syncPayloadEncoded,
       }).pipe(Effect.withPerformanceMeasure('livestore:makeAdapter'), Effect.withSpan('createStore:makeAdapter'))
 
       if (LS_DEV && clientSession.leaderThread.initialState.migrationsReport.migrations.length > 0) {
@@ -280,19 +348,19 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
         storeId,
         params: {
           leaderPushBatchSize: params?.leaderPushBatchSize ?? DEFAULT_PARAMS.leaderPushBatchSize,
-          simulation: params?.simulation,
+          ...omitUndefineds({ simulation: params?.simulation }),
         },
       })
 
       // Starts background fibers (syncing, event processing, etc) for store
-      yield* store.boot
+      yield* store[StoreInternalsSymbol].boot
 
       if (boot !== undefined) {
         // TODO also incorporate `boot` function progress into `bootStatusQueue`
         yield* Effect.tryAll(() =>
           boot(store, { migrationsReport: clientSession.leaderThread.initialState.migrationsReport, parentSpan: span }),
         ).pipe(
-          UnexpectedError.mapToUnexpectedError,
+          UnknownError.mapToUnknownError,
           Effect.provide(Layer.succeed(LiveStoreContextRunning, { stage: 'running', store: store as any as Store })),
           Effect.withSpan('createStore:boot'),
         )
@@ -303,7 +371,7 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema.An
 
       if (batchUpdates !== undefined) {
         // Replacing the default batchUpdates function with the provided one after boot
-        store.reactivityGraph.context!.effectsWrapper = batchUpdates
+        store[StoreInternalsSymbol].reactivityGraph.context!.effectsWrapper = batchUpdates
       }
 
       yield* Deferred.succeed(storeDeferred, store as any as Store)
@@ -322,7 +390,7 @@ const validateStoreId = (storeId: string) =>
     const validChars = /^[a-zA-Z0-9_-]+$/
 
     if (!validChars.test(storeId)) {
-      return yield* UnexpectedError.make({
+      return yield* UnknownError.make({
         cause: `Invalid storeId: ${storeId}. Only alphanumeric characters, underscores, and hyphens are allowed.`,
         payload: { storeId },
       })

package/src/store/devtools.ts

@@ -1,23 +1,14 @@
-import type { ClientSession, ClientSessionSyncProcessor, DebugInfo, SyncState } from '@livestore/common'
-import { Devtools, liveStoreVersion, UnexpectedError } from '@livestore/common'
+import type { DebugInfo, SyncState } from '@livestore/common'
+import { Devtools, liveStoreVersion, UnknownError } 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.ts'
 import { NOT_REFRESHED_YET } from '../reactive.ts'
-import type { SqliteDbWrapper } from '../SqliteDbWrapper.ts'
 import { emptyDebugInfo as makeEmptyDebugInfo } from '../SqliteDbWrapper.ts'
-import type { ReferenceCountedSet } from '../utils/data-structures.ts'
-
-type IStore = {
-  clientSession: ClientSession
-  reactivityGraph: ReactivityGraph
-  sqliteDbWrapper: SqliteDbWrapper
-  activeQueries: ReferenceCountedSet<LiveQuery<any>>
-  syncProcessor: ClientSessionSyncProcessor
-}
+import type { Store } from './store.ts'
+import { StoreInternalsSymbol } from './store-types.ts'
 
 type Unsub = () => void
 type RequestId = string
@@ -40,7 +31,7 @@ export const connectDevtoolsToStore = ({
     Devtools.ClientSession.MessageToApp,
     Devtools.ClientSession.MessageFromApp
   >
-  store: IStore
+  store: Store
 }) =>
   Effect.gen(function* () {
     const reactivityGraphSubcriptions: SubMap = new Map()
@@ -48,7 +39,7 @@ export const connectDevtoolsToStore = ({
     const debugInfoHistorySubscriptions: SubMap = new Map()
     const syncHeadClientSessionSubscriptions: SubMap = new Map()
 
-    const { clientId, sessionId } = store.clientSession
+    const { clientId, sessionId } = store[StoreInternalsSymbol].clientSession
 
     yield* Effect.addFinalizer(() =>
       Effect.sync(() => {
@@ -73,7 +64,21 @@ export const connectDevtoolsToStore = ({
       }
 
       if (decodedMessage._tag === 'LSD.ClientSession.Disconnect') {
-        // console.error('TODO handle disconnect properly in store')
+        // Gracefully tear down all DevTools subscriptions and close the channel.
+        // This prevents background fibers from lingering after DevTools closes
+        // (e.g. when a window is closed without sending explicit unsubs).
+        for (const unsub of reactivityGraphSubcriptions.values()) unsub()
+        reactivityGraphSubcriptions.clear()
+        for (const unsub of liveQueriesSubscriptions.values()) unsub()
+        liveQueriesSubscriptions.clear()
+        for (const unsub of debugInfoHistorySubscriptions.values()) unsub()
+        debugInfoHistorySubscriptions.clear()
+        for (const unsub of syncHeadClientSessionSubscriptions.values()) unsub()
+        syncHeadClientSessionSubscriptions.clear()
+
+        // Signal the WebChannel to shut down; this causes the `listen` stream
+        // to complete and allows the surrounding scoped fiber to exit.
+        storeDevtoolsChannel.shutdown.pipe(Effect.runFork)
         return
       }
 
@@ -103,7 +108,7 @@ export const connectDevtoolsToStore = ({
               () =>
                 sendToDevtools(
                   Devtools.ClientSession.ReactivityGraphRes.make({
-                    reactivityGraph: store.reactivityGraph.getSnapshot({ includeResults }),
+                    reactivityGraph: store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults }),
                     requestId: nanoid(10),
                     clientId,
                     sessionId,
@@ -121,14 +126,17 @@ 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(subscriptionId, store.reactivityGraph.subscribeToRefresh(throttledSend))
+          reactivityGraphSubcriptions.set(
+            subscriptionId,
+            store[StoreInternalsSymbol].reactivityGraph.subscribeToRefresh(throttledSend),
+          )
 
           break
         }
         case 'LSD.ClientSession.DebugInfoReq': {
           sendToDevtools(
             Devtools.ClientSession.DebugInfoRes.make({
-              debugInfo: store.sqliteDbWrapper.debugInfo,
+              debugInfo: store[StoreInternalsSymbol].sqliteDbWrapper.debugInfo,
               requestId,
               clientId,
               sessionId,
@@ -144,13 +152,13 @@ export const connectDevtoolsToStore = ({
           let tickHandle: number | undefined
 
           const tick = () => {
-            buffer.push(store.sqliteDbWrapper.debugInfo)
+            buffer.push(store[StoreInternalsSymbol].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.sqliteDbWrapper.debugInfo = makeEmptyDebugInfo()
+            store[StoreInternalsSymbol].sqliteDbWrapper.debugInfo = makeEmptyDebugInfo()
 
             if (buffer.length > 10) {
               sendToDevtools(
@@ -194,7 +202,7 @@ export const connectDevtoolsToStore = ({
           break
         }
         case 'LSD.ClientSession.DebugInfoResetReq': {
-          store.sqliteDbWrapper.debugInfo.slowQueries.clear()
+          store[StoreInternalsSymbol].sqliteDbWrapper.debugInfo.slowQueries.clear()
           sendToDevtools(
             Devtools.ClientSession.DebugInfoResetRes.make({ requestId, clientId, sessionId, liveStoreVersion }),
           )
@@ -202,7 +210,10 @@ export const connectDevtoolsToStore = ({
         }
         case 'LSD.ClientSession.DebugInfoRerunQueryReq': {
           const { queryStr, bindValues, queriedTables } = decodedMessage
-          store.sqliteDbWrapper.cachedSelect(queryStr, bindValues, { queriedTables, skipCache: true })
+          store[StoreInternalsSymbol].sqliteDbWrapper.cachedSelect(queryStr, bindValues, {
+            queriedTables,
+            skipCache: true,
+          })
           sendToDevtools(
             Devtools.ClientSession.DebugInfoRerunQueryRes.make({ requestId, clientId, sessionId, liveStoreVersion }),
           )
@@ -223,7 +234,7 @@ export const connectDevtoolsToStore = ({
               () =>
                 sendToDevtools(
                   Devtools.ClientSession.LiveQueriesRes.make({
-                    liveQueries: [...store.activeQueries].map((q) => ({
+                    liveQueries: [...store[StoreInternalsSymbol].activeQueries].map((q) => ({
                       _tag: q._tag,
                       id: q.id,
                       label: q.label,
@@ -251,7 +262,10 @@ 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(subscriptionId, store.reactivityGraph.subscribeToRefresh(throttledSend))
+          liveQueriesSubscriptions.set(
+            subscriptionId,
+            store[StoreInternalsSymbol].reactivityGraph.subscribeToRefresh(throttledSend),
+          )
 
           break
         }
@@ -278,11 +292,11 @@ export const connectDevtoolsToStore = ({
               }),
             )
 
-          send(store.syncProcessor.syncState.pipe(Effect.runSync))
+          send(store[StoreInternalsSymbol].syncProcessor.syncState.pipe(Effect.runSync))
 
           syncHeadClientSessionSubscriptions.set(
             subscriptionId,
-            store.syncProcessor.syncState.changes.pipe(
+            store[StoreInternalsSymbol].syncProcessor.syncState.changes.pipe(
               Stream.tap((syncState) => send(syncState)),
               Stream.runDrain,
               Effect.interruptible,
@@ -318,4 +332,4 @@ export const connectDevtoolsToStore = ({
       Stream.runDrain,
       Effect.withSpan('LSD.devtools.onMessage'),
     )
-  }).pipe(UnexpectedError.mapToUnexpectedError, Effect.withSpan('LSD.devtools.connectStoreToDevtools'))
+  }).pipe(UnknownError.mapToUnknownError, Effect.withSpan('LSD.devtools.connectStoreToDevtools'))