diff --git a/packages/core/src/storage/idb.ts b/packages/core/src/storage/idb.ts
index e1b4c001..07d198c7 100644
--- a/packages/core/src/storage/idb.ts
+++ b/packages/core/src/storage/idb.ts
@@ -94,6 +94,12 @@ interface CachedEntity {
     full: tl.TypeUser | tl.TypeChat | null
 }
 
+/**
+ * mtcute storage that uses IndexedDB as a backend.
+ *
+ * This storage is the default one for browsers, and is generally
+ * recommended over local storage based one.
+ */
 export class IdbStorage implements ITelegramStorage {
     private _cache?: LruMap<number, CachedEntity>
 
diff --git a/packages/core/src/storage/json-file.ts b/packages/core/src/storage/json-file.ts
index 09a9996c..54b5b0be 100644
--- a/packages/core/src/storage/json-file.ts
+++ b/packages/core/src/storage/json-file.ts
@@ -5,6 +5,18 @@ import { JsonMemoryStorage } from './json.js'
 
 const EVENTS = ['exit', 'SIGINT', 'SIGUSR1', 'SIGUSR2', 'uncaughtException', 'SIGTERM']
 
+/**
+ * mtcute storage that stores data in a JSON file.
+ *
+ * > **Note**: This storage is **not fully persistent**, meaning that
+ * > some data *will* be lost on restart, including entities cache,
+ * > FSM and rate limiter states, because JSON file would be too large otherwise.
+ * >
+ * > This storage should only be used for testing purposes,
+ * > and should not be used in production. Use e.g. `@mtcute/sqlite` instead.
+ *
+ * @deprecated
+ */
 export class JsonFileStorage extends JsonMemoryStorage {
     private readonly _filename: string
     private readonly _safe: boolean
diff --git a/packages/core/src/storage/json.test.ts b/packages/core/src/storage/json.test.ts
index 0be416af..362b36fe 100644
--- a/packages/core/src/storage/json.test.ts
+++ b/packages/core/src/storage/json.test.ts
@@ -1,7 +1,5 @@
 import { describe, expect, it } from 'vitest'
 
-import { stubPeerUser } from '@mtcute/test'
-
 import { JsonMemoryStorage } from './json.js'
 
 // eslint-disable-next-line no-restricted-globals
@@ -31,8 +29,6 @@ describe('JsonMemoryStorage', () => {
         s.setAuthKeyFor(1, createBuffer([1, 2, 3]))
         // eslint-disable-next-line no-restricted-globals
         s.setTempAuthKeyFor(2, 0, createBuffer([4, 5, 6]), 1234567890)
-        s.setState('someState', 'someValue')
-        s.updatePeers([{ ...stubPeerUser, updated: 0 }])
 
         const json = s.saveJson()
         const s2 = new ExtJsonMemoryStorage()
diff --git a/packages/core/src/storage/json.ts b/packages/core/src/storage/json.ts
index 8e6570a8..55bd1628 100644
--- a/packages/core/src/storage/json.ts
+++ b/packages/core/src/storage/json.ts
@@ -26,13 +26,13 @@ export class JsonMemoryStorage extends MemoryStorage {
                         return ret
                     }
                     case 'authKeysTempExpiry':
+                    case 'pts':
+                        return new Map(Object.entries(value as Record<string, string>))
                     case 'phoneIndex':
                     case 'usernameIndex':
-                    case 'pts':
                     case 'fsm':
                     case 'rl':
                     case 'refs':
-                        return new Map(Object.entries(value as Record<string, string>))
                     case 'entities':
                         return new Map()
                 }
diff --git a/packages/core/src/storage/localstorage.ts b/packages/core/src/storage/localstorage.ts
index d041740c..6a1e8f23 100644
--- a/packages/core/src/storage/localstorage.ts
+++ b/packages/core/src/storage/localstorage.ts
@@ -1,6 +1,18 @@
 import { MtUnsupportedError } from '../types/index.js'
 import { JsonMemoryStorage } from './json.js'
 
+/**
+ * mtcute storage that stores data in a `localStorage` key.
+ *
+ * > **Note**: This storage is **not fully persistent**, meaning that
+ * > some data *will* be lost on restart, including entities cache,
+ * > FSM and rate limiter states, because the JSON would be too large otherwise.
+ * >
+ * > This storage should only be used for testing purposes,
+ * > and should not be used in production. Use e.g. {@link IdbStorage} instead.
+ *
+ * @deprecated
+ */
 export class LocalstorageStorage extends JsonMemoryStorage {
     private readonly _key: string