Apply feedback (#265)

Author: benitav

client-sdk-references/javascript-web.mdx

@@ -329,7 +329,7 @@ This SDK supports multiple Virtual File Systems (VFS), responsible for storing t
 
 - This system utilizes IndexedDB as its underlying storage mechanism.
 - Multiple tabs are fully supported across most modern browsers.
-- Users may experience stability issues when using Safari.
+- Users may experience stability issues when using Safari. For example, the `RangeError: Maximum call stack size exceeded` error. See [Troubleshooting](/resources/troubleshooting#rangeerror-maximum-call-stack-size-exceeded-on-ios-or-safari) for more details.
 
 #### 2. OPFS-based Alternatives
 

client-sdk-references/javascript-web/usage-examples.mdx

@@ -11,6 +11,7 @@ import JavaScriptCallbackWatch from '/snippets/basic-watch-query-javascript-call
 <Warning>
   * Multiple tab support is not currently available on Android. 
   * For Safari, use the [`OPFSCoopSyncVFS`](/client-sdk-references/javascript-web#sqlite-virtual-file-systems) virtual file system to ensure stable multi-tab functionality.
+  * If you encounter a `RangeError: Maximum call stack size exceeded` error, see [Troubleshooting](/resources/troubleshooting#rangeerror-maximum-call-stack-size-exceeded-on-ios-or-safari) for solutions.
 </Warning>
 
 Using PowerSync between multiple tabs is supported on some web browsers. Multiple tab support relies on shared web workers for database and sync streaming operations. When enabled, shared web workers named `shared-DB-worker-[dbFileName]` and `shared-sync-[dbFileName]` will be created.

resources/troubleshooting.mdx

@@ -6,13 +6,53 @@ sidebarTitle: "Overview"
 
 ## Common issues
 
+<Tip>
+**Tip**: Asking the AI bot on this page, or on the [#gpt-help](https://discord.com/channels/1138230179878154300/1304118313093173329) channel on our [Discord server](https://discord.com/invite/powersync), is a good way to troubleshoot common issues.
+</Tip>
+
 ### `SqliteException: Could not load extension` or similar
 
 This client-side error or similar typically occurs when PowerSync is used in conjunction with either another SQLite library or the standard system SQLite library. PowerSync is generally not compatible with multiple SQLite sources. If another SQLite library exists in your project dependencies, remove it if it is not required. In some cases, there might be other workarounds. For example, in Flutter projects, we've seen this issue with `sqflite 2.2.6`, but `sqflite 2.3.3+1` does not throw the same exception.
 
-<Note>
-Tip: Asking the AI bot on the [#gpt-help](https://discord.com/channels/1138230179878154300/1304118313093173329) channel on our [Discord server](https://discord.com/invite/powersync) is a good way to troubleshoot common issues.
-</Note>
+### `RangeError: Maximum call stack size exceeded` on iOS or Safari
+
+This client-side error commonly occurs when using the PowerSync Web SDK on Safari or iOS (including iOS simulator).
+
+**Solutions:**
+
+1. **Use OPFSCoopSyncVFS (Recommended)**: Switch to the `OPFSCoopSyncVFS` virtual file system, which provides better Safari compatibility and multi-tab support:
+
+```js
+import { PowerSyncDatabase, WASQLiteOpenFactory, WASQLiteVFS } from '@powersync/web';
+
+export const db = new PowerSyncDatabase({
+  schema: AppSchema,
+  database: new WASQLiteOpenFactory({
+    dbFilename: 'exampleVFS.db',
+    vfs: WASQLiteVFS.OPFSCoopSyncVFS,
+    flags: {
+      enableMultiTabs: typeof SharedWorker !== 'undefined'
+    }
+  }),
+  flags: {
+    enableMultiTabs: typeof SharedWorker !== 'undefined'
+  }
+});
+```
+
+2. **Disable Web Workers (Alternative)**: Set the `useWebWorker` flag to `false`, but note that this disables multi-tab support:
+
+```js
+export const db = new PowerSyncDatabase({
+  schema: AppSchema,
+  database: {
+    dbFilename: 'powersync.db'
+  },
+  flags: {
+    useWebWorker: false
+  }
+});
+```
 
 ## Tools
 

usage/use-case-examples/high-performance-diffs.mdx

@@ -9,7 +9,7 @@ description: 'Efficiently get row changes using trigger-based table diffs (JS)'
 While [basic/incremental watch queries](/usage/use-case-examples/watch-queries) enable reactive UIs by automatically re‑running queries when underlying data changes and returning updated results, they don't specify which individual rows were modified. To get these details, you can use [**differential watch queries**](/usage/use-case-examples/watch-queries#differential-watch-queries), which return a structured diff between successive query results. However, on large result sets they can be slow because they re‑run the query and compare full results (e.g., scanning ~1,000 rows to detect 1 new item). That’s why we introduced **trigger‑based table diffs**: a more performant approach that uses SQLite triggers to record changes on a table as they happen. This means that the overhead associated with tracking these changes overhead is more proportional to the number of rows inserted, updated, or deleted.
 
 <Note>
-  **JavaScript Only**: Trigger-based table diffs are available in the JavaScript SDKs starting from:
+  **JavaScript Only**: Trigger-based table diffs are currently only supported in our JavaScript SDKs, starting from:
   * Web v1.26.0
   * React Native v1.24.0
   * Node.js v0.10.0